** Using Mercurial Cheat Sheet ** We need a system that will allow the team to work on projects and tasks independently from each other without micromanaging and allowing build-testing and rollbacks to avoid bugs, allow updates of versions and merging, viewing of all versions of code.


Eclipse can be handy for version control, as it has built-in version control functionality, and works (on Windows at least) with some fuss to compile Arduino code. See the Eclipse page if you have free time and would like to try to set it up on your computer.


Why Mercurial is better than Subversion (according to Mercurial):

Mercurial section of the Mozilla project:

Some scary warnings about using Mercurial

Portable MercurialEdit

These are the links to install on your Z: drive: Inno installers dont require admin priviledges, the x86 version is for 32 bit operating systems, x64 for 64 bit. KDiff3, for merging, you'll want this later; get the *.exe with the large number of downloads (for Windows).

Install these to Z:\Mercurial and Z:\KDiff3

TortoiseHg requires admin priviledges, but can perhaps be run off a flash drive, (also Command-line mercurial can run off a flash drive.)

First Run Guide (command line)Edit

If you're using Eclipse or TortoiseHg or some front-end, the steps are the same, you just dont have to use these command-line commands.

Install Mercurial (hg) and KDiff3. If you have any trouble with these instructions (programs not found) on windows try the following in a command prompt (change to your install locations).

path = $PATH$;Z:\Mercurial;Z:\KDiff3

First pull or clone the qmast repository.

hg clone qmast
hg pull

When you pull the repository, you may be asked to update to get a working copy. This is achieved by typing:

hg update

Now your repository will be ready to work on. Then make changes to a file, in the qmast folder mercurial just created. Save the file. Note: if you add a file to this directory there's this extra step:

hg add  (this updates the repository to include any new files in the folder that aren't already tracked)

Check what the difference between the old and new repository is; (hg status will list files that have changed with a code-character in front, ? and ! characters are bad news and require updating the repo [1])

hg status
hg diff

If it looks good, commit it with a useful informative, short comment. (see the googleCode issue updating from commits page for some cool things you can do with your commit logs)

hg commit -u YourGoogleUsername -m "First commit! :) (test)"

This worked? Great! Skip to the next paragraph. If not, stay here. If you're working off your Z:\ drive and get the error "Abort: none: the system cannot find the file specified" try copying and pasting the notepad.exe (found in C:\WINDOWS\system32 ) file to the repository (or possibly, anywhere on your Z:\ drive).

Make other changes, save the world with your awesome coding skills, committing when you want to save a "screenshot" of your code. Now to share it with everyone: First check the list of commits you're about to share:

hg outgoing

Looks good? Share! This updates the code on the repo with YOUR version!

hg push
        • Your Google CODE password is NOT the same as your gmail password. It is autogenerated and can be found under your Settings tab****

If there is an error about merging, there's very little code needed to fix it. Type:

hg merge

You should now get a message about uncommitted merges. Commit your file as indicated above using the commit command. If there are multiple heads, you will have to repeat this process until you no longer get any errors about merging. Below is an in depth discussion for merging with KDiff.

External Diff/Merge SetupEdit

External software that allows comparisons for diff-ing and merging is critical once you get into merging different people's changes together.

I installed KDiff3 from the .exe on windows here, no problems with admin privileges on my Z:/ drive.

Then, (this makes KDiff3 accessible everywhere into that command prompt is closed)

run -> cmd -> :\> path = $PATH$;Z:\KDiff3

External merge configuration just comes down to editing the ~/.hgrc file to have the proper settings.

Mercurial book, section about merging theory

Trouble-shooting kdiff3 and mercurial setup

How to install and setup mercurials .hgrc (and it's location on Windows, Unix); good instructions, not sure about some of the hgrc diff flags

Directions to setup an external merge program in mercurial, no examples, some tips

Sample ~/.hgrc file

Mine looks like this on linux, seems to work for pushing at least:

username = C Blair
merge = kdiff3
hgext.extdiff =
cmd.kdiff3 =
kdiff3.args = $base $local $other -o $output
commit = -v

For Windows, I edited Z:\Mercurial\Mercurial.ini : (removed the lines which were commented out; this works to push and merge; the [merge-tools] section could probably just be cut down to the kdiff3 stuff)

editor = notepad
username = C Blair
merge = kdiff3
hgext.extdiff =
cmd.kdiff3 =
# Some default global settings for common merge tools
kdiff3.args=--auto --L1 base --L2 local --L3 other $base $local $other -o $output
kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
gvimdiff.args=--nofork -d -g -O $local $other $base
vimdiff.args=$local $other $base
meld.args=--label='local' $local --label='base' $base --label='other' $other
meld.diffargs=-a --label='$plabel1' $parent --label='$clabel' $child 
tkdiff.args=$local $other -a $base -o $output
tkdiff.diffargs=-L '$plabel1' $parent -L '$clabel' $child 
xxdiff.args=--show-merged-pane --exit-with-merge-status --title1 local --title2 base --title3 other --merged-filename  $output --merge $local $base $other
xxdiff.diffargs=--title1 '$plabel1' $parent --title2 '$clabel' $child
diffmerge.regkey=Software\SourceGear\SourceGear DiffMerge\
diffmerge.args=-nosplash -merge -title1=local -title2=merged -title3=other $local $base $other -result=$output
diffmerge.diffargs=--nosplash --title1='$plabel1' --title2='$clabel' $parent $child
p4merge.args=$base $local $other $output
p4merge.diffargs=$parent $child
tortoisemerge.args=/base:$base /mine:$local /theirs:$other /merged:$output
tortoisemerge.diffargs=/base:$parent /mine:$child /basename:'$plabel1' /minename:'$clabel'
ecmerge.args=$base $local $other --mode=merge3 --title0=base --title1=local --title2=other --to=$output
ecmerge.regkey=Software\Elli\xc3\xa9 Computing\Merge
ecmerge.diffargs=$parent $child --mode=diff2 --title1='$plabel1' --title2='$clabel'
filemerge.args=-left $other -right $local -ancestor $base -merge $output
; Windows version of Beyond Compare
beyondcompare3.args=$local $other $base $output /ro /lefttitle=local /centertitle=base /righttitle=other /automerge /reviewconflicts /solo
beyondcompare3.regkey=Software\Scooter Software\Beyond Compare 3
beyondcompare3.diffargs=/lro /lefttitle='$plabel1' /righttitle='$clabel' /solo /expandall $parent $child
; Linux version of Beyond Compare
bcompare.args=$local $other $base -mergeoutput=$output -ro -lefttitle=parent1 -centertitle=base -righttitle=parent2 -outputtitle=merged -automerge -reviewconflicts -solo
bcompare.diffargs=-lro -lefttitle='$plabel1' -righttitle='$clabel' -solo -expandall $parent $child
winmerge.args=/e /x /wl /ub /dl other /dr local $other $local $output
winmerge.diffargs=/r /e /x /ub /wl /dl '$plabel1' /dr '$clabel' $parent $child
araxis.args=/3 /a2 /wait /merge /title1:"Other" /title2:"Base" /title3:"Local :"$local $other $base $local $output
araxis.diffargs=/2 /wait /title1:"$plabel1" /title2:"$clabel" $parent $child
diffuse.args=$local $base $other
diffuse.diffargs=$parent $child
UltraCompare.regkey=Software\Microsoft\Windows\CurrentVersion\App Paths\UC.exe
UltraCompare.args = $base $local $other -title1 base -title3 other
UltraCompare.priority = -2
UltraCompare.gui = True
UltraCompare.binary = True
UltraCompare.checkconflicts = True
UltraCompare.checkchanged = True
UltraCompare.diffargs=$child $parent -title1 $clabel -title2 $plabel1
commit = -v

I also went to Windows -> Preferences -> Team -> Mercurial and ticked "Use external merge tool" option in Eclipse, and installed kdiff3 to my Z drive.

Using command-line hg, I created a merge conflict (pulled from one computer, made a change on another computer and pushed, then changed the same line in the file on the first computer) and tried to push, as above. Was warned, so did

hg pull

Was warned that I should merge, so

hg merge

KDiff3 opened, as per my settings. I copied the proper fix into the Output box, and then clicked "Merge" (the diamond-arrow picture). It didn't seem to be doing anything though. Tried saving, clicking merge - I feel like each time I did this it was actually just merging the output as an input? Once I exited, hg detected that KDiff3 had closed and prompted me to commit. Tada!

Update: KDiff3 will not let you Save until all conflicting merges are dealt with. Once you've saved, you can close KDiff3 and your changes will be recorded, and you'll return to hg. The "Merge" button has nothing to do with this; just wrong-click on any "<Merge conflict>?" lines in the output box, select which version (A or B) you want (or edit the Merge Conflict line by hand) to fix merge conflicts. There is a button that will go to the next Merge Conflict, useful for when you're not sure why you can't save.

Hosting ServicesEdit

There are many hosting services around the internet. We looked at GoogleCode and Launchpad, presently we're using GoogleCode.

Google CodeEdit

This is what we wound up going with. Our project Good tutorial on using google code from eclipse Eclipse task list to google code issue list connector


Bazaar-driven project code repository and feature request form

Plugin for bazaar/eclipse integration necessary to save a step using launchpad and eclipse and not really working (could just test in eclipse and then bzr the files)

Version control software tracks changes. Launchpad also tracks bugs and allows descriptions of future features (which I've setup as our major tasks, though I'm sure there are other ways to do it).

Good directions for creating local branches on launchpad with bazaar

QMAST on launchpad This is our project. Bazaar on my computer seems very tempermental with when it will allow me to push - it worked well directly after booting, and pushed once.

 bzr push --use-existing lp:qmast
Community content is available under CC-BY-SA unless otherwise noted.