MercurialEclipse is a plugin for Eclipse that provides Mercurial integration.


Below we'll go through the very basics of using Mercurial from within Eclipse, via the MercurialEclipse plugin.

1. Getting the Plugin

The MercurialEclipse plugin can be installed either from Eclipse Marketplace, under Help → Eclipse MarketPlace... or from an Eclipse Update Site for MercurialEclipse. See more on the MercurialEclipse homepage.

When installing from Eclipse Marketplace it is not possible to install Mercurial binaries, so there you have to install Mercurial yourself. If you choose the update site you can choose to have the Windows binaries installed with MercurialEclipse. However, this is an older version of Mercurial compared to what you would get if you installed, say, TortoiseHg. What I usually do is install TortoiseHg with the bundled Mercurial, and make MercurialEclipse use that installation. Since Mercurial is very stable, it is not a problem to change to a newer version than MercurialEclipse is made to work with.

2. Creating a Repository

The recommended practice in Mercurial is one repository per project, and this is also what will be assumed in this tutorial.

Although Mercurial is a distributed version control system then people often use a central repository as the canonical repository, but you can of course also create your repository locally. This is done in the following way: Right click on the project you want to make into a repository → choose Team → Share Project...:

Share Project

This brings up a dialog asking which repository plugin you want to use to share your project. Since this is about Mercurial, we will choose Mercurial:

Repository Type

Now you have the possibility to use the current project folder as the root of your repository, or you can choose to initialize a repository somewhere else. There will not be a connection between the project and the repository, if you choose the somewhere else option. So lets just use the project folder as our repository:

Mercurial Repository Location Setup

Now we have initialized the root folder of our project as a repository. So now we can see the status of the repository in the navigator, and a lot of version control commands are available under the Team context menu, for the project and for the file. The essential ones of these will be described below.

Project Explorer

3. Cloning

If the repository is already created, you can clone a repository by choosing File → New → Project... and then choose the Clone Existing Mercurial Repository wizard.

New Project

The wizard then lets you then specify the URL to clone from and other options, like username and password if required.

Clone Repository Wizard

When the clone has been made, a new dialog is shown. This dialog lets you choose which revision the working copy should be updated to. You can both type a revision or select one, by browsing the tabs.

Select Working Directory Revision

The final dialog lets you decide whether what now has been cloned should be imported into Eclipse workspace.

Import Projects

As we saw when creating a new repository, the working directory status is shown in the Project Explorer.

4. Committing

To make a commit use Team → Commit... for the context menu for a project or a file if you want to commit a single file. This brings up a dialog, where you have to enter a commit message and can specify some other commit options, e.g. leaving out some files.


5. Pushing and Pulling

Since Mercurial is a distributed version control system, commits are only local. To push these to another repository, e.g. the canonical one, one should use Team → Push... the team menu for the project context menu. This also brings up a dialog, where the push destination can be entered and other options can be set.

Push Changesets

After you have set the options for pushing, then a new dialog window is shown. Here it is possible to see all the changesets that's going to be pushed, and by clicking on a changeset, it can be seen what it consists of. So here you can check if you really want to push the changes your are about to. When you are sure, then push the changes by pressing the Finish button.

Outgoing Changesets

If we want to receive changes from another repository then this is done in a similar way, but of course starting with the Team → Pull... menu item instead. One thing to notice is that default behavior of pull in MercurialEclipse is to update after pull, which is different from the default behavior when pulling from the command line.

Pull Changesets

Just as you get to see the outgoing changesets when pulling, you get to see the incoming ones before pulling, so you can check whether you really want to pull in those changes.

Incoming Changesets

6. Update

In the Team menu for the project there is an Update menu item. This will update the working directory to the tip of the current named branch.


If the working directory should be updated to a different revision, then the Team → Switch To... menu item should be chosen, which brings up a dialog to select the place in history to update the working directory to.

Switch To

7. Show History

A reason to have a version control system is to be able to see the earlier states of the project. The Team menu includes a Show History both for the project, and for the files. Both will bring up a History view showing a revision graph, with information on the changesets, and if a changeset is selected, then more specific information on this changeset is shown. If Show History is done on a file, only changesets in which the file was changed are shown.

There can also be updated to a revision from the History View, by right clicking on a changeset and select Switch Repository to Selected Changeset.

Show History

When a changeset is selected, files edited in that changeset is shown, and can be opened or compared with current or previous version of that file.

Right Click on Changeset

If the History View shows history for a specific file, then two revision can be compared by selecting two revisions, right clicking on one of them and choose compare with each other.

Right Click on File

8. Merging

To perform a merge choose Team → Merge... from the team menu from the project context menu. Choose the revision you want to merge with. If there is only one other head this is suggested as the revision to merge with by default.


If the merging results in conflicts the Mercurial Merge View shows where these conflicts are.

Conflict View

From this view you can bring up either the default editor for the file, or the merge editor, which shows the difference between the two editions of the file. It is also from this view you can finish or abort a merge. A merge cannot be finished until all conflicts has been marked as resolved.

Merge Editor

9. Much More...

Almost everything that can be done via the command line can also be done by MercurialEclipse, therefore a lot more things can be done from inside Eclipse, but what was described here was the very basic commands for interaction with a Mercurial repository.

MercurialEclipse (last edited 2012-08-23 12:07:44 by MartinGeisler)