Points Software Engineering recently adopted Mercurial (hg) for version control. This post explores our decision and presents some of our intro materials for developers new to Mercurial.

If you love Git, never fear! There are enough similarities in adopting any DVCS that you’ll likely find this useful.

Welcome to the Party

If you’re just arriving at the DVCS party, you’re late! Mercurial and Git have been around since 2005. Many organizations are stuck on legacy version control: Subversion, Perforce, ClearCase, or other horrors. Distributed version control eliminates the need for a central repository (though we commonly end up with one for other reasons).

DVCS is awesome because it:

  • Massively parallelizes development.
  • Brings amazing new merge functionality.
  • Automatically detects renames and moved files.
  • Deeply understands file parenting across branches and renames.
  • Tracks (binary) changes to the repo rather than individual file changes.
  • Facilitates exploratory development through effortless branching.

This is true whether you use Git, Mercurial, or Bazaar.

Our Intro to Mercurial Slides

You can read our intro slides here: http://slidesha.re/nWG9mz

Decision Factors

When deciding on a DVCS at Points, it was largely a Git vs Mercurial debate. We considered numerous factors:

  • How familiar were our developers with each?
  • How much did our devs want a specific DVCS? Any fanatics?
  • Who could champion Git or Mercurial?
  • Who’re our Git or Mercurial gurus?
  • How easy is it for developers to learn? (From scratch.)
  • How good are the supporting tools? UI tools? IDE plugins?
  • How easily can we host central repos internally? GitHub, Bitbucket are not options for legal reasons.

The Decision

We’d love to regale you with tales of nerf gun wars and an epic final battle where Git emerged victorious, but that didn’t happen.

We answered the above questions methodically, sent surveymonkey to our devs to gather opinions, and had discussions among the leads and devs. Our answers skewed heavily to Mercurial over Git.

The two biggest factors for us were the supporting tools and ease of learning.

Ease of Learning

If someone told you that you had to explain to a Subversion user Git’s staging area and 2 step commit, how Git handles workspace changes, the difference between reset and checkout, how to attach and detach remote branch tracking, how to merge the latest fetch… would you look forward to it? Or would you ask the user to plz RTM?

One of Mercurial’s greatest strengths is ease of use. Most of the time, it does what you expect, especially if you’re coming from Subversion. It’s very easy to explain to someone without them knowing Mercurial internals. One of Git’s biggest failings is that you really have to understand how it’s implemented in order to avoid paralyzing mistakes.


There’s a condescending tone to much of the Git literature, implying that if a user’s reading those docs, they must be too dumb to use git! You’ll see a lot of that same attitude in the heated Git vs Mercurial debates.

Mercurial’s docs are a mixed bag. There are great tutorials and a wonderful, free book. Thankfully they’re missing the “you’re numpty if you don’t know Git’s object DAG impl”-tone. Unfortunately some of the more advanced Mercurial docs are incomplete and their wiki is a hodgepodge of outdated info.

Try this sometime:

  • git help commit
  • hg help commit
  • git help merge
  • hg help merge
  • git help reset
  • hg help revert

See how deeply technical Git’s explanations are? Notice the simplicity and clarity of Mercurial’s help pages? This may reflect the C origins of Git and Python origins of Mercurial…

Supporting Tools

Developers love Git and GitHub. That’s an important point: how many Git fanatics would love it if we took away GitHub and Meld? How many git users primarily live on the command line?

Our developers largely code on Windows in IDEs — the DVCS supporting tools need to play nice on Windows and be easy to use.

TortoiseHg vs TortoiseGit was an easy one: TortoiseHg is great, TortoiseGit is nasty. (Try them, you’ll see.)

Eclipse IDE integration for Mercurial via MercurialEclipse HGE was another easy win over EGit — the EGit impl as of mid 2011 is a gimpy thing compared to its HGE counterpart. You’ll end up on the command line for git more often than not. To be fair, JetBrains IntelliJ IDEA’s Git integration is fantastic — but we mostly use Eclipse.

The dominant Windows Git tool, msysgit, is a horrendous mess compared to the Mercurial command line. msysgit is far nicer now than a few years ago but the old warts are still there: file path nonsense, sluggish prompts, the baggage of  et al. Mercurial’s command line integration is seamless on Windows using the official package or TortoiseHg.

We use Atlassian’s Fisheye, which works great with both Git and Mercurial. (Thanks guys!)

The Adoption

Our switch to Mercurial had a few bumps.

Good stuff:

Early adopters: One of our dev teams adopted Mercurial a month ahead of everyone else. This let us resolve many of the kinks early. You can promote from your Mercurial repo to an old Subversion repo (or most VCSs) without too much trouble — both Git and Mercurial have explicit integrations for that purpose. This lets you run both in parallel and gradually introduce DVCS. (In Google’s case, they’ve kept Perforce around as a central repo and let teams adopt Git as they wish.)

Training: We invested heavily in wiki pages, lunch and learns, training materials, Eclipse IDE upgrade bundled with HGE, and a few Mercurial champions to run around and answer questions. These greatly smoothed adoption.

Bad stuff:

Merge nightmares: We had a handful of developers who really struggled with merges. Branching in DVCS is a regular thing (even part of the daily workflow for the best of devs), and multiple heads are a way of life too. We should have held more workshops before the switch over, so people would become more familiar with merging. We did the workshops after the fact and this seemed to help — hands on is often better than lecture/reading.

Too many tool choices: We let people use TortoiseHg, command line, or HGE as they wished. We should have invested more training in HGE and recommended that as the primary tool, rather than let people wander about in tool-land. Let devs use what tools they want, but for those who don’t have time to learn them all, provide a preferred path!

Champions are busy people: We had too few experts able to answer Mercurial questions. When they were busy, some developers got stuck mid merge. We should have trained up more experts beforehand.

The Result: Success!

We now have our dev teams happily humming along on their own branches, merging code in shared projects, and we’ve parallelized our development to a degree we’ve never seen before. We cut our continuous integration build build time by half due to faster clones and no need for build tagging.

Additionally, our best developers are doing cool things:

  • Frequent, small commits. This one’s huge — it changes the way you think about code progress.
  • Exploratory branching.
  • Finding bugs using hg bisect.
  • Undoing mistakes with hg rollback, backout, and strip.
  • Switching between branches with ease.
  • Simultaneously using multiple workspaces on different branches.
  • Awesome code reviews using Atlassian’s Crucible.

hg commit -m “Thanks for reading!” && hg push


Leave a Reply

Your email address will not be published.