Mercurial/Getting Started

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 regularily 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 refered to using "changeset" identifiers. Think of it as checksums.

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

This section is meant to summarize (sometimes duplicate) the Documentation in the Mercurial wiki - If you already know those pages, you won't find something new here..

creating a local copy

Creating a local copy means to clone from the master - the URL for the Mercurial Pilot is http://hg.services.openoffice.org/hg/DEV300

$ hg clone http://hg.services.openoffice.org/hg/DEV300 [target-directory]

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/hg/DEV300 OOo-tip_repo-only

This will create a repository-only 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.

updating the local copy with new changes from the master

As mentioned above, doing a full clone every time would be a waste, so how to stay up-to-date then? (Well, for working on a cws you don't need this, only when you want "HEAD" (called "tip" in Mercurial) or when you want a local copy of a master that is not available locally)

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

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

Caveat: 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. This is of course no biggie if you use a repo-only master anyway - 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 seperate pull and update
$ hg pull -u http://hg.services.openoffice.org/hg/DEV300

Note: 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 -U DEV300 target-dir # where DEV300 is your main-checkout
$ hg --cwd target-dir update DEV300_m46 # same as "cd target-dir && hg update -r DEV300_m46" 

This is much faster than to use "hg clone -r DEV300_m46 DEV300 target-dir" and preserves future revisions in the target-clone. It is much faster because the clone without revision uses hardlinks, creates a full-featured copy of the main-checkout very fast (plain copy). The subsequent update command (hg --cwd target-dir update DEV300_m46) creates the files that match the DEV300_m46 tag. The clone with revision creates a DEV300_m46 straight ahead, but uses a different method called "pull protocol". It needs to analyze the full history and changesets to isolate those that are included in DEV300_m46 and throws away everything that was added after DEV300_m46 and is much slower (and needs more diskspace)