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.