Mercurial/Getting Started

Mercurial
Quick Navigation Setting It Up Getting Started CWS Workflow Tips and Tricks Migration
About this template

This page aims to help cvs/svn users to get started with mercurial, without the need to dig in cyberspace for basic stuff. If you have a tip or general remark to share, feel free to edit the page - It's a wiki after all :-) Especially if you see something wrong here, just correct it without asking for permission on the ML

The very basics: Mercurial is a DVCS

Mercurial (hg) is a distributed version control system. This is a major difference compared to tools like CVS or subversion and that difference imposes a changed workflow compared to centralized version control systems.

Your checkout is a full repository

In a simplified view, every checkout is a full repository. You have history and version info for other branches in your local tree. So naturally such a checkout is rather big compared to a single-revision checkout done by cvs and svn. So you won't checkout a full repo every time (unless you have bandwidth to waste and too much time on your hands :-) Instead you will regularly update your local copy with the changes that were added to the repository and then "clone" (that's the term used for a "checkout") your local repository instead.

Your commits go to your local repository first

Another difference is that any change you commit will be done in your local copy only at first. You can accumulate many different commits locally and need to "push" changes to the master to finally have them in the main repo/available for everyone.

There are no version numbers anymore

Because multiple persons can do local commits, have different "local master copies" (somebody else could have pushed a change to the master before that alters the file you change yourself), it is impossible to refer to a specific version of a file by a version number. What is version 23 of a file? The one in your local copy, that doesn't exist on the master yet? Or version 23 of a file of another user that did commit the same file locally? So instead of version numbers, specific versions are referred to using "changeset" identifiers. Think of it as checksums.

Mercurial offers the possibilities to use easier to type numeric revisions instead of changeset identifiers during work with a local repository. But remember: these numbers have no meaning outside this specific local repository. Don't use them when communicating with others.

Further reading

Remembering the three points above are enough to get you going. If you want to know more you'll find all things Mercurial at the Mercurial Wiki. An excellent tutorial can be found in "tour" chapters of the Mercurial book, which is also available online. Another excellent illustrated tutorial aimed at a broad audience (written by Joel Spolski, no less) can be found here.

The Mercurial command line help is quite well written and concise. Make good use of it. Example:

 $ hg merge --help

To get an overview over all commands and some concepts type:

 $ hg help

So how to use it then (aka: What commands do I have to type?)

You want to play around with the OpenOffice.org sources without bothering with all the things a OOo domain developer needs to keep in mind? You aren't interested in this CWS thing at all? Good, this section is for you.

Creating a local copy

Creating a local copy means to clone from the master - the URL for the the main OOo development code line is http://hg.services.openoffice.org/DEV300

$ hg clone http://hg.services.openoffice.org/DEV300 local_DEV300

If you know that you'll only use this as basis for different local clones and don't want it to create the actual source-files, then you can use

$ hg clone -U http://hg.services.openoffice.org/DEV300 local_DEV300

This will create a treeless version, i.e. you'll get an (apparently) empty OOo-tip-repo-only directory that holds the history/changeset data only, but not the actual files. Saves some diskspace and lessens the risk of modifying the master you intended to keep pristine.

The OOo mercurial repository is quite huge, so doing cloning from the OOo server will take substantial time. A significant faster way is to download a nightly (GMT) created so called bundle of DEV300 which is available at http://hg.services.openoffice.org/bundle/DEV300.hg. This bundle contains the full history in one highly compressed file (currently about 800MB in size). Create a treeless local DEV300 copy with $ mkdir local_DEV300 $ cd local_DEV300 $ hg init $ hg unbundle <path_to_bundle>/DEV300.hg and proceed with updating it with the latest changes as described below.

Pulling new changes from the master and updating the local copy

As mentioned above, doing a full clone from the OOo server every time would be a waste, so how to stay up-to-date then?

Updating means "pulling the new changes" from the master:

$ cd local_DEV300 # change to the directory of your main clone
$ hg pull http://hg.services.openoffice.org/DEV300

While this grabs all the changes that were done on the master since the last checkout, it will not automatically update the source-code files on your disk. It basically only gets the history and changesets.

Not updating the source tree is just what we want for a treeless copy. But if you want local source-files to reflect the newest changes, you need to do an update of your tree:

$ hg update

Since pulling the newest changes and updating to those changes is rather common, you can use the -u switch to the pull command to do both in one go:

# alternative to separate pull and update
$ hg pull -u http://hg.services.openoffice.org/DEV300

The URL is optional in all of the above commands - if omitted, it will just use the URL that was used to clone the repo.

Cloning from the local repo to create a working copy

It is easier to keep a pristine copy of the sources as a base for new work, than to clean up an already modified repo, especially when you're not familiar with the tools yet :-) - so to create a working playground for your real work, clone from your local main-clone:

$ hg clone local_DEV300 working_DEV300 # where local_DEV300 is your main-checkout

If you need an earlier milestone examine the tags and update your working copy to the desired milestone (you might want to use clone -U in the command above then).

$ cd working_DEV300
$ hg tags                 # in case you don't already know the name of the tag
$ hg update -r DEV300_m60 # if you want milestone DEV300:m60

The above method is much faster than the apparently easier method of using clone with a revision. Don't use $ hg clone -r DEV300_m60 local_DEV300 working_DEV300 as mercurial would have to examine the whole history to throw out everything that wasn't part of DEV300_m60, and it cannot make use of hardlinks, thus it will require a significant amount of diskspace as well. Depending on how fast your system is, the difference can be something like 30 minutes for the "clone -r" method and just 3 minutes for the "first clone, then update" one. You have been warned.

Explore the working tree and history

The basic Mercurial commands are very similar to their equivalents in SVN and CVS.

$ hg status sw             # shows the status of all files in directory sw
$ hg status                # shows the status of the whole tree!

Most Mercurial commands, when specified without file/directory argument, will operate on the whole tree. This will come as a surprise to SVN and CVS users. You'll notice it when your status command scans the whole tree instead of a single directory, or you accidentally commit files in a far away directory.

 $ hg log cws.pl           # shows all changesets affecting file cws.pl
 $ hg log -v | more        # shows all changes in the repository in verbose format
 $ hg log -v -r 262026     # shows verbose log of the changset with the numeric id 262026 (only locally valid!)

 $ hg diff cws.pl          # shows local (= not yet committed) modifications of cws.pl
 $ hg diff --git           # shows all not yet committed modifications in tree, format is git-diff
 $ hg diff -c 2e9d06d9922d # show all changes made by changeset 2e9d06d9922d
 $ hg diff -r 4e62cb377115 -r d6f5cf344cec cws.pl # show diff of cws.pl between the two rev.

Committing your changes

Commit your changes to your local repository is straighforward:

$ hg commit -m"foo42: #i4711# implement foobar gadget" # Commit all your locally modified files
$ hg commit cws.pl         # Commit cws.pl, an editor will pop up for the commit log

Merging

Occasionally you will need to merge changes. Say you are working on repository cloned a while ago and now you want to update to the latest DEV300 milestone:

$ hg pull http://hg.services.openoffice.org/DEV300

Mercurial will tell you that you need to merge the freshly pull changes with your local changes

$ hg merge

In many cases automerging the files will suffice, but occasionally you'll get conflicts. Fix the conflicts and mark the conflicted file as resolved.

$ hg resolve -m solenv/bin/cws.pl   # mark the conflict in cws.pl as resolved

Check if there are more unresolved conflicts with

$ hg resolve -l

When all conflicted files are resolved commit the result with

$ hg commit -m"foo42: merge with DEV300 m63"

Exchanging your work with others

There are a number of ways on how to exchange your work with others. OpenOffice.org domain developers use a process called "child workspaces (CWS)" as the main way to organize collaboration. How to work with Mercurial based Child Workspaces is described here.

If you are not (yet) a OOo domain developer you can export your changes as patch and attach it to an issue or send it to the developers mailing list

$ hg export tip > tip.patch

When you made larger changes you could use the patchbomb extension for proper formatting before sending to the mailing list.