Queen's Mostly Autonomous Sailboat Team Wiki
Register
Advertisement

** 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[]

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.

Mercurial[]

Why Mercurial is better than Subversion (according to Mercurial): http://hginit.com/

Mercurial section of the Mozilla project: https://developer.mozilla.org/en/Mercurial

Some scary warnings about using Mercurial

Portable Mercurial[]

These are the links to install on your Z: drive:

http://mercurial.selenic.com/downloads/ Inno installers dont require admin priviledges, the x86 version is for 32 bit operating systems, x64 for 64 bit.

http://sourceforge.net/projects/kdiff3/files/kdiff3/0.9.95/ 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 http://stackoverflow.com/questions/1904419/running-mercurial-on-a-flash-drive Command-line mercurial can run off a flash drive.)

First Run Guide (command line)[]

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 https://qmast.googlecode.com/hg/ qmast
(OR)
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 https://YourGoogleUsername:YourGoogleCODEpassword@qmast.googlecode.com/hg/
        • 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 Setup[]

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:

[ui]
username = C Blair
merge = kdiff3
[extensions]
hgext.extdiff =
[extdiff]
cmd.kdiff3 =
[merge-tools]
kdiff3.args = $base $local $other -o $output
[defaults]
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)

[ui]
editor = notepad
username = C Blair
merge = kdiff3
[extensions]
hgext.extdiff =
[extdiff]
cmd.kdiff3 =
# Some default global settings for common merge tools
[merge-tools]
kdiff3.args=--auto --L1 base --L2 local --L3 other $base $local $other -o $output
kdiff3.regkey=Software\KDiff3
kdiff3.regappend=\kdiff3.exe
kdiff3.fixeol=True
kdiff3.gui=True
kdiff3.diffargs=--L1 '$plabel1' --L2 '$clabel' $parent $child
gvimdiff.args=--nofork -d -g -O $local $other $base
gvimdiff.regkey=Software\Vim\GVim
gvimdiff.regname=path
gvimdiff.priority=-9
vimdiff.args=$local $other $base
vimdiff.priority=-10
merge.checkconflicts=True
merge.priority=-100
gpyfm.gui=True
meld.gui=True
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.gui=True
tkdiff.priority=-8
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.gui=True
xxdiff.priority=-8
xxdiff.diffargs=--title1 '$plabel1' $parent --title2 '$clabel' $child
diffmerge.regkey=Software\SourceGear\SourceGear DiffMerge\
diffmerge.regname=Location
diffmerge.priority=-7
diffmerge.args=-nosplash -merge -title1=local -title2=merged -title3=other $local $base $other -result=$output
diffmerge.checkchanged=True
diffmerge.gui=True
diffmerge.diffargs=--nosplash --title1='$plabel1' --title2='$clabel' $parent $child
p4merge.args=$base $local $other $output
p4merge.regkey=Software\Perforce\Environment
p4merge.regname=P4INSTROOT
p4merge.regappend=\p4merge.exe
p4merge.gui=True
p4merge.priority=-8
p4merge.diffargs=$parent $child
tortoisemerge.args=/base:$base /mine:$local /theirs:$other /merged:$output
tortoisemerge.regkey=Software\TortoiseSVN
tortoisemerge.checkchanged=True
tortoisemerge.gui=True
tortoisemerge.priority=-8
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.gui=True
ecmerge.diffargs=$parent $child --mode=diff2 --title1='$plabel1' --title2='$clabel'
filemerge.executable=/Developer/Applications/Utilities/FileMerge.app/Contents/MacOS/FileMerge
filemerge.args=-left $other -right $local -ancestor $base -merge $output
filemerge.gui=True
; 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.regname=ExePath
beyondcompare3.gui=True
beyondcompare3.priority=-2
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.premerge=False
bcompare.gui=True
bcompare.priority=-1
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.regkey=Software\Thingamahoochie\WinMerge
winmerge.regname=Executable
winmerge.checkchanged=True
winmerge.gui=True
winmerge.priority=-10
winmerge.diffargs=/r /e /x /ub /wl /dl '$plabel1' /dr '$clabel' $parent $child
araxis.regkey=SOFTWARE\Classes\TypeLib\{46799e0a-7bd1-4330-911c-9660bb964ea2}\7.0\HELPDIR
araxis.regappend=\ConsoleCompare.exe
araxis.priority=-2
araxis.args=/3 /a2 /wait /merge /title1:"Other" /title2:"Base" /title3:"Local :"$local $other $base $local $output
araxis.premerge=False
araxis.checkconflict=True
araxis.binary=True
araxis.gui=True
araxis.diffargs=/2 /wait /title1:"$plabel1" /title2:"$clabel" $parent $child
diffuse.priority=-3
diffuse.args=$local $base $other
diffuse.gui=True
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
[web]
cacerts=U:\Mercurial\cacert.pem 
[defaults]
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 Services[]

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

Google Code[]

This is what we wound up going with.

https://code.google.com/p/qmast/ Our project

http://blogs.intland.com/main/entry/39 Good tutorial on using google code from eclipse

http://code.google.com/p/googlecode-mylyn-connector/ Eclipse task list to google code issue list connector


Launchpad[]

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
Advertisement