Manage code with Mercurial – tutorial
Use Mercurial to manage your source code and the TortoiseHg GUI to manage the infrastructure
Mercurial is a powerful open source version control system. It is available for all major platforms, which is why it tends to be a popular option. It’s an easy-to-use yet powerful system and is loaded with advanced features, without being too hard to grasp.
This tutorial covers the basics and you’ll be up and running in no time. We’ll show you how to avoid the commonplace but inefficient version- per-folder method used to keep track of different versions of files. Mercurial makes it easy to compare your file versions and see the changes between many different versions, even when they are several generations apart.
This tutorial also covers the installation and use of TortoiseHg, one of several GUIs available that complement the command-line installation and make management much easier.
Mercurial is flexible enough that it can meet the requirements of the most demanding users or projects and can cater for distributed version control with multiple users. In this article, though, we are going to focus on the local features for a single user.
Step 01 Install Mercurial
Installing Mercurial is easily accomplished. Most Ubuntu derivatives have it available as standard. To install it, open a shell and issue the following command:
sudo apt-get -y install mercurial
You will also need to manually configure the .hgrc file. In your home directory, edit the .hgrc file. This is a very minimal configuration. Below, it is done with the gedit command:
Add the ‘[ui]’ line followed by the line starting ‘username’. Use your name and your email address, with angled brackets, as is shown in the screenshot above.
Step 02 Configuring a repository
Create a new working folder to contain your files, and change directory into it:
mkdir work cd work
This example uses the folder ‘work’ for our repository. Now we need to initialise our repository. Do this by issuing the command:
hg inithg add example.txt
The command allows the additional files into the repository. You can commit several files using the same command.
Step 03 Committing changes to a repository
At this point the changes made aren’t persistent. A point-in-time copy is needed, also known as a commit. To commit the change, use the following command:
(or hg ci for short)
Navigate down the editor window and fill it in with a useful comment! To save filling in all the details each time a commit is needed, it is possible to specify the comment using the -m switch, as is shown below:
hg commit -m "This is a comment about our first commit"
Step 04 Working with changes
The system now has a point-in-time copy of the data. Add an additional line of text to our example.txt file. Commit this change as per our first commit with a different comment. Use the hg commit -m command. As there are now two point-in-time copies, we can revert to the previous copy if we need to. To revert back to the earlier version, just use the command:
hg update -r 0
All files revert to the last commit. Commit the change to save changes.
Step 05 Using Mercurial history
Perform a few more changes and commits. To view a list of commits to the repository, use the command:
This shows all the commits made over time, with the comments that where added. Note the ‘tip’. This means this is the current live version of the file. View the difference between versions using:
hg diff -r 0 -r 3 example.txt
See the differences between selected revisions using the -r switch. See what has been added where it’s prefixed with ‘+’ before the second line.
Step 06 Reverting to earlier changes
The rollback feature is not just limited to the latest save, but if the earlier rollback wasn’t rolled back far enough, it can be rolled back further. This is achieved using the hg revert command:
hg revert -r
The change number is the commit version assigned when it was created. For example:
hg revert -r 0 example.txt
Doing the above will revert to the very first instance of this file that we created. Don’t forget to commit to save the rolled-back versions!
Step 07 Using the built-in web server
A very interesting and useful feature of Mercurial is that it has its own built-in web server that runs a change-viewing system. To initiate this system, use the following command:
This starts a web server. Notice that the port number is 8000. Use Ctrl+C to kill the web server process. This is a great way to set up to allow anyone to connect and download the latest copy of your repository. They can download a copy of your repository using the command:
Step 08 Creating a test clone
One of the nice features of Mercurial is the clone command. It allows for unlimited experimentation with the data but leaves the real copy behind. Using the hg clone command saves the changes to the new repository. It also creates a hard link that allows you to, in effect, copy an entire repository to test with.
To clone a repository, use the command:
cd mkdir new-work hg clone work new-work
This will create a new clone. Before running the command, make sure the folder new-work exists, otherwise the command will fail.
Step 09 Introducing the TortoiseHg user interface
All the above can also be done using TortoiseHg, for those who prefer a GUI. Open a terminal session and use the following command:
sudo apt-get install -y tortoisehg
To start using TortoiseHg, use the command:
Go to File and click Open Repository. Navigate to the work directory we are using and click Open. Note that all the windows are now populated. Once you’ve finished working with the repository, close it by using File>Close. The repository will, however, be remembered for future use.
Step 10 Basic use of TortoiseHg
As you can see, the area is split into several windows. Most are fairly self-explanatory. Notice that the comments from the earlier revisions are there. Use gedit or similar to create another file with comments in it. To add a comment for our new file, click in the comments box and enter a descriptive comment. To commit our changes to the system, select Commit.
Step 11 Adding more files
A project of any size will have more than one file. Don’t forget that a commit is just a point- in-time copy. The TortoiseHg system will pick up the extra files that you add to your folders and ask if you wish to commit them. You may need to press the refresh button on the file selection box to see additional files. It will ask to add the untracked files; click Add. This will then keep track of the file through all your revisions.
Step 12 Creating a Mercurial backup
Backing up Mercurial is straightforward. As well as the actual data files that you work on, there is a hidden folder called .hg located in the repository folder. This holds all the versioning and commit data. Therefore, backing up manually would work fine as long as the hidden folder is backed up. Alternatively, you could use the following commands:
cd hg clone -U work work.hg
Follow up with a normal backup of the files in the repository and then restoring it will be as easy as restoring the files and importing the clone data.