Mercurial is an Open Source distributed version control system that offers you the power and speed to efficiently handle projects of any size and kind. Every clone contains the whole project history, so committing, branching, tagging and merging are local, fast and convenient. You can use a multitude of workflows and easily enhance its functionality with new or existing extensions. Come join us if you want to learn more!

There will be two main parts:

• Mercurial Kick Start: Martin Geisler will get you quickly up to speed on Mercurial. We will cover the important difference between centralized and distributed version control, and show the basic commands. The aim of the talk is to answer your questions about Mercurial, so we will try to make it very interactive.
• Mercurial Migration: Sune Foldager will describe how he helped migrate 150 developers from CVS to Mercurial. Why did they choose Mercurial over competing systems like Git? What changes did they make to their workflows and are they happy with the results?

The speakers:

Martin Geisler and Sune Foldager have both been involved in the Mercurial project since 2008 and are now part of the core developer team.

Martin moved from Denmark to Switzerland in the beginning of 2010 to work full-time as a Mercurial consultant for aragost Trifork. There he has helped several large European clients migrate to Mercurial by writing custom extensions, providing training, and helping with the implementation of new workflows.

Sune works in the infrastructure team for the Danish company Edlund A/S, with around 150 C# / .NET developers, and has been instrumental in switching their source control from CVS to Mercurial back in 2009. He has made several contributions to Mercurial concerning use and deployment in Windows environments, and working effectively with named branches.

The event is free! Please come along if you have little or no experience with distributed version control, but want to learn more. We expect you are familiar with an existing centralized revision control systems such as CVS, Subversion, or Perforce, and want to show you the new world of distributed version control.

• Introduction to Mercurial: this was a general talk about distributed version control in general and Mercurial in particular.

  Download the slides: PDF.

• Query Languages in Mercurial: this was described for both revision sets and file sets. The first is a very rich SQL-like query language for specifying revisions. This is a query which will show you a combined diff of all outgoing changesets:

  hg diff -r "outgoing()"

  The second is a similar language for specifying files in the working copy, which will let you do things like this to revert files not in the UTF-8 encoding:

  hg revert "set:not decodes('UTF-8')"

  Download the slides: PDF.

Distributed version control tools like Mercurial are faster and more flexible than the traditional tools like CVS and SVN. Mercurial is used by projects ranging in size from a single developer up to very large projects such as Firefox and OpenOffice.

The talk will have two parts: Martin Geisler from aragost Trifork will start by giving you an introduction to Mercurial and distributed version control.

Afterwards, Cedric Staub from Wyona will present a case study of how switching from Subversion to Mercurial allowed for greater flexibility in their development process.

Date: Tuesday, April 12th at 19:30
Place: Memonic, Badenerstrasse 120, 8004 Zurich

Please see the announcement on techup.ch for more details.

The Burton Group (part of Gartner) published a 25 page report on February 1st that does a pretty good job at describing the strengths and weaknesses of distributed revision control. It focuses on Mercurial and Git, which it calls the open source market leaders.

Strengths

The report says that distributed version control tools have unique features that can improve developer productivity. Some of the most important features mentioned in the report are:

• DVCS tools provide zero-cost, seamless branching.
• DVCS tools merge more efficiently and automatically than traditional CVCS tools.

In addition, the report stresses that tools like Mercurial and Git promote developer collaboration and communication and that both tools have large communities that provide extensive documentation and guidance.

I will add that the extra speed you gain by having local access to the source code history suddenly enables entirely new workflows: you can now search efficiently through the past history to find out when a bug was introduced. This is important to know so that you can provide your customers with a fixed release.

Weaknesses

The report also discusses some challenges in adopting a DVCS tool:

• The paradigm shift of DVCS tools may require process change and comes with a learning curve.
• Administrators may need to reorganize source code into several repositories.

This is true — making changes to an essential tool like a version control system will require changes in the way developers think and in how administrators work. We believe these changes are for the better, but there will be changes.

The report also says that no dedicated support exists for the leading DVCS tools since they are open source. While this might have been true some years ago, it is no longer the case: aragost Trifork provides a full range of support for Mercurial. We help you with the initial analysis and planning, with the actual migration, and with training of your developers. There exists similar options for Git and, as the report mentions on the very same page, there is extensive documentation and guidance available for both systems.

The report also claims that:

• Open source DVCS tools typically have lackluster GUI front ends, and some don’t port easily to Windows and OS X.

This is mentioned in several places throughout the report and I believe the reason for this is that the report makes a sharp distinction between the core tool (the command line tool you get from the Mercurial homepage) and third-party front-ends such as TortoiseHg. This distinction is unnecessary: TortoiseHg is the recommended way to install Mercurial on Windows and it comes with a full-features graphical front-end for Mercurial. You can use TortoiseHg for all your Mercurial work and you wont have to use the command line tool (which is installed as well in case you sometimes prefer it).

For Mac OS X we have the beautiful MacHg front-end, which is a full, native Mac OS X program that looks and behaves like any other program you would find on your Mac.

Finally, the report lists the license as a potential problem for Mercurial and Git:

• The licensing model of open source DVCS tools may be unacceptable to some organizations.

Both tools are licensed under the GNU GPL, the most widely used open source license. I think listing this as a problem is a red herring: you are not restricted by the license when you install and use Mercurial. The license grants you the right to install and use Mercurial on as many machines that you like and it grants you an additional right when it says that you can also distribute derived versions of Mercurial under the GPL. You or your company will not be making any derived versions of Mercurial — your company will most likely have enough to do with producing and selling its own software.

Download

The report is unfortunately not free, but you can buy a copy online.

If you are in the area, then you should consider joining! Come talk to us on IRC and put your name on the wiki page linked above. We will sponsor beer and soda for the event, so you wont be thirsty!

• Martin Geisler: A core developer of Mercurial. Lives in Zürich and work for aragost Trifork ag as a Mercurial consultant helping others with Mercurial.
• Aaron Digulla: A Mercurial user and works as a Senior Java Developer at Avanon in Zürich.
• Klaus Bucka-Lassen: A Mercurial user and managing director of aragost Trifork ag. He lives in Switzerland where he is mainly works as a technology consultant, project leader, architecht and software developer.

Mercurial

Fast, scalable revision control

Abstract: Distributed revision control is now widely used in the industry and by many open source projects. This article takes a closer look at Mercurial, one of the fastest and most user friendly distributed revision control systems, and explains how it works and why you would want to use one.

Introduction

Just like Subversion solved many of the problems with CVS, distributed revision control systems like Mercurial and Git solve many of the issues with Subversion. They are faster, more flexible, much better at handling branches and merges, and encourage a better style of development.

The main issue with Subversion and similar centralized revision control tools is that they fail to help users when they need it most. Instead of being an ally that provides a safety net for your experiments, centralized tools discourage experiments and many developers come to see them more as a burden than a help. A new wave of distributed version control systems changes these things drastically, and this article will show you how.

The core feature of a distributed revision control system (DVCS) is the distribution of history — instead of having just a single repository stored on a central server, you now have many redundant repositories. In fact, each developer has his own, private repository.

By moving the full project history out to the developers own machine, a lot of operations suddenly become very fast. When things are fast, people tend to use them more. This means that developers will want to make more and better commits with Mercurial. When a commit takes 0.1 seconds instead of 3 seconds (or more), then you will begin making more logical commits. Small commits that each contain one coherent change are easier to review. This will be elaborated below.

Mercurial is an open source and cross platform system used by large organizations such as Mozilla Foundation (Firefox, Thunderbird, …) and Sun (OpenSolaris, Java, OpenOffice…) as well as many other companies and open source projects.

Key Concepts

There are a number of important concepts that must be understood to work efficiently with Mercurial.

Working with a Single Repository

The first is the notion of your working copy. This is where all the files in your project live and this is where you edit them. When you make a commit, the changes made in the working copy are saved as a new changeset. Changesets are also often called revisions, just like in Subversion. The changesets make up the project history and live in the repository, which is always stored in the .hg/ directory at the root of the working copy. See Figure 1.

Figure 1: Local and remote operations.

The working copy reflect a given checked out revision, the so-called working copy parent revision. When you ask Mercurial to show the file statuses, your files in the working copy are compared to how they looked in the parent revision. You can ask Mercurial to update the working copy to reflect another revision. When you commit, the changeset you create is always a child revision that descends from the current working copy parent revision. This parent information is stored in each changeset so that it knows where it came from.

Working with Several Repositories

Repositories can be cloned and this makes a full, independent copy of all the history. This is how a developer gets access to the source code initially: he clones it from some well-known location such as a central server in a company, or a homepage for an open source project. Having made his own private clone, the developer can explore the history and make new changesets, all without talking to the server he got the clone from. When new changesets are made in the server’s repository, he will pull them into his own clone. The symmetric operation is push: he uses that to push his new changesets back to the server. The two commands simply compares the two repositories and transfers missing changesets.

When changesets are copied from one repository to another, the parent information stored in each changeset is critical: it is used to insert the changesets at their right position in the history. The result is a graph of changesets as shown in Figure 2.

When changesets pulled and pushed between repositories, small branches appear in the history. They represent parallel lines of development, e.g., if Alice created a new changeset A and Bob created a new changeset B, and if both A and B descends from changeset X, then after pulling B into her clone, Alice will see two branches starting at X. The changesets A and B have no children and such changesets are called heads. Two heads represent divergent lines of development and should normally be merged back together. Small branches are created all the time. Compared to older tools such as Subversion, Mercurial has a much more robust merge engine that works correctly in face of renamed files and similar corner cases.

The command line interface for Mercurial is called hg, named after the element mercury. Just like the svn program for Subversion, the hg program has a number of sub-commands. The most important commands are listed in Box 1. Notice how they match the commands from Subversion closely — Mercurial has been designed to make transition from Subversion as painless as possible.

Box 1: The most important commands in Mercurial.

Historic Background

The need for keeping track of source code has existed ever since the first source code was written. There are therefore a long tradition of making revision control systems. The first generation of revision control systems worked on a single file basis only. The classic RCS program (which is simply short for „Revision Control System“) is an example of such a system and dominated the scene in the 1980s.

The second generation of revision control systems came with CVS, short for Concurrent Versions System. CVS and its proprietary cousins handle multiple files and support network operations. CVS enable several developers to work concurrently on the files and then merge their outstanding changes when committing them to a central server. CVS became extremely widespread in the 1990s. In 2000, Subversion (SVN) was released as a „better CVS“ and has since then replaced many CVS installations.

The two first generations relied on a single central server to store the history. A third generation of revision control systems is starting to remove this central server and instead offer a fully distributed workflow instead. These distributed version control systems started to appear in the beginning of this millennium, but the development really took hold in 2005 with the release of Mercurial and Git.

Git and Mercurial both has the same historic background. In 2005, the source code of the Linux Kernel was kept in a proprietary system called BitKeeper. The kernel developers received a free license to BitKeeper under the condition that they would not themselves work on competing products. However, this free license was revoked in the beginning of 2005, when a kernel developer made a third-party tool that would talk to the BitKeeper servers.

This unleashed an enormous activity in the Linux Kernel development community where a small army of very skillful programmers suddenly found themselves without a revision control system. Hackers as they were, they sat down and made their own. Linus Torvalds made a system he called Git and another kernel developer, Matt Mackall, called his system Mercurial, abbreviated „hg“ after the chemical symbol for mercury. Today, the Linux kernel is kept in Linus’ system with a Mercurial mirror.

The Problems with Traditional Tools

Traditional version control systems such as Subversion use a client-server architectures with a central server to store the revisions of a project. This has two negative consequences:

1. The clients must contact the server over the network for almost all operations. Subversion support diff without talking to the server, but that is it. It only supports a very limited form of diffs: you can compare a file with the working copy base revision, but not with any other revision.Contacting a server over a network connection takes much longer than accessing data on a local disk and this slows down development. The natural reaction from developers is to use the revision control tool less. Instead of making small, consistent commits they make larger commits in order to avoid talking to the server. Large commits that mix different changes are much more difficult to review and this hurts the code quality.
2. With a centralized system, every commit is published immediately for all to see. It is not uncommon for people to wait with a commit because they are afraid of breaking the build.This means that people instead sit on their uncommitted changes for days or weeks without committing. So instead of encouraging developers to track their progress step by step (including false starts), a centralized tool makes people not want to use it.Branches are supposed to help solve this problem: each developer gets his own branch where he can make all the mistakes he want without disturbing the rest of the team. However, branches are only interesting if you can merge them again!Subversion has very fragile merge support: try merging a branch with a renamed file that has also been modified on trunk. Depending on the version, Subversion will either say there is a conflict or it will silently(!) throw away the change. This bug has been there for years.The fact is that merging is a hard problem and tools like Subversion do not support it very well. The result is that people either avoid branches and sit on their code for a long time, or that they use branches but are burned when they try to merge them again.

Benefits of Distributed Version Control

In Mercurial, the history is stored redundantly on several servers. Each developer has local access to the full history and this makes it very fast to work with. When switching to Mercurial, people naturally tend to make much more fine-grained commits simply because it’s easy and fast.

Also, when developers commit changes to their own local repositories, the repositories begin to diverge. The histories are brought back in sync with a merge — so by necessity, Mercurial has excellent support for merges. Branches are created and merged back together on a daily basis and become a natural part of the workflow.

Branches are an enormously useful concept and with a distributed system, developers become used to working with them. They can therefore use them efficiently on all scales: for a small bugfix or for tracking major lines of development.

Better Workflows

Mercurial gives a better workflow for the individual developer or within a single team. But being distributed also makes it possible to improve workflows that involve several teams. A great example of this is off-shoring. With Subversion all teams but one must suffer from extra-long network round trips since there is only one server.

Mercurial allows you to put a hub at each site. The developers use this to get quick, local access to each others changes. The hubs are then synchronized periodically. You simply don’t get this kind of flexibility with a centralized system.

Figure 3: Globally distributed development with local hubs.

Changes flow from one repository to another and it is straight-forward to impose conditions on when a change can move to another repository. This can be used for mandatory code reviews: developers push their changes to a holding-repository where they sit until a reviewer approves or rejects them. This reviewer could be a team-leader or it could be an automated continuous integration system. When a change passes review, it is pushed further along to a central repository. The other developers will then see it and they can then integrate it into their own repository.

Implementation

The preceding sections looked at Mercurial from a very high-level view — this section will dive right into the nitty-gritty details of how Mercurial is implemented. Mercurial tracks three things:

1. Changes to file content (file edits)
2. Changes to the file tree (added and removed files)
3. Information about who made the above changes

The history of each file under revision control is kept in a filelog stored under .hg/store/data/. For files with a large history, there are actually two files: a file.i which holds an index and a file.d which holds the revision data itself. While this may look innocent in itself, it turns out that filenames are a somewhat messy subject.

Encoding Filenames

Mercurial repositories are often put on memory sticks and carried around to different computers with different operating systems. Different operating systems have different opinions on what constitutes a valid filename: Linux filesystems generally allow any byte except “\0” and “/“, Windows filesystems are more restrictive and disallows characters such as “:” and “?” but also normal looking filenames such as “aux” and “nul” (they are DOS device files and still reserved today). Mercurial needs to ensure that files stored under the .hg folder are readable on any filesystem. The filenames are therefore encoded to a safe subset of ASCII.

While this mapping ensures that a repository can be copied around between different machines, it does not ensure that one can always make a successful checkout. In other words, there is nothing that prevents a Linux user from adding a file called aux. The history for this file will be stored in.hg/store/data/au~78.d, which is a legal filename on a Windows filesystem. So a Windows user can pull the changeset and browse the history using TortoiseHg, say, but he cannot use hg update to checkout the file. There is an extension for Mercurial called caseguard which can be enabled to catch such problems. It was originally designed to prevent the more simple problem of a Linux user adding files that differ only in the case of the filename.

The file tree is tracked in a file called the manifest. The manifest looks similar to the output of ls -Rexcept that there is a hash-value stored for each file. The manifest changes as files are added and removed from the tree, and the hash values change when the files are modified. To reconstruct the project as it stood at a certain revision, one simply has to reconstruct the right revision of the manifest and then use this to lookup the right revisions in the referenced filelogs.

Finally, the who-did-what part is tracked in file called the changelog. When a new commit is made, metadata such as username, date, and the commit message is recorded in the changelog file. The changelog also points to a particular revision of the manifest in order to tie the change to a particular file tree.

The Revision Log

The basic building block in Mercurial is the revlog, which is short for “revision log”. This is an append-only data structure that is used to implement both filelogs, the manifest and the changelog itself. A revlog stores a series of revisions and does so in a simple, yet efficient way. When a new revision is added – such as a new version of a file in case of a filelog – the delta (difference) between the last revision is computed and compressed. The compressed delta is appended to the revlog. However, simply appending deltas like this would make it increasingly expensive to reconstruct new revisions of a given file since one would have to read and process all the differences since the very first version. To prevent this, the revlog automatically stores a compressed snapshot of the file if it determines that the chain of deltas has grown too large. This ensures that the time needed to reconstruct any revision of the file does not grow when the number of revisions grow.

Furthermore, the revlog is append-only: when a new revision is added, the compressed delta or the compressed snapshot is simply appended to the file. The primary benefit of this is that any revision of a file can be reconstructed using a single seek to find the beginning of the delta chain (or snapshot) and a single read operation to read the needed deltas (or snapshot). By avoiding seeks, the data can be read very efficiently by a normal hard drive. A secondary benefit is that appending to files is inherently more safe than rewriting them. If the computer crashes while Mercurial is appending to one of its files, then it is easy to recover to a known good state: simply truncate each file to its original length (which was stored at the beginning of the transaction). The user can then re-do the commit or pull operation.

Avoiding Locks

Mercurial is a multiuser system where several users may push changesets to a central server at the same time while other users are pulling changesets. Mercurial must ensure that this is done in an orderly fashion without people stepping on each other’s toes.

As described above, the final file data is found by first visiting the changelog. This points to a manifest, which in turn points to the filelogs. When new changesets are added to a repository, the data is written in the opposite order: first the filelogs are extended, then the manifest is written and finally the changelog is updated. This can be done concurrently with readers since they wont notice or care about the new data until they see it referenced from the changelog. Reading can thus be done without taking any locks at all. This is rather important since read operations are by far the most common operation and also because the reader quite often cannot expect to be able to take a lock due to filesystem permissions (you should be able to clone a repository with nothing but read-access to the files in the repository). Multiple writers need to lock the repository to serialize their access to the files.

Figure 3: Relationships between the changelog, manifest, and file logs.

Identifying Changesets

Each changeset in Mercurial is given a unique identifier. With a centralized system it is easy to use sequential integers as identifiers: the clients simply ask the server for the next number in the sequence. With a distributed system where the clients must be able to work in complete isolation, something more clever is needed. First of all, it is clear that a simple integer sequence won’t be enough when identifiers must be globally unique – if Alice calls her changeset number 37, then Bob won’t know about it when he is working in a train without an Internet connection.

One possibility would be to assign a completely random identifier to each changeset. Given a sufficiently large space of identifiers, the risk of a collision can be made arbitrarily small. For example, one could make the risk smaller than the chance of winning the lottery – not just winning a single time, but winning again and again, every day of your life!

There is a better alternative, though: using a cryptographic hash function. A cryptographically secure hash function H takes an input string of arbitrary length and maps it to an output of fixed length, say, 160 bit. To be secure, a hash function must be hard to invert, that is, given a hash value h, it must be extremely difficult to find an m, such that H(m) = h. It should also be hard to find two different messages that hash to the same value. Hash functions play a key role in modern cryptographic systems.

Armed with a cryptographically secure hash function (Mercurial uses the industry standard SHA-1 function and we plan to switch to a more secure hash function when SHA-1 is broken in the future), it is now possible to construct changeset identifiers (changeset hashes) in a completely systematic way and still avoid the problem of Alice and Bob assigning the same identifier to different changesets. The key trick is to use the content of the change itself together with the changeset hashes of the parent changesets as input to the hash function.

Concretely, each Mercurial changeset is identified by a 40 character hexadecimal hash value – though only 12 characters is shown in the interface by default since this is normally more than enough to differentiate changesets. The hash value is computed from these components:

• The manifest hash
• The username
• The current date
• The commit message
• Hash value of first parent changeset
• Hash value of second parent

The manifest hash is computed in a similar fashion by giving the filelog hashes as inputs to SHA-1. The filelog hashes themselves originate from the actual file content. This design ensures that a byte in a file affects the filelog hash, which in turn affects the manifest hash, which in turn affects the changeset hash. Put differently: because it is infeasible to find collisions for the hash function, the changeset hash fixes the manifest hash. This means that if you are given the changeset hash from a trusted source, then you can download everything else from an untrusted server and afterwards verify the integrity of the data. You know that it is infeasible to find two manifest hash values that gives the same changeset hash, so when you have retrieved one manifest hash from the untrusted server, then you can be sure it’s the correct value when it gives the correct changeset hash. Similarly for the filelogs: if they hash to the correct manifest hash, then they must be correct with overwhelming probability.

Because the changeset hash include the hash values of the parent changesets, the entire history of the repository is included in the hash value! Given a trustworthy changeset hash, it can be verified that the parent hash values are trustworthy. The integrity of the entire history graph can be verified by walking backwards from the tip-most changeset to the root in this recursive fashion.

Using a cryptographic hash function to verify the history like this was pioneered by the Monotone distributed revision control system and has since then been used in both Mercurial and Git.

Upcoming Features

There is a growing community around Mercurial that continuously add new features and fix bugs. We will focus on two features below which will hopefully soon be included in Mercurial.

Shallow Clones

A Mercurial repository can grow large over time as changesets are added and as more and more files are put under version control. While the technological advances in harddisk sizes and bandwidth will be able to keep up with the expansion to some extend, it would often be nice if one could work on only a subset of the files or a subset of the history. The first feature is called “narrow clones” since they only clone a narrow subtree of the full project tree, and the second feature is called “shallow clones” since they only clone a shallow part of the full changeset graph.

Mercurial participates in Google’s Summer of Code program and three students will spend their summer implementing new features, see Box 2. In particular, a student will work on implementing shallow clones. Shallow clones are often requested by organizations that have converted a very old CVS repository to Mercurial – say with 10 or 20 years of history. For their day to day development, they don’t need access to the ancient versions of the code, and so a shallow clone would be a nice way to save on the bandwidth and disk space needed.

Kasten 2: Google’s Summer of Code program.

The way history is stored by Mercurial lends itself well to shallow clones. The history for each file is stored sequentially in a single revlog, and by collapsing the first N revisions of a revlog into a single snapshot, one can effectively exclude the first N revisions. This snapshot will naturally have the wrong SHA-1 hash value, so Mercurial will have to be taught to ignore this for shallow clones.

The main difficulty in implementing shallow clones is in the handling of merges. If the changeset graph is simply cut off at a certain depth below the tip, then you may lose important information needed for correct merges. This could be information about renamed files: if old.txt is renamed to new.txt in a changeset that is not part of the shallow clone, then Mercurial will see the two files as independent. Merging will therefore give a different result in a shallow clone compared to a full clone.

This is of course not acceptable, so the current proposal for shallow clones requires that there must be a single root for a shallow clone. This means that if you want to make a shallow clone that involves changesets on two different branches, then you must extend the shallow clone back to the first common ancestor changeset between the two braches. This not a very limiting requirement since most projects have regular points in time where all branches are merged into a single changeset, e.g., when a release is made.

When a shallow clone contains a single root changeset only, then merges will be identical to merges in full clones, which is what we want for consistency and to make the mental model simple for the users. When the summer is over, then it will be known if the student succeeded with the project.

Dealing with Big Files

One area where distributed version control systems have a disadvantage compared with centralized systems is in handling of very large files. Large files tend to be compressed already (think of images or movies), which means that they cannot be compressed any further. To make things worse, even a small change to a binary file can lead to a very different file on disk, so the deltas between each revision will also tend to be large.

When the entire history is stored on each client, a big file will keep taking up space everywhere and initial clones will take longer because they need to transport more data. In a centralized system, you can simply delete a big file again if you added it by mistake and it will then only be the server that has to keep a copy of the file. After the file has been deleted, a checkout will again be fast since the clients only retrieve the last revision from the server.

Greg Ward, a long time Python developer, has written an extension for Mercurial called bfiles. It combines the strengths of both centralized and distributed version control by storing the big files in a central location, while letting you work with all the smaller files like normal. When you retrieve a clone of your Mercurial repository, you only retrieve the small files plus a number of “stand-in files”. These stand-in files are small files that reference the big files by the SHA-1 hash value of the big file. Using the stand-in files, Mercurial can now retrieve the needed big files. This saves you from downloading the entire history of each big file – you only get what you need. All the revisions of the big files are still stored on the server, but since storage space is cheap, it is no problem to add more disks to a central server. This design gives you the best of both worlds: you get the full history for your smaller files so that you can still search through them with hg grep and you can still compare them with hg diff, and you save disk space on the clients and bandwidth when making a clone.

The extension currently requires the use of a number of special commands such as hg bfupdate after a hg update to actually update the big files. When complete, the extension will allow full integration in the normal Mercurial workflow in order to make the use as seamless as possible.

Conclusion

Developers are smart people — if you give them a slow or tedious tool to work with, their natural reaction is to use it as little as possible. This means making bigger commits in order to not have the tool talk too often to the server. Mercurial solves this problem in the most elementary way possible: by distributing the server to all the clients. Making a commit is now a fast operation and with the history at hand, developers can begin using the history to their benefit when tracking down bugs. Being smart people, developers will see that it now pays off to make more fine-grained commits, each with a small logical unit of work.

Since Mercurial is a distributed tool, it must be good at merging branches. Developers will be merging daily and they will thus also become very familiar with it. When dealing with longer lived branches for new features, it is also important to merge often. Mercurial remembers what you have already merged and you can therefore do repeated merges of the main branch into your feature branch. This is the key to making merging manageable: do it often in order to keep the merge conflicts that you must deal with small. Mercurial is not magic, but it helps you as much as possible by keeping track of things and by ensuring that the conflicts you get are genuine.

There is a very friendly community around Mercurial. Everybody is welcome and encouraged to join the mailinglist or to come online in the #mercurial, our IRC channel at irc.freenode.net for a direct chat with the developers and other users.

Acknowledgements

The author would like to thank Greg Ward and Benoit Boissinot for their helpful comments.

Literatur & Links

• Mercurial Links
• Mercurial: The Definitive Guide
• Hg Init: a Mercurial tutorial
• Towards a Better SCM: Revlog and Mercurial
• Bfiles extension

Saturday, January 15th at 9:00

in the aragost Trifork office at Buckhauserstrasse 40, fifth floor. I will be there from the morning, but you are welcome to pop by whenever it suits you best. Please send me a mail first so that I know how many people to expect. We will probably continue until we go out for dinner in the evening.

This post will go through the very basics of using Mercurial from within Eclipse, via the MercurialEclipse plugin.

Getting the Plugin

The MercurialEclipse plugin can be installed either from Eclipse Marketplace, under Help → Eclipse MarketPlace… or from an Eclipe 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.

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… (Img 1)

Img 1

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

Img 2

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

Img 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 (Img 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.

Img 4

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 (Img 5)

Img 5

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

Img 6

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

Img 7

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

Img 8

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

Img 9

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

Img 10

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… under 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 (Img 11).

Img 11

After you have set the options for pushing, then a new dialog window is shown (Img 12). Here it is possible to see all the changesets thats 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.

Img 12

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

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

Img 14

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.

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

Img 16

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

Image 19

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

Img 20

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

Img 21

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

Img 22

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.

[extensions]
color =

That will make Mercurial load the extension. Since it is a standard extension, you don’t have to tell Mercurial where to load it from and you can thus leave the right-hand side empty.

This is all the setup needed — your output will now go from

to

Notice how even the simple hg log command benefits from the color extension. By highlighting each changeset with a yellow line, it becomes much easier to scroll through the output with eyes.

The change in hg diff and hg status is even more profound. After using the color extension for a while, I am sure you will also find it almost impossible to read a diff without any highlighting.

It is possible to customize the colors used by the extension. If you want to have the output of hg diff look like it has been piped through colordiff, then use

[color]
diff.diffline = green bold
diff.file_b = blue bold
diff.hunk = magenta bold
diff.deleted = red bold
diff.inserted = blue bold

Put those lines into your configuration file to make them take effect:

As you can see, there are a number of labels and each is assigned a color. The color names are: “none”, “black”, “red”, “green”, “yellow”, “blue”, “magenta”, “cyan”, “white” for foreground colors, and the same names with “_background” appended to set the background. After choosing a color, you can decide to make it more intensive by adding the keyword “bold”, you can make it underlined with the keyword “underline”, and you can ask for reverse video with “inverse”.

In addition to the labels I showed you above for customizing hg diff, there are other labels for hg status, hg log, etc. See hg help color for the full list.

If you miss color support for a particular command, then please write the Mercurial mailinglist and I’m sure we can help you.

Re-posted from the Trifork blog:

Abstract:

Are you curious about how you can improve your workflows with Mercurial? In this Geek Night, Martin Geisler from aragost Trifork will introduce you to Mercurial, a fast distributed version control system used by large projects such as Firefox and OpenOffice. You will see first-hand how Mercurial is much more light-weight and flexible than legacy systems like CVS, Subversion, ClearCase, etc.

Following the introduction, Gonzalo Casas from isonet ag will describe how and why they migrated 20 developers from Subversion to Mercurial. You will learn how the robust support for merging in Mercurial makes it feasible for them to manage long-term maintenance branches, while still being able to easily create new branches for new features.

Speaker Bios:

Martin Geisler holds a PhD in Computer Science from the University of Aarhus, Denmark. He has been involved in the Mercurial project for three years and is now a member of the core developer team. He relocated to Zurich in the beginning of 2010 to work full-time as a Mercurial consultant for aragost Trifork.

Gonzalo Casas studied Computer Science at the University Siglo 21, Córdoba, Argentina. He currently works for isonet ag as a software engineer and has been in charge of migrating from Subversion to Mercurial and maintaining the Mercurial repositories and the development process on top of it.

Language: English
Place: Technopark Zurich
Date & Time: 13th January 2011, 17.00
Price: Free
Registration: Please send name and company address to Serife Cakmak.