Given the increasing popularity of the Mercurial version control system (and the fact that I'm using it more and more these days), here's a quick tutorial for people who simply want to check out and work with a Mercurial repository; it won't cover creating your own repo or committing changes, just working with someone else's repository.
It's your responsibility to install Mercurial on your (Linux?) system -- on Ubuntu, that would involve running:
$ sudo apt-get install mercurial
On other Linux distros, it's your job to figure out which package to install but it's a good bet it's just "mercurial," at which point you'll use the
hg commmand from then on.
Unsurprisingly, you want to check out someone's Mercurial repo if you want to keep up with their latest development commits and track their most recent work. If you don't want to do that, then there's probably little value in following their repository.
I'm currently working with three Mercurial checkouts, so I'm just going to pick the smallest as a working example to demonstrate simple Mercurial usage. Here's how to check out the repository corresponding to Nuxeo's Digital Asset Management (DAM) software (my other two checkouts are significantly larger so I'm ignoring them):
$ hg clone http://hg.nuxeo.org/nuxeo-dam
After a minute or two of downloading, this will give you a directory named
nuxeo-dam in your current directory, at which point you can
cd into that directory and we can get started.
Your Mercurial checkout might consist of a number of branches, as well as a number of tags. First, you can examine your current branch and the set of all branches with:
$ hg branch develop <--- current development branch $ hg branches develop 671:9c52da2250ff 1.0-beta 431:b795ce621653 DAM-181 239:366875669cef DAM-213 205:21c67297f7f7 minimal-project 7:526c1a840e79 NXP-4792-DAM-467-video-refactoring 615:679081992b79 (inactive) DAM-357 598:9e637c5186d1 (inactive) 1.0 572:0afefc3970dc (inactive) DAM-449 566:d27e91c25145 (inactive) ... snip ... $
It might be that you want to be working with a specific branch but, unless you have a reason for that, you probably want to stick with whatever branch has a name like "develop" or "development" or "master" or something similar, so that you're staying on top of the absolutely latest commits.
In addition, at times, you might want to view your checkout as it was tagged at some point in the past. You can view the tags with:
$ hg tags tip 671:9c52da2250ff release-1.0 568:2f07379e3737 release-1.0-beta 430:7a000fb522dc $
but, again, unless you have a good reason to be working with an older version of the repository, you probably just want to stick with the tag labelled "tip," which represents the latest version of the current branch.
In other words, if you simply check out someone's Mercurial repository and
cd into it, you're probably right where you want to be.
To stay on top of the latest commits to the repository, you can just:
$ hg pull -u
In addition, before you pull, you can check if there are any outstanding commits you'd be receiving with:
$ hg incoming
There are a number of commands you can use to examine the progression of work in the Mercurial repository.
$ hg tip changeset: 671:9c52da2250ff branch: develop tag: tip user: Thomas Roger date: Mon Jun 28 00:15:42 2010 +0200 summary: DAM-499: add importer dependencies to distributions. \ New profile to include JAX-RS importer modules $
The above shows you that the latest commit that you've pulled down is change 671, who committed it, when it was committed and a short summary.
In addition, you can ask for the actual "diff" output of that commit by adding the
-p option which (for quite a number of Mercurial commands) specifies to show the "patch" information corresponding to that commit:
hg tip -p changeset: 671:9c52da2250ff branch: develop tag: tip user: Thomas Roger date: Mon Jun 28 00:15:42 2010 +0200 summary: DAM-499: add importer dependencies to distributions. \ New profile to include JAX-RS importer modules diff -r 6b483e7f2fd6 -r 9c52da2250ff nuxeo-dam-distribution/pom.xml --- a/nuxeo-dam-distribution/pom.xml Sat Jun 26 16:14:42 2010 +0200 +++ b/nuxeo-dam-distribution/pom.xml Mon Jun 28 00:15:42 2010 +0200 @@ -35,6 +35,9 @@ all-distributions + + http-importer + ... and so on ...
As an aside, for any Mercurial command, you can get help with:
$ hg help [command]
If you want to see the repository history, just use one of:
$ hg log $ hg log -p [add patch info as well]
You can also check the log and contents of any other revision if you have the revision number:
$ hg log -r667 -p ... log entry and diff printed here ... $
If you want to see what else this command can do, there's always:
$ hg help log
If you're following someone's development branch because you want to test the absolutely latest (pre-release) version of the software, it's entirely possible that you might want to make some temporary changes to your local working copy to see how that would affect the software. For example, in this current Nuxeo DAM checkout, let's say you made some innocuous changes to the
README.txt file. You could examine your local diffs (throughout the entire source tree) with:
$ hg diff diff -r 9c52da2250ff README.txt --- a/README.txt Mon Jun 28 00:15:42 2010 +0200 +++ b/README.txt Fri Jul 02 07:20:39 2010 -0400 @@ -1,3 +1,6 @@ +This line added by rday. +This one, too. + Nuxeo Digital Asset Management application ========================================== $
At this point, perhaps you'd rebuild the software (locally, of course) and test the effect of your change (assuming you made a more meaningful change than the one above).
Once you're done testing your local changes, you can discard those changes throughout your working copy with:
$ hg revert -a
$ hg help revert
One final point is worth covering. If you're using your checkout to build and test someone's else code base, chances are that you'll be generating temporary files inside your local working copy and, after testing, you might want to delete those temp files -- that is, delete any content within your working copy that doesn't represent an official entry in the repository.
You can easily generate the list of untagged files with:
$ hg status -nu
and use whatever incantation you want to drive that list of files into a Linux command that removes them all, such as
$ hg status -nu | xargs rm -f
or something similar.
At this point, that should be enough to get you going as a simple Mercurial user. For more tutorial, I suggest starting here and following links.
We're aware of the time and budget pressures at most companies, normally accompanied by the plaintive cry from management of, "Yes, I know we need training on that topic, but I just can't afford to send my entire team away for three (or four or five) days to get it!" And that's where we come in.
The main focus at Crashcourse is to offer a choice of intense, 1-day, hands-on courses on specific topics in Linux and open source. And given that we already have the laptops for the delivery of that training, the idea is to show up early, set up a classroom, then spend the day teaching exactly the topic you're interested in. No travel time, and no wasted classroom time.
If we don't already have a course that addresses the topic you're interested in, drop us a note and we'll see what we can do -- our content providers can almost certainly put together a course that's precisely what you're after.
While there are a variety of sources for Linux and open source training, we at Crashcourse are taking a slightly different approach. Our philosophy is simple: exactly the training you want, and no wasted time or travel to get it.