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 don’t 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 working 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 command provides a command line interface to the Mercurial system. In general each command has the following syntax:
Setting up a new Mercurial project
Let’s say you want to create a local repository named repository-main:
1 2 3
init command initializes new repository in the current folder.
Here is a more shorter way of creating the local repository:
If you check repository-main folder you can see .hg folder there.
1 2 3 4
.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 on your machine use
1 2 3 4
clone command created 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
1 2 3 4 5 6
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:
1 2 3 4 5
We have the next in our folder project-test1:
1 2 3 4 5
If we run
hg status command we’ll see the following:
status command shows the status of files in the repository. In our case we can see
? (question mark) before the
It means that this file is not tracked by 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:
You can check that Mercurial is tracking just added file by executing
hg status command:
To commit the changes you need to execute
hg commit command:
Just after you press Enter button Mercurial will run a text editor and ask you to write a comment:
1 2 3 4 5 6 7 8
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:
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 will be 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
hg push command:
1 2 3 4 5 6 7
Our changes were pushed to the remote repository and new changeset was created.