Note: There is also a version of this page on the class wiki, where you can edit it for yourself. Please feel free to contribute.
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 figure 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.
The labs in this class don't allow you to take full advantage of Mercurial's capabilities, because they are usually in a single source file, which makes it hard for you to go genuinely independent work. But it will still be helpful to have a shared log of changes.
If you decide that you want (or need) to learn 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. Whenever you run hg, it will
look for a file named .hgrc in your home directory for
some settings and options. We suggest that you put the following in
that file:
[ui] username = msnerd <Mortimer.Snerd@my.wheaton.edu> merge = meldThe second line sets the identity that will be recorded when your actions are logged; substitute your username and email address, of course. The last line selects the program
meld to be
used when you have to merge changes (more on that below).
You can edit your .hgrc file later on if you want to set
some more options.
push or pull changes between them.
So someone has to do the initial creation of the repository,
and then put it where the other(s) can access it. There are several
ways that you might get there.
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).
If you start this way, you'd share your repository by making it
available for your partner to clone. The easiest way to do that is to
use a shared server; we provide the host cshg for that
purpose. If you're all set up with cshg and you're in
the top directory of your local repository, you can clone it with
$ hg clone . ssh://hg@cshg/pathname-for-repositoryThe
pathname-for-repository is going to be something like
351-12/groupname/labname.
$ hg clone /path/to/provided/repo ssh://hg@cshg/pathname-for-repositoryand then
$ hg clone ssh://hg@cshg/pathname-for-repository .to create a (private) working copy under the current directory.
.hg/hgrc, which looks something like
this:
[paths] default = /path/from/which/this/was/clonedYou can edit that file (use your favorite text editor) to set the default to the location (such as the ssh URI above) for pushing and pulling.
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/csci351/dot.hgignoreThat file ignores
.o 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 more complicated.
When you've committed a group of changes that you want to share
with your partner(s), you push those changes to the shared
repository. But it is a good idea to first pull any changes
that others have made. If your .hg/hgrc is properly set
up, you can do
$ hg pull $ hg updateThe first command gets the changes into your (local) repository, the second makes those changes in your working copy. If you and your partner have only worked on different files, you'd be ready now to commit (adding his/her changes to yours), and then
$ hg pushIf you've modified any of the same files, you are now going to have to merge the changes.
The process of reconciling independent changes to the files in the repository is known as merging. It is nicest if you don't have to do that. But sometimes it is unavoidable.
Instructions for merging will be added. Feel free to contribute on the wiki version of this page.
Last modified: Wed Nov 7 15:28:47 CST 2012