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... (Image 1).

Image 1

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

Image 2

Now you have the possibility to use the current project folder as the root of your repository (Image 3), 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.

Image 3

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 (Image 4), 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.

Image 4

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 (Image 5).

Image 5

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

Image 6

When the clone has been made, a new dialog is shown (Image 7). 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 in Image 7.

Image 7

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

Image 8

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


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 (Image 10), where you have to enter a commit message and can specify some other commit options, e.g. leaving out some files.

Image 10

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 (Image 11).

Image 11

After you have set the options for pushing, then a new dialog window is shown (Image 12). 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.

Image 12

If we want to receive changes from another repository then this is done in a similar way (Image 13 and Image 14), 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.

Image 13

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.

Image 14

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.

Image 15

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.

Image 16

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 (Image 17). 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.

Image 17

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 (Image 18).

Image 18

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 (Image 19).

Image 19

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 (Image 20).

Image 20

If the merging results in conflicts the Mercurial Merge View shows where these conflicts are (Image 21).

Image 21

From this view you can bring up either the default editor for the file, or the merge editor (Image 22), 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.

Image 22

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.