Mercurial is a revision control system. That means it is designed to help track work on a collection of files, giving you the ability to identify and retrieve the revisions that existed at various points during the process. The huge motivation for revision control is when there are several people all working on the same program (or collection of programs), because then it is very helpful to be able to fugure out what was changed and by whom. But revision control is also helpful when you are working by yourself: if you manage to make a mess, you can back up to a coherent prior state.
Mercurial can do much more than we need in this class. If you get really interested, or you need something more, there is a very good online tutorial and reference, This page is limited to the features you are most likely to need in this class.
Mercurial manages a subtree of files: a directory and all of its
subdirectories. This matches the way we usually work on projects
(including labs): we make a new directory for each new project. When
we are working in a Mercurial-managed tree, we see the files there as
we would normally. But Mecurial also maintains, behind the scenes,
additional files that keep the history and other information; we call
that hidden collection the repository. (The repository is
actually hiding in a dirctory named .hg, taking advantage
of the fact that names beginning with dot are nor normally shown.) The visible
files we actually work with are called a working copy. We
manage the repository and its relationship with the working copy using
the hg commmand.
The main Mercurial command hg is always followed by
another command that tells Mercurial what to do. It is very helpful
to remember that one of those commands is help. So you
can always do
$ hg helpto get general help, or add a command, such as
update, to
the end of the help to get a reminder of what that command does and
what its arguments can be; for example,
$ hg help updateor even
$ hg help help
Before you can make very much use of Mercurial, you need to do a
tiny bit of setting up (which has already been done for the lab
accounts, and in rudimentary form for the accounts of students in this
class). Whenever you run hg, it will look for a file
named .hgrc in your home directory for some settings and
options. You can add to that later on if you want to set some more options.
In this class, you'll often start from a repository that already exists; you'll create your own working copy and repository by cloning the existing repository. When that repository is local, you can name it with its filename; so the command
$ hg clone /cslab/class/csci235/lab4 .will clone the repository under
/cslab/class/csci235/lab4
to the current working directory (that's the dot); it will make a new
directory named lab4 to hold the working copy and repository.
If you already have a directory for which you would like to start using Mercurial, you can create a repository by (1) making sure that you are in the top directory of the tree you want to manage and then (2) issuing the command
$ hg init
When you create a repository, you will need to remember to use the
hg add command to tell the repository what files it
should manage (see below).
Because there are usually files in the working copy that you don't
want in the repository (such as the compiled versions of the source
files), you can use a file .hgignore to tell Mercurial
the filenames it should ignore. That will be included when you clone
a repository, but you can edit it if you need to. That file has
patterns in it (a lesson in itself), but you can get a reasonable
starting file for this class by copying the file found at
/cslab/class/csci235/misc/dot.hgignoreThat file ignores
.class files, XEmacs backups, and
dot-files. You will want to remember to explicitly add the
.hgignore file, because it will otherwise be ignored.
hg status
Show the status of files in the working copy. The status letters you'll see most often are
? this file is not known to the repository (and not ignored)
M the working copy has been modified since the
last commit
A the file has been added to the repository, but
not yet committed
hg add filenames
Add the files to the set that are tracked by the repository.
hg forget filenames
No longer track these files.
hg log filenames
Show the history of commits to the named files.
hg update
Update the working copy to match the repository.
hg commit -m "message"
Commit the changes in the working copy to the repository. Replace message with a brief description of what has changed; this is the information that will be shown by the log command.
hg revert filenames
Restore the working copy of the named files to the latest version in the repository. This "undoes" uncommitted changes. (The command can also be used to get older revisions. More on that later.)
Things are pretty easy if you only revert uncommitted files (to their latest committed version) or if you revert the entire tree to a previously committed state. If you want to revert a file to an earlier committed state, you will have to do some merging, which is a subject for another day.
There are special ways to copy a directory with a Mercurial
repository. If user msnerd wants to copy from the lab
account to directory csci235/lab4 under his home
directory, the command would be
$ hg clone . ssh://msnerd@cslab25/csci235/lab4
You'll be prompted for your password.
When you have logged in to your account and change into your
csci235/lab4 directory, all that will be there is the
repository. To set up the working copy, you use
$ hg updatewhich makes the working copy match the last committed version from the repository.
Last modified: Tue Mar 1 07:48:26 CST 2011