MercurialEclipse

MercurialEclipse is a plugin for Eclipse that provides Mercurial integration.

HomePage: https://foss.heptapod.net/mercurial/mercurialeclipse/-/wikis/home

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... (Marketplace version is broken!) or from the Eclipse Update Site for MercurialEclipse:

Update Site: https://foss.heptapod.net/mercurial/mercurialeclipse-updatesite/-/raw/branch/default/p2

See more on the MercurialEclipse Wiki.

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...:

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:

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:

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.