OLPC/MercurialQuickstart

Mercurial quick start guide

This page gives a quick overview of using Mercurial for people who are familiar with a traditional CVS workflow.

Setting your identity

Every single changelist is tagged with an email address, so assuming you don't want this to just reflect the yourusername@hostname of your current UNIX login, you must set your public identity. This is done by creating a file $HOME/.hgrc. For example:

$ cat > $HOME/.hgrc <<EOF
[ui] 
username="Daniel P. Berrange <berrange@redhat.com>"
EOF
$

NB, even if you are planning to work off the anonymous repository and submit changelist bundles upstream setting your identity is still important, since Mercurial maintains change history at all steps.

Getting an initial checkout

In a distributed SCM system, getting a checkout not only populates the local working directory with the latest files, but downloads the entire repository history. Thus the process of getting an initial checkout is referred to as 'cloning' a repository, and is accomplished with the 'clone' command. So get get a checkout of the development branch of the SDK project, one would run:

$ cd $HOME
$ mkdir olpc
$ hg clone http://hg.fedoraproject.org/hg/olpc/tools/sdk--devel

Once the clone operation completes there will be a local directory called 'sdk--devel' containing the latest code. The directory '.hg' inside there contains the entire repository history, so from this point onwards no network access is required to the hg.fedoraproject.org machine.

Manipulating files

So during the course of development files may be added, deleted, renamed or just plain edited. .

Adding files

The 'add' command is used to register new files

$ hg add Makefile.am

Removing files

The 'remove' command is used to delete existing files

$ hg remove Makefile

Renaming files

Files can be renamed using the 'rename' command, although this is really just a sequence of remove/add commands

$ hg rename notes.txt README

Editing files

No special command is required to edit files, since Mercurial will notice changes automatically from the file modification timestamp.

Working directory status

At any time a summary of the local repository state can be seen running the 'status' command

$ hg status
M README
R Makefile
A Makefile.am
? bin/Makefile
? config.log
? config.status

This tells us that the file 'README' is modified, 'Makefile' has been removed, and 'Makefile.am' has been aded.

Commiting a changelist

Once a suitable amount of work has been completed, a changelist can be committed. Changelists are uniquely identified by a hexidecimal hashcode - this hashcode is considered unique even across any repository worldwide. To commit a changelist just run the 'commit' command passing a short description

$ hg commit -m "Renamed makefiles"

Viewing history

The 'log' command will show details of every changelist in the local repository

$ hg log
changeset:   10:f2f143a6365f
tag:         tip
user:        "Daniel P. Berrange <berrange@redhat.com>"
date:        Thu Mar  9 09:40:39 2006 -0500
summary:     Renamed makefiles

... snipped out rest of changelist ...

Exporting changes

To submit changes back to the master OLPC source repository, one must export a bundle containing the changelists. This can then be sent to the mailing lists or attached to a bug report or feature request ticket. The 'bundle' command is used to do the export. This compares the local repository with the master repository are creates a bundle containing all the local changelists which are not already in the master repository. So for example

$ hg bundle mychanges.hg http://hg.fedoraproject.org/hg/olpc/tools/sdk--devel

The 'mychanges.hg' file can now be sent upstream for review.

---