Wednesday, May 17, 2006

The missing Mercurial manual

I think I've found my ideal solution for version control. I used bzr for a few weeks, and appreciated its distributed nature - no single repository has to be the ultimate authority, so it works well for machines that can't all be connected to the same network. I use a travelling USB drive to sync my machines, so it was perfect... except that bzr can take several minutes for just a few merges. It got annoying when the merge was keeping me from leaving work.

Mercurial is also distributed, but it's very, very fast. It's even (gasp) well-documented! There are, however, a few things I think a newbie should know up-front.
  • The tutorial assumes you'll start by copying an existing mercurial repository. I wanted my own, though, and it took me several tries to figure out that I needed to do this:
    ~/existing$ hg init
    ~/existing$ hg add
    ~/existing$ hg commit
    ~/existing$ cd ..
    ~$ hg clone existing newdir

    Later on, if I make new files in existing, they won't get to newdir until I
    ~/existing$ hg add
    ~/existing$ hg commit
    ~/existing$ cd ../newdir
    ~/newdir$ hg pull
    ~/newdir$ hg update

    pull brings fresh metadata in from the other repository, storing it in .hg, but doesn't actually go on to update the files themselves. That's what update does. It took a while to get it, but now that I do, it seems intuitive and helps me feel in control.
  • Your EDITOR or HGEDITOR environment variable must be set, or else hg commit will hurl you pitilessly into vi (*nix) or throw up its hands and scoff at you (Windows).
  • But, if you use gedit and already have another file open in it, you get
    ~/existing$ hg commit
    transaction abort!
    rollback completed

    I suspect that may happen with other multi-file editors, too. I'll use EXPORT HGEDITOR=pico.


Anonymous said...

Just curious if you’ve tried moving a repository. I’m using version 0.9.3+20061222 on a “Billy Box” and have had no luck. I agree that the docs are great, but they’re a tease right now, in a sadistic kind of way, when it comes to “rename”.

Anonymous said...

The repository lives in the .hg subdirectory of the current working directory.

I just found out that when you have named branches, hg clone will create a new working directory on the "default" branch, and not the tip.

The "Update" command is quite unlike the Update in svn. It is used as a "GOTO" revision number. If you

hg update -C -r 5

and you commit some changes, you've created a branch of your repository back at that point in time.