Support free tutorials:

vogella training Training Books

Mercurial - Tutorial

Lars Vogel

Version 1.1


Revision History
Revision 0.1 13.09.2009 Lars
Revision 0.2 - 1.1 12.11.2009 - 27.06.2011 Lars
bug fixes and enhancements

Mercurial Tutorial

This article describes the distributed version control system Mercurial.

Table of Contents

1. Overview
1.1. Distributed Version control system
1.2. Mercurial
2. Installation
2.1. Installation on Ubuntu
2.2. Installation on Windows
3. Mercurial usage with the command line
3.1. Overview
3.2. Prepare
3.3. Create Java Project
3.4. Add Project to Mercurial and commit
3.5. Making changes
3.6. See changes
3.7. Revert
4. Support this website
4.1. Thank you
4.2. Questions and Discussion
5. Links and Literature
5.1. Mercurial Resources
5.2. MercurialEclipse Resources
5.3. vogella Resources

1. Overview

1.1. Distributed Version control system

With a distributed version control system you basically do not have a central code repository but everyone has its own branch. To can clone a branch and you always get the full history of the whole branch on your system. You commit into your own branch and you can push your changes to other repositories and other people can pull from you.

The main advantages of distributed version control systems are

  • Speed: As the whole repository is offline available you can much faster search and compare

  • Commits: Everyone can commit to his own branch

Another popular distributed version control systems is Git.

1.2. Mercurial

Mercurial is a distributed version control system. Mercurial is used by Oracle for the OpenJDK development and offered as a option by Google in Google hosting.

Mercurial is written in Python. Mercurial has a command-line interface. Eclipse provides also a plug-in to use Mercurial.

2. Installation

2.1. Installation on Ubuntu

Install Mercurial on Ubuntu via:

sudo apt-get install mercurial 

The installation of Mercurial for other platforms is described in Mercurial installation.

2.2. Installation on Windows

You find binary packages for Mercurial on Window on Binary packages for Windows.

3. Mercurial usage with the command line

3.1. Overview

The following will demonstrate a short development cycle using the command line interface of Mercurial.

You will create a new Mercurial repository, create a new Java project and commit the changes to your Mercurial repository.

The command for using Mercurial on the command line is "hg".

3.2. Prepare

Check that you are using Mercurial version 1.3 or higher:

hg --version 

Create and switch to your desired work directory .

Initialize a new Mercurial repository with:

hg clone name_of_directory_for_the_clone 


If you have an existing project you could clone, e.g. create a copy of, your repository via the following command.

hg clone name_of_directory_for_the_clone 

Eclipse creates a lot of metadata with regards to the current status of the Eclipse workbench. Also Eclipse creates compiled version in the directory bin. This data should not be placed in the mercurial repository. Create the file ".hgignore" in the same directory as the hg project.

# switch to regexp syntax.
syntax: regexp

3.3. Create Java Project

Start Eclipse and use the new directory as workspace. Create a new Java project "de.vogella.mercurial.firstproject". Create the following Java class.

package de.vogella.mercurial.firstproject;

public class Test {

/** * @param args */
public static void main(String[] args) { System.out.println("Hello Mercurial"); } }

3.4. Add Project to Mercurial and commit

Add the project to Mercurial.

hg commit -A -m 'Commit with automatic addremove' 


hg commit -m "Create new project" 

If you have checked out the Mercurial project from another site you can push your changes to the repository.

hg push 

Check the history via:

hg log 

3.5. Making changes

Rename your Java class to "TestNewName" and create a new class "Test2".

package de.vogella.mercurial.firstproject;

public class Test2 {

/** * @param args */
public static void main(String[] args) { System.out.println("Hello Mercurial"); System.out.println("This is a new class"); } }

Add the new files to Mercurial.

hg commit -A -m 'Commit with automatic addremove' 

A rename in Java removes the old file. Mercurial will report these files as missing (hg status). You can use the following command to automatically add the new files and remove the deleted.

Add the new files to Mercurial.

hg addremove 

You can now commit. The -A flag in the commit command would also automatically add and remove new files.

hg add . 

3.6. See changes

To see the changes use the status command. diff we show the differences.

hg log
hg diff 

3.7. Revert

You can revert the changes via "hg revert".

hg revert de.vogella.mercurial.firstproject/src/de/vogella/mercurial/firstproject/ 

4. Support this website

This tutorial is Open Content under the CC BY-NC-SA 3.0 DE license. Source code in this tutorial is distributed under the Eclipse Public License. See the vogella License page for details on the terms of reuse.

Writing and updating these tutorials is a lot of work. If this free community service was helpful, you can support the cause by giving a tip as well as reporting typos and factual errors.

4.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

4.2. Questions and Discussion

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

5. Links and Literature

5.1. Mercurial Resources Mercurial Homepage Mercurial Wiki Free Online Mercurial Book from Mercurial Hosting service Mercurial: The Definitive Guide How to convert svn to Mercurial at Google hosting

5.2. MercurialEclipse Resources EclipseMercurial plug-in homepage EclipseMercurial change logs Mercurial Eclipse Bug tracker

5.3. vogella Resources

vogella Training Android and Eclipse Training from the vogella team

Android Tutorial Introduction to Android Programming

GWT Tutorial Program in Java, compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put all your files in a distributed version control system