Here is a short tutorial on getting going. For more info, the web site is http://www.selenic.com/mercurial/wiki/index.cgi
First, why bother?
Mercurial seems to give a source-control model much more like Teamware, in the sense that there is no single repository. Instead, you work against a local repository (committing changes, browsing history, and possible cloning the repository for experiments as you go), and periodically communicate your changes between repositories ("push", "pull").
The "killer feature" that got me started with Mercurial is that it is relatively easy (as in, it worked the first time I tried it) to overlay a subversion workspace on top of a Mercurial repository, and because Mercurial has no special rootedness, we could use mercurial to communicate between a pair of rooted subversion repositories.
In addition, Mercurial lets you have all the benefits of a version control system, locally, without the full overhead of testing and coordinating before commit. This is similar to working with Teamware, but without the requirement that you stay connected.
It is dead easy to start up web access to a repository. Typing hg serve at the root of the repository gets you web service good for both browsing, and obtaining your own clone of the repository. (It seems to be stuck at a particular point in time; this may be fixed in the latest release).
Try http://selenic.com/repo/hg for a sample.
To make your own copy of that repository, all you need to type is
hg clone http://selenic.com/repo/hg MyRepositoryName
Since you can run a server with one command, almost anyone can run a server.
This is the list of simple commands:
add add the specified files on the next commit annotate show changeset information per file line clone make a copy of an existing repository commit commit the specified files or all outstanding changes diff diff repository (or selected files) export dump the header and diffs for one or more changesets init create a new repository in the given directory log show revision history of entire repository or files parents show the parents of the working dir or revision pull pull changes from the specified source push push changes to the specified destination remove remove the specified files on the next commit revert revert files or dirs to their states as of some revision serve export the repository via HTTP status show changed files in the working directory update update or merge working directory
There's a start at a Mercurial GUI (hgk, see below) but I have not been able to make it work on Solaris, nor have I been able to successfully clone on Solaris through a firewall (this all just worked on the Mac, which is why I like my Mac).
Install instructions
- On Solaris boxes, it is at least available from Blastwave. On a Mac, you can either use !MacPorts sudo port install hg or download it from http://mercurial.berkwood.com/ . On Windows, you can download it from http://mercurial.berkwood.com/ .
- Unless you like "vim", be sure to set the following environment variable:
HGEDITOR=/Users/chase/bin/runemacs
On a Mac, runemacs is this script:#!/bin/bash ec=/Applications/Aquamacs\ Emacs.app/Contents/MacOS/bin/emacsclient open -a "/Applications/Aquamacs Emacs.app" "$ec" $* || ( sleep 10; "$ec" $*)
- You may want to use the "UI". To do that, you need a copy of hgk, which is a giant script. If you use MacPorts it comes with the Mercurial port, and it may be part of Mercurial 1.0.
You need to create $HOME/.hgrc if you don't have one already
[extensions] hgk= [ui] username = David Chase <dr2chase@sun.com> [hgk] path=/opt/local/share/mercurial/contrib/hgk
Project Fortress instructions
This repository already contains .hgignore, and two scripts (in bin) that assist in keeping Mercurial and Subversion in sync with each other.
To create the initial subversion-mercurial link at the top level (best place, I think):
hg init bin/adds hg > hgadds.txt # review hgadds.txt to remove any spurious files, like, say, hgadds.txt sh < hgadds.txt # this will take a few minutes
As long as the information is flowing from subversion to mercurial, a subversion update will include the following additional steps:
svn up bin/adds hg > hgadds.txt bin/rems hg > hgrems.txt # review hgadds.txt and hgrems.txt for additions and deletions sh < hgadds.txt sh < hgrems.txt hg commit -m "Latest update from svn `svnversion`"
Once the first repository is created, you can use it to manage local changes with periodic commits to it, even if disconnected from the network. You can also clone it into a second repository, if you wish to try more extensive experiments outside the view/interference of subversion:
hg clone location-of-original location-of-new
To move changes from Mercurial to Subversion (perhaps you added files in a second Mercurial repository, pushed them back to the parent, and now wish to commit to subversion, you would say (in the subversion repository):
hg up bin/adds svn > svnadds.txt bin/rems svn > svnrems.txt # review svnadds.txt and svnrems.txt for additions and deletions sh < svnadds.txt sh < svnrems.txt svn commit -m "Collected changes from my mercurial sandbox; other useful remarks..."
Notice that the options for hg and svn are relatively symmetric, to the point that the adds and rems scripts work for either application.
