Mercurial Guide

Liran Mendelovich

Jul. 21, 10 · Interview

Like (0)

Save

18.80K Views

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

Windows
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)
Ubuntu(Linux)
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:
http://www.selenic.com/mercurial/wiki/index.cgi/MercurialHosting (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:

Commit
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).

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

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

Merge
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.'

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

Branching

Introduction

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.

Version Control Guide

source control Branch (computer science) Repository (version control) Commit (data management) Merge (version control) teams Version control Eclipse Distributed version control

Opinions expressed by DZone contributors are their own.

Comments

Mercurial Guide

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

Installing Mercurial, And Eclipse Plug-In