technology

Using Mercurial as ad-hoc local version control

Let’s assume you’re working at a company using Perforce or Subversion as
source control, and you’re tasked to fix a bug on the main branch of
development. You’d prefer not to commit anything into the repository that
breaks, lest the build master (who may be yourself) get on your case and
you’re additionally tasked to buy donuts for the group.

If the bug/change you’re trying to make is anything beyond the most trivial
task, it would be great to have your sources under version control so you have
the freedom to try things and backtrack—you know, one of the basic ideas
behind version control. So, now you’re stuck. There’s too much overhead to
create a whole new branch just for this one fix. Do you resort to renaming
files and folders and moving back and forth on your editor’s undo buffer?
C’mon now, behave.

When the tools aren’t working for you, find a new tool! Enter
Mercurial. I won’t get into the
interminable debate between Mercurial and Git and other
DVCS’s. Suffice it to say that they are all the NBT, and distributed VCS are a
superset of centralized ones. I’ve chosen Mercurial for pragmatic reasons: 1)
works well on Windows and 2) is implemented primarily in
Python.

The basic idea is, you can use Mercurial on top of your current, centralized
version control system. This way, you get all of your local sources under
version control independent of what the rest of your company uses. It’s a
simple idea, but it frees you from worrying about how to manage changes you’re
making in your local area. Another situation I frequently find this useful in
is when I’m writing a one-off script that I’m not sure if I want to commit to
the repository. But, the script is complex enough that I’ll need to iterate a
few times. Wouldn’t it be great to have it under version control? Here’s how:

Install Mercurial

I’m on Windows, so I just go for the Windows binary
package
where Python and everything is all
wrapped up for you. You can also install it with cygwin, if that’s your bag.
Make sure C:\Mercurial (or wherever you installed it) is in your path.

Now, you’re good to go. The executable name is “hg” (get it?) and if you type
that without any arguments at command prompt, you will see a list of basic
commands. All the concepts of version control that you’re familiar with are
all there. Let’s walk through an example of putting your sources under version
control and making some changes.

Create a new repository

The first thing you’ll do is create a new repository from your current
sources. Let’s say you’re working on on a project in C:\projects\GoogleKiller.
Navigate to that directory, and type:

> hg init

That command should return silently. It generated a .hg folder in that
directory where the metadata is stored. You’ve just created a repository. You
can now do:

> hg status
? GoogleKiller.py
? GoogleKillerTests.py
? README.TXT

This tells you that mercurial sees three files, but none of them are tracked.
To start tracking them, simply:

> hg add
adding GoogleKiller.py
adding GoogleKillerTests.py
adding README.TXT

Without specifying any files to “hg add”, you’ve added all the files in the
directory. Now, the last step to getting these sources in the repository is:

hg commit -m "Initial checkin!"

The -m argument is the log message for the checkin. You can track the history
of commits with the log command:

> hg log
changeset:   0:8c047c4da9a4
tag:         tip
user:        bentsai@example.com
date:        Fri May 30 17:32:17 2008 -0400
summary:     Initial checkin!

Now you’re ready to roll with local version control:)

Start coding

The commandline help for mercurial is pretty good. The basic commands you’ll
care about are:

  • hg status (to see what files have been modified)
  • hg diff (which prints out a unified diff of what’s changed)
  • hg revert (for backing out of changes)
    To get more details on these commands, just type “hg help “. There
    are other tweaks you can make to the usage (the [documentation](http://hgbook
    .red-bean.com/hgbook.html) is good), but that’s the general idea. Now you’re
    free to get on with coding!

The process for getting up and running is pretty low on friction, which is why
I like it. This doesn’t even begin to touch the real boon of DVCS’s—actually
collaborating with others. But this technique takes advantage of Mercurial’s
speed, easy-of-use, and unobtrusiveness for a rapid solution to a fairly
common problem.

Update (June 1, 2008): I should note that using Mercurial for version control isn’t limited to code. Any situation you’re keen on rolling back changes, this could work. Before I found out about Mercurial, I thought about using Subversion for such a purpose. But the pain was setting up a server – with Mercurial, there is no centralized server to setup. The only thing Mercurial does is add an “.hg” folder in the root. Once you have it installed on your computer, you’ve got localized Time Machine-like powers at your fingertips.

Update (June 2, 2008): Here’s someone who’s using Mercurial specifically with Perforce and described his workflow more extensively than I have.

Advertisements
Standard

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s