SiteName

New to Mercurial? Here is a quick reference to ease you into the differences of Mercurial, as opposed to SVN, and help you get your first project started!

What is Mercurial?

Mercurial is a code versioning tool akin to the likes of SVN, Git, CVS and countless others. As described by wikipedia:

Is the management of changes to documents, programs, and other information stored as computer files. It is most commonly used in software development, where a team of people may change the same files. Changes are usually identified by a number or letter code, termed the "revision number", "revision level", or simply "revision".

How is Mercurial different from SVN?

If you've come from an SVN background, such as I have, there are some key differences to note when transitioning to Mercurial. Namely, Mercurial has two repositories. The first is stored locally and it's best to think of this like the repository you're used to in SVN. It's here where you commit and update your code as you're used to in SVN.

Mecurial is different in that once you're happy with your code you then "push" the local repository code to the second repository - usually an external server. I guess you could think of this as "making it public". This isn't strictly speaking as you can actually pull code from other users machines but that's out of the scope of this article.

Another difference is the terminology of "checkout". In SVN this is what you do when you first start working on a project to download the initial copy to your local machine. The Mercurial definition of this is "clone".

The Mercurial Process

To begin, you start by "cloning" (aka checking out) an existing project (from the main repository)

Example:

hg clone [http://server.name/project]

As mention, you "commit" your code (from what is termed your "working directory") to your local repository. You then "push" that code to the main repository.

Example:

hg commit
hg push

To update your code with the latest changes you essentially do the opposite. You "pull" code from the central server which updates your local repository, and then you use "update" to update your working directory.

Example:

hg pull
hg update

Mercurial Reference

Below are some of the commands you'll need to master the basics of Mercurial.

Help:

hg help

Clone (checkout):

hg clone [http://server.name/project]

List files that have changed:

hg status

See the changes we've made to the file(s):

hg diff

Save changes, aka commit (You commit your changes to your local repo then "push" that to the external server):

hg commit

See file modified by other users:

hg incoming

Update your *repository* with the latest changes:

hg pull

Update *working* directory with the latest changes (Basically you pull the changes from the global repo to your local repo and then you use update to make those changes available for you to use in your working copy):

hg update

List what changes would be pushed into another repository:

hg outgoing

Perform actual push:

hg push