Dmitry Churbanov

Mercurial is a distributed revision control (DRC) management system. Decentralization is one of its advantages. For an individual developer DRC systems are faster than centralized: all metadata is stored locally and you do not need to contact the central server each time you modified the code. Mercurial repository is self-contained. It means that all changes you have made will exist only in your local repository until you decide to propagate these changes to the remote one.

This series of posts is how to start to work with Mercurial. If you are looking for a book, there is a very good one which is publicly available: Mercurial: The Definitive Guide by by Bryan O’Sullivan. And I advise you to read it.

In the beginning

All Mercurial commands starts from hg.The hg command provides a command line interface to the Mercurial system. In general each command has the next syntax:

hg command [options]...[arguments]...

Setting up a new Mercurial project

Let’s say you want to create a local repository named “repository-main”:

$ mkdir repository-main
$ cd repository-main
$ hg init

init command initializes new repository in the current folder.
Here is a more shorter way of creating the local repository:

$ hg init repository-main

If you check repository-main folder you can see .hg folder there.

$ ls -la
$ .
$ ..
$ .hg

.hg folder is the only folder where Mercurial keeps all repository related information.

But hardly ever you will create repository on you local computer. Most probably you will use one of the many hosting services to host your repository there. One of the lists of such places you can find here.

Working with existing Mercurial repository

Let’s assume you are using one of the services to host your Mercurial repository (for this post I have used Project Kenai).

To clone files from remote repository and create a local copy, clone command should be used:

$ hg clone ssh://dzmitryc@hg.kenai.com/project-test1~source-code-repository project-test1
no changes found
updating working directory
0 files updated, 0 files merged, 0 files removed, 0 files unresolved

The clone command created a new directory project-test1 and checked out the latest version of the default branch. In Mercurial, the newest version of the branch is called tip. To see the logs about the newest version of the repository you can execute the tip command:

$ cd project-test1
$ hg tip
changeset:   -1:000000000000
tag:         tip
user:
date:        Thu Jan 01 00:00:00 1970 +0000

As our repository is new and empty we don’t see much info.

What about adding new files?

Now lets create the file HelloWorld.java with the following content:

public class HelloWorld {
  public static void main(String args[]) {
    System.out.println("Hello World!");
  }
}

We have the next in our folder project-test1:

$ ls -la
$ .
$ ..
$ HelloWorld.java
$ .hg

If we run hg status command we’ll see the following:

$ hg status
? HelloWorld.java

The status command shows the status of files in the repository. In our case we can see ? (question mark) before the HelloWorld.java file. It means that this file is not tracked by the Mercurial. The next codes are used to show the status:

M = modified
A = added
R = removed
C = clean
! = missing (deleted by non-hg command, but still tracked)
? = not tracked
I = ignored

Now if you want to tell Mercurial to start to track the file and add it to the repository you need to execute hg add command:

$ hg add HelloWorld.java

You can check that Mercurial is tracking just added file by executing hg status command:

$ hg status
A HelloWorld.java

Committing the changes

To commit the changes you need to execute hg commit command:

$ hg commit

Just after you press Enter button Mercurial will run a text editor and ask you to write a comment:

_

HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: Leave message empty to abort commit.
HG: --
HG: user: dmitry@dmitry-laptop
HG: branch 'default'
HG: added HelloWorld.java

Lines started with HG will be removed. It is better to wright a good and clear comment so later you can find out what was the purpose of the commit. In our case we can wright something like: “Add new file HelloWorld.java”.

Another way of committing is to execute:

$ hg commit -m 'Commit message'

where instead of ‘Commit message’ text you can write your commit comment.

Now if you execute hg status command you see nothing. It is because status command only shows files with which something needs to be done. Files which have already been tracked and were not changed will not be shown. After executing hg commit command all changes were saved in your local repository.

Moving changes to the remote repository

As it has been said, each local repository is a full copy of a working repository. And if you make any changes in a local repository and make commit, changes are not automatically propagated to the working repository until you decide to do so.

Let’s say you are fixing bugs. And every day you are fixing only one bug. And after the work was done you commit your changes to the local repository. But at the end of each week you decide to move all your changes from your local repository to the working one. To do so you need to execute hg push command:

$ hg push
pushing to ssh://dzmitryc@hg.kenai.com/project-test1~source-code-repository
searching for changes
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 1 changesets with 1 changes to 1 files

Our changes were pushed to the remote repository and new changeset was created.

Tags: mercurial