I am a Software Developer at a large software company. Formerly at a start-up company. Mostly server side, core, design and architecture. Computer Science degree at a university. Liran has posted 1 posts at DZone. You can read more from them at their website. View Full User Profile

Mercurial Guide

  • submit to reddit
Version 1.41, 29/03/2013 

Short and simple Mercurial Guide / Tutorial - for working with a plug-in for Eclipse

Mercurial is a distributed version control system. Each user has revisions in their local repository. There is also one shared repository, typically hosted on the internet. Mercurial is convenient for teamworking, as well as working alone where you can easily roll back to an older version of the project.

Important: You should read the entire guide first, before you start working with Mercurial, especially the working rules at the end. Also, it's a good idea to save a manual backup of your files (although not required)

There are many ways to use Mercurial. In this article we'll explain how to use Mercurial in a Java project with a plug-in for Eclipse.

Installing Mercurial, And Eclipse Plug-In

Download Mercurial from http://mercurial.selenic.com/downloads/, install, and verify that the second option is checked. Add the installation path to the search path

Hit “Finish” and you’re ready. Open “Cmd” and type:

hg --version
Now you’re done. Mercurial is installed on Windows.(Now you have verified that you can use it from command prompt on Windows)
sudo apt-get install mercurial hg --version
Eclipse Plug-In In Eclipse, go to Help/Install New Software and install from the  following update site:http://cbes.javaforge.com/update

It can take a while. Also, if there is a problem at the intallation, you can uncheck the second option and try again.
If there is sill a problem during installation, download com.vectrace.MercurialEclipse_xxx.jar from http://javaforge.com/dir/76467, close Eclipse, put in the folder you installed Eclipse to, under plugins, e.g. Eclipse\plugins, and start Eclipse again. It will be installed.

Now we'll see how to work with Mercurial, broken into two parts: for the user who initially created the project, and for the user(s) who are also working with this project.

For the user who initially created the project

  • Create a new Java project in Eclipse, hit right mouse click on it: Team /Share Project…  This will cause a star to appear next to the project

    and confirm.
  • Create a repository on the internet, for example on one of these sites:
    (Google code, Codeplex, etc', notice the clone address that the sites give you)

Now we'll see an example of using the repository.

Create a class and write in something, i.e. "try1" as a comment. Now right click on Project/Team/Commit.

A window will open, write your commit message (important ! So when switching to another revision, the changes will be clear quickly), check all the files, and confirm. Now the revision is saved on the local repository on your computer.

Again, right click on  project, click Team/Push, and enter the clone project address from the internet repository, with your username and password and confirm.

Now the revisions from your computer are uploaded to the shared repository on the internet.

Now your project teammate, who also works on the project, did some changes of other files from the project, and committed them to a newer revision (he also pushed his changes). You want these changes at your computer as well.

Right click on the project, and click Team/Pull.

Check update (checked by default), this is recommended. Now the revision from the internet repository is downloaded to your local repository, and if there are no conflicts (e.g. working on same file at the same time), all the needed files will be updated. If wanted - do commit.

For Users Working on an Existing Project

The more convenient option, but which causes the project hierarchy (on the left) to look a bit different.Using the File / Import / Mercurial / Clone repository using Mercurial.

Type in the clone project address, and click confirm.

There are a lot of options under the Team menu, such as options for branches, and merge, which can be problematic (see below), but necessary.

Important Working Rules

Without maintaining these rules, working with Mercurial can be very frustrating and cause problems, mainly when trying to merge. In fact, the merge option can still be problematic even when maintaining these rules!

Do not create a situation where more than one user is working on the same file on the same time (What will happened to this file on merge and which file will be chosen ?)

Short explanations of actions:

Save the changes you made on the revision to your local repository.
Notice you should pull and update before a commit. Otherwise, if there was a commit by a different user after your last pull, and before your commit - when you push you will see that your commit created another head - a merge will be necessary (don't force push in this case).

Upload all the revisions from your local repository to the internet.

Note, this meaning is just for pull, without checking the merge/update option, no merge afterwards
Download all revisions that other users have uploaded to your local repository from the server (shared repository). If the merge option is chosen, it merges your revision with the latest changes.
If update (recommended) is checked, the changes from the repository will take place at your computer. You should update before start working.

Switch to
Make sure to commit first!
Switches to another revision. This is a very powerful option, which can be used a lot. When you are at a certain revision, and wants to see an older one as is - just do switch to to the wanted revision, and you will see it. Make sure though, that the next time you do commit, it's from the tip(last) revision.

Choose the required revision, usually the last one that you didn't upload, and merge the changes with your revisions.

Each time when you work, before you start changing things, if you do not have the last revision – pull and then merge with the last revision.

When you have made your changes, commit and push. It's recommended to do this from time to time.

When you push or pull, you can probably check both the option 'abort when timeout occurs.'

With backout you can reverse changes that have been committed earlier. Meaning, when you want to switch to an older revision, so that older revision will become the new tip revision, the newest revision. It can be useful if you want to discard the changes of some of the last revisions (while keeping them at the repository).
To do this: team -> undo -> backout, and choose the next revision, the one revision after the revision you want to switch to. So the parent of the revision you chose will become the new one(without creating a new unwanted head, like it can happend if you commit from an older revision). You can also leave the merge option checked, and then merge some of the changes.



A branch is like a collection of revisions, a linear sequence of consecutive changesets, a copy of the main source. And it is targeted not to be committed onto the main source.

Uses, for example:

- If you want to try changing some classes, but not sure it will work, you can try,

and if you want to revert, you do not have to remember all the changes you have made - just return to the main branch. This way, you can commit a few times to the branch, without affecting the main source.

- A Software developer at a developing team can work on his branch, and when he finishes, the team leader can check his work before it is merged onto the main source.

- * You created a system for something. Now there is a demand for a similar one, but with slightly changes. So instead of creating another copy of the whole source - create a branch for it.

  * This is sometimes not needed, depends on the design of the system.

Creating branches

There are several ways; I will discuss branching with named branches.

I will discuss a case where there is a main source, and branches under it, with no sub-branches of them. But this should not be very different.

If it used under the same repository, it adds a new head. So the space that the source is taken is not doubled (correct me if I’m wrong here).

To create a branch at Eclipse: right mouse click on the project: team -> Add Branch.

Working with the branch

You can commit changes regulary as needed (right mouse click on the project: team -> commit).

Merging changes from a branch to the main source (The branch is good)

First we go back to the main branch (or someone, e.g. team leader which already at the main branch so it is not needed): right mouse click on the project: team -> switch to – branches – and choose the main branch.

right mouse click on the project: team -> merge – branches – choose the newly created branch (notice that files that have been changed at the branch will be also changed at the main branch !!! ).

Close / Remove Branch

You can close a branch for some reasons, for example:

With Mercurial, you can create a temporary branch, either for an experimental feature, or to develop a new pretty big feature when you do not want to commit to the head until it is ready, or you do not want this branch anymore.

In order to do this:
When you are on the latest revision of the branch you want to close: team -> commit -> check "Close named branch".

This will keep the branch with its revisions in repository history, but you will not see this branch in the active branches tab.


You can tag revisions for a certain project version, patch / update number etc':
team -> Tags...


If you want to ignore a file, so it will not be uploaded to the repository on 'commit':
Right click on the file -> team -> ignore.
It is good for example for keeping local configuration file, configured differently for each computer / environment.

If you get "crosses branches" message when trying to push
'force push' will work, but it is NOT recommended ! So it suggested for you to first merge with the head - but notice every different file - notice that you get in the end actually the files you wanted, with their content.

WEB interface for a project

Right click on the project -> team -> serve
Then go to http://localhost:8000/ (default port) / http://localhost:PORTNUMBER/ at your web browser.
This command can be useful to see the specific lines each user wrote at a file. This command can be used from the Eclipse plug-in, but it's not so clear over there. So from the Windows command line / Linux console, enter the folder of the project, and then:
hg annotate -u -n FILENAME
hg annotate -u FILENAME

Mercurial can run script/s each time a specific defined Mercurial event happens.
The script to run is defined at the file .hg/hgrc at the folder of the project. Notice that this file, and Mercurial Hooks are not revision controlled, and do not propagate. So it’s defined only on each repository separately, or only on one (or more) repository.
More information:
Notice that some online repository sites offer an option to request an API call on each PUSH, so you might consider it instead of hooks, depends on your needs.


This is like export.
It can create a snapshot of the project at a certain revision (usually the latest).
To do this, enter the folder of the project via the command line / terminal / console, and enter the command:
hg archive ARCHIVENAME
Or to specify a revision:
It can also create ZIP, or other type archive files.

This can also be a version control / distributed version control guide for beginners / starters:

Version Control Guide

Published at DZone with permission of its author, Liran Mendelovich.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)


Liran Mendelovich replied on Thu, 2010/07/22 - 6:34am

This is clearly not a full guide/manual. Just a simple and nice getting started tutorial.
I have publish this article when I worked on a project on a Computer Science course at the university, and many students found this useful for their project and used Mercurial this way.
Comments \ "Zone it" will be welcomed.

Michael Jäger replied on Wed, 2010/07/21 - 10:19am

I quit reading when I realized, this is not a guide to Mercurial, but to Mercurial on Eclipse. As I am not using Eclipse and do not intend to do so, this is useless to me.

Liran Mendelovich replied on Wed, 2010/07/21 - 12:48pm in response to: Michael Jäger

Right. It's a specific guide for Mercurial-Java-Eclipse (maybe it's relevant for other languages with Eclipse).
But I wrote this at the beginning:
"There are many ways to use Mercurial. In this article we'll explain how to use Mercurial in a Java project with a plug-in for Eclipse."
It is also written in the subtitle:
Short and simple Mercurial guide - for working with plug-in for Eclipse"

Fabrizio Giudici replied on Wed, 2010/07/21 - 11:26am

Do not create a situation where more than one user is working on the same file on the same time (What will happened to this file on merge and which file will be chosen ?)


I think that the above statement should be clarified. Actually, Mercurial and other similar distributed source repositories have been designed exactly for allowing people to concurrently work on the same stuff (in contrast with old facilities where it was mandatory to lock a file while working on it, then unlock when the job was done) and eventually postponing the merge time as long as one wishes.  Clearly, the longer you postpone the merge, the harder the merge will be, but this is a trade off one must handle.

While the lock approach is clearly safer, it's also a bottleneck and Mercurial has been designed for scale up with a very high number of committers.

So, people could work on the same file and their work should be merged at some time. Of course you're right that this scenario is a potential problem and must be dealt with care, but if I one wanted to absolutely avoid it, perhaps Mercurial is not the best tool for him (even though it offers other features that one might like).

Michael Jäger replied on Thu, 2010/07/22 - 2:37am in response to: Liran Mendelovich

Might be that I am looking at the wrong place, but ... there is no subtitle. And then the passage about the use of Mercurial in the context of Eclipse is not at the very begining, it is the third passage.

I am not to say your article is irrelevant or bad, but its title is clearly misguiding.

Liran Mendelovich replied on Thu, 2010/07/22 - 3:27am in response to: Michael Jäger

The subtitle is at the end, this is how it's on this site:
Short and simple Mercurial guide - for working with plug-in for Eclipse

Article Type:
Ok. The 2-3 first paragraphs are just an Introduction, so it's written there.

Michael Jäger replied on Thu, 2010/07/22 - 6:59am in response to: Liran Mendelovich

I see, not your fault then. Putting the subtitle at the bottom of the page seems like a curious decision anyway.

So in conclusion: might be a great article but I do not belong to the intended audience. I would have preferred a hint on that a little earlier to prevent me from wasting time (which is what I am still doing here ... ;-)).

Chad Hahn replied on Thu, 2010/07/22 - 10:41am


Do not create a situation where more than one user is working on the same file on the same time (What will happened to this file on merge and which file will be chose ?)
I love Mercurial, but this article isn't doing it any favors. If someone not experienced with Mercurial read this, they would probably associate it with SourceSafe or some other horrid thing. That is NOT the case.  Mercurial just works, but you need to read their workflow guide to get a basic grasp of what's going on.

Christoph Grothaus replied on Fri, 2010/07/23 - 9:31am

> Without maintaining these rules, working with Mercurial can be very frustrating and cause problems, mainly when trying to merge. In fact, the merge option can still be problematic even when maintaining these rules!
> Do not create a situation where more than one user is working on the same file on the same time (What will happened to this file on merge and which file will be chosen ?)

I do not want to be unfair or anything, but the above quote clearly shows, that the author of this article has not really understood Mercurial. Indeed, it is one of the strengths of Mercurial (and other distributed version control systems like Git or Bazaar) to be very good at merging commits. How could you work distributed without that?

Liran Mendelovich replied on Sat, 2010/07/24 - 3:25am in response to: Christoph Grothaus

I wrote this after experience with many people which had problems with merge. When people tried to merge after they have been working on the same file at the same time - they got stuck, they did not succeed to merge, and it created many problems for them.
Many people can work, each of them on its own files at the time, and merge afterwards.
It's possible to work on the same files at the same time - and merge manually these files when needed - the plug-in would ask you to edit the file before the merge, but it creates problems - again, i'm talking from experience with this plug-in.
These "rules" I wrote are certainly not mandatory for people know what they are doing, but for people who are experiencing with version control system for the first time - if they will not follow this rules, and will work with this plug-in for Mercurial, many problems can occur.
I know for a fact, that big part of students at my course at the university had these problems with merge, hence I wrote these rules, not because they are 100% accurate or mandatory.

Khent Johnson replied on Fri, 2011/09/02 - 3:36pm

Hi! I am new with Mercurial and Eclipse thing and I know I need to exert extra effort to move forward quickly. But before getting started, I would like to raise my great thanks to the author of this writings because as you all know it really means to me. I am working as a project manager and will be using this platform thus; I really need full information as you have there. Thanks! GAR Labs

Elton Daries replied on Tue, 2012/12/18 - 4:03am in response to: Liran Mendelovich

 Hi Liran

I am a developer that started to use Mercurial with Eclipse (PHP) and find your tutorial concise, to the point and very helpful.  Well done!

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.