Revision as of 12:53, 8 May 2009

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

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. To really update your local tree 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

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 DEV300 target-dir # where DEV300 is your main-checkout

show me the differences

committing stuff

pushing changes

what about merging