Mercurial Tutorial

From Arctic Core - the open source AUTOSAR embedded platform

Mercurial is the concurrent versioning system used to maintain the source code of Arctic Core.

Tools

Download the latest TortoiseHG to get a recent copy of Mercurial for Windows.

To get an overview of how to do different things with Mercurial you can take a look at their Quick reference cards and cheat sheets

Mercurial also has built-in help that can be accessed from the command line. For an overview of available commands, issue

 hg help

For detailed help on a specific command type

 hg help command

Checkout

Checkouts in Mercurial are done by cloning, thus setting up a local repository for you to work against.

To clone the Arctic Core repository, run the following from the command line

hg clone http://arccore.com/hg/arc

Staying up to date

Getting changes

To get all remote changes and add them to your local repository, use the command

hg pull

The repository that is searched for changes is the one that your local repository was initially cloned from.

To get changes from another repository, enter the URL to it, like this

hg pull url

Pulls can also be made from bundle files. Just enter the filename like this

hg pull filename

To get a list of changes that would be added in a pull operation, run

hg incoming

Updating working directory

When the changes are in your local repository you need to update the files in your working directory.

Update working directory to tip revision by running

hg update

Alternatively you can have pull perform the update automatically by using

hg pull -u

Merge and conflicts

Whenever you have changes checked in to your local repository that are not part of the main repository that you are pulling from, you will end up having multiple heads in your repository. In this state you won't be able to do an update to extract the new changes into your working copy immediatly.

To join two heads together into one, use

hg merge

This will update your working directory with all changes and perform automatic merging of all unconflicting changes.

The results of a merge is kept in the working directory only, so when the merge is complete you will need to commit. See #Committing below.

hg commit -m"Merge commit message"

This makes sense because even though you pulled changes from some other repository, there is still the job of putting it together with your changes to do, and to commit.

Committing

Please also read the page on contributing to the Arctic Core project.

Committing locally

Changes in your working directory must first be commited to your local repository. From there they can be exported and incorporated into our main repository or other developers' repositories.

To view the status of the files in your working directory, use

hg status

To commit all the changes in the status list, use

hg commit -m "My detailed commit message"

This does not add new files to the repository however.

To add new files to the repository, use

hg add file1 file2 ...

Alternatively use the flag -A to have commit add all new files

hg commit -A -m "My detailed commit message"

To only commit changes from specific files, simply list them at the end of the command, like so

hg commit -A -m "My detailed commit message" file1 file2 ...

Committing to the repository

In order to get your local commits into the main repositories you have to email a patch to the gatekeeper. The e-mail of the gatekeeper is gatekeeper@arccore.com

Rebasing

Instead of cluttering the history with lots and lots of local commit comments, try to collapse them before submittning them.

$ hg history
changeset:   6:7b27cae09209
tag:         tip
user:        mahi
date:        Wed Sep 16 22:12:34 2009 +0200
summary:     - The ARM port is now building (Not on the buildbot though. Have to build the multilib ARM GCC first)

....

changeset:   1:07b0f34acbda
user:        mahi
date:        Sun Sep 13 18:26:23 2009 +0200
summary:     Temp commit for ARM. Probably breaks some other targets.

changeset:   0:8d39b93e55b0
user:        Mattias Ekberg <maek@arccore.com>
date:        Mon Sep 07 16:37:51 2009 +0200
summary:     Initial commit.

Now we want to rebase to version 0 from version 1 and up.

$ hg update -C 0
35 files updated, 0 files merged, 6 files removed, 0 files unresolved

$ hg tag "pre ARM commit"

$ hg rebase -s 1 --collapse
merging arch/arm/arm_cm3/scripts/linkscript_gcc.ldf
merging boards/board_common.mk
merging arch/arm/arm_cm3/scripts/linkscript_gcc.ldf
merging boards/et_stm32_stamp/build_config.mk
merging scripts/rules.mk
merging arch/arm/arm_cm3/kernel/arch.c
merging arch/arm/arm_cm3/kernel/arch_krn.S
merging arch/arm/arm_cm3/kernel/arch.c
merging boards/board_common.mk
merging boards/mpc5567qrtech/build_config.mk
merging common/ramlog.c
merging include/Ramlog.h
merging tools/t32/load.cmm
merging tools/t32/start.cmm
saving bundle to C:\ArcticStudio\Studio\workspace\arc_rebase\.hg\strip-backup\07b0f34acbda-temp
adding branch
adding changesets
adding manifests
adding file changes
added 2 changesets with 41 changes to 41 files
rebase completed

$ hg history
changeset:   2:1dccb77aeec8
tag:         tip
user:        mahi
date:        Wed Sep 16 22:12:34 2009 +0200
summary:     ARM port

changeset:   1:d2392f85d9b7
user:        mahi
date:        Wed Sep 16 22:45:42 2009 +0200
summary:     Added tag pre ARM commit for changeset 8d39b93e55b0

changeset:   0:8d39b93e55b0
tag:         pre ARM commit
user:        Mattias Ekberg <maek@arccore.com>
date:        Mon Sep 07 16:37:51 2009 +0200
summary:     Initial commit.

Creating a patch

A patch is created using the export from the command line.

hg export tip -o mychanges.patch

This patch is then attached to an email and sent to the gatekeeper. For a more automatic approach see #Using Patchbomb.

USE BUNDLES INSTEAD

Using Patchbomb

Patchbomb is a tool that makes committing patches through our repository gatekeeper easy.

To enable patchbomb, create or edit your .hgrc (Located at %REPOSITORYDIR%\.hg\hgrc) to include the following:

[extensions]
hgext.patchbomb = 

[email]
from = Your Name <joe.average@average-isp.com>
to = gatekeeper@arccore.com, recipient2, recipient3, ...
cc = cc1, cc2, ...
bcc = bcc1, bcc2, ...

[smtp]
host = smtp1.average-isp.com
port = 25

You can also let sendmail send the mail for you. For more information see PatchbombExtension in the Mercurial wiki.