Mercurial (hg)¶

See Version Control Software and the links there for a more general discussion of the concepts.

Instructions for cloning the class repository¶

All of the materials for this class, including slides, sample programs, and the webpages you are now reading (or at least the .rst files used to create them, see Sphinx documentation), are in a Mercurial repository hosted at Bitbucket, located at http://bitbucket.org/rjleveque/uwamath583s11/. In addition to viewing the files via the link above, you can also view changesets, issues, etc. (see Bitbucket repositories: viewing changesets, issue tracking).

To obtain a copy, simply move to the directory where you want your copy to reside (assumed to be your home directory below) and then clone the repository:

$ cd
$ hg clone http://bitbucket.org/rjleveque/uwamath583s11/

Note the following:

It is assumed you have Mercurial (hg) installed, see Downloading and installing software for this class.

The clone statement will download the entire repository as a new subdirectory called uwamath583s11, residing in your home directory. If you want uwamath583s11 to reside elsewhere, you should first cd to that directory.

It will be useful to set a Unix environment variable (see Environment variables) called CLASSHG to refer to the directory you have just created. Assuming you are using the bash shell (see The bash shell), and that you cloned uwamath583s11 into your home directory, you can do this via:

$ export CLASSHG=$HOME/uwamath583s11

This uses the standard environment variable HOME, which is the full path to your home directory.

If you put it somewhere else, you can instead do:

$ cd uwamath583s11
$ export CLASSHG=`pwd`

The syntax `pwd` means to run the pwd command (print working directory) and insert the output of this command into the export command.

Type:

$ printenv CLASSHG

to make sure CLASSHG is set properly. This should print the full path to the new directory.

If you log out and log in again later, you will find that this environment variable is no longer set. Or if you set it in one terminal window, it will not be set in others. To have it set automatically every time a new bash shell is created (e.g. whenever a new terminal window is opened), add a line of the form:

export CLASSHG=$HOME/uwamath583s11

to your .bashrc file. (See .bashrc file). This assumes it is in your home directory. If not, you will have to add a line of the form:

export CLASSHG=full-path-to-uwamath583s11

where the full path is what was returned by the printenv statement above.

Updating your clone¶

The files in the class repository will change as the quarter progresses — new notes, slides, sample programs, and homeworks will be added. In order to bring these changes over to your cloned copy, all you need to do is:

$ cd $CLASSHG
$ hg pull
$ hg update

Of course this assumes that CLASSHG has been properly set, see above.

The last two command can be combined as:

$ hg pull -u

Creating your own Bitbucket repository¶

In addition to using the class repository, students in AMath 483/583 are also required to create their own repository on Bitbucket. It is possible to use Mercurial for your own work without creating a repository on a hosted site such as Bitbucket (see newhg below), but there are several reasons for this requirement:

You should learn how to use Bitbucket for more than just pulling changes.

You will use this repository to “submit” your solutions to homeworks. You will give the instructor and TA permission to clone your repository so that we can grade the homework (others will not be able to clone or view it unless you also give them permission).

It is recommended that after the class ends you continue to use your repository as a way to back up your important work on another computer (with all the benefits of version control too!). At that point, of course, you can change the permissions so the instructor and TA no longer have access.

Below are the instructions for creating your own repository. Note that this should be a private repository so nobody can view or clone it unless you grant permission.

Anyone can create one free private repository on Bitbucket. More than one costs money. If you already have a private repository that you don’t want to give us access to, contact us and we can arrange something else. (Note that you can also create an unlimited number of public repositories free at Bitbucket, which you might want to do for open source software projects, or for classes like this one.)

Follow these directions exactly. Doing so is part of Homework 1. We will clone your repository and check that testfile.txt has been created and modified as directed below.

On the machine you’re working on, go to your home directory (“cd $HOME” on Unix) and create a file named .hgrc (with a dot at the front) containing:
```
[ui]
username = Your Name <yournetid@uw.edu>
verbose = True
```
This will be used when you commit changes. This is a configuration file used by hg, similar to the .bashrc file used by bash. If you don’t do this, you might get a message like:
```
abort: no username supplied (see "hg help config")
```
the first time you try to commit.
Go to http://bitbucket.org/ and click on “Sign up now”
Fill in the form, make sure you remember your username and password.
You should then be taken to your account. Click on “+ Create new” next to “Your repositories”.
You should now see a form where you can specify the name of a repository and a description. The repository name need not be the same as your user name (a single user might have several repositories). For example, the class repository is named uwamath583s11, owned by user rjleveque. To avoid confusion, you should probably not name your repository uwamath583s11.
Make sure you click on “Private” at the bottom. Also keep “Issue tracking” and “Wiki” clicked on.
Click on “Create repository”.
You should now see a page with instructions on how to clone your (currently empty) repository. In a Unix window, cd to the directory where you want your cloned copy to reside, and perform the clone by typing in the clone command shown. This will create a new directory with the same name as the repository.
You should now be able to cd into the directory this created.
To keep track of where this directory is and get to it easily in the future, create an environment variable MYHG from inside this directory by:
```
$ export MYHG=`pwd`
```
See the discussion above in section Instructions for cloning the class repository for what this does. You will also probably want to add a line to your .bashrc file to define MYHG similar to the line added for CLASSHG.
The directory you are now in will appear empty if you simply do:
```
$ ls
```
But try:
```
$ ls -a
./  ../  .hg/
```
the -a option causes ls to list files starting with a dot, which are normally suppressed. See ls for a discussion of ./ and ../. The directory .hg is the directory that stores all the information about the contents of this directory and a complete history of every file and every change ever committed. You shouldn’t touch or modify the files in this directory, they are used by Mercurial.
Add a new file to your directory:
```
$ cat > testfile.txt
This is a new file
with only two lines so far.
^D
```
The Unix cat command simply redirects everything you type on the following lines into a file called testfile.txt. This goes on until you type a <ctrl>-d (the 4th line in the example above). After typing <ctrl>-d you should get the Unix prompt back. Alternatively, you could create the file testfile.txt using your favorite text editor (see Text editors).
Type:
```
$ hg status
```
The response should be:
```
? testfile.txt
```
The ? means that this file is not under revision control. To put it under revision control, type:
```
$ hg add testfile.txt
$ hg status
A testfile.txt
```
The A means it has been added. However, at this point Mercurial is not yet keeping track of this version or any changes to this file. We can tell Mercurial to track this version by:
```
$ hg commit testfile.txt -m "My first commit of a test file."
```
The string following the -m is a comment about this commit that may help you in general remember why you committed new or changed files.

If you left off the file name testfile.txt then be default hg will commit all changes made in this directory since the last commit. In the current example there is only one change, the addition of this file, so it would have the same behavior either way.

We can now see the status of our directory via:
```
$ hg status --all
C testfile.txt
```
Now the C means this file is clean (agrees with the version being tracked). If you leave off the –all flag, by default hg status does not list the clean files and only shows files that differ from the lastest version being tracked. This is generally what you want if you have thousands of files in your repository and only a few have been changed.

Alternatively, you can check the status of a single file with:
```
$ hg status testfile.txt
```
Now let’s modify this file:
```
$ cat >> testfile.txt
Adding a third line
^D
```
Here the >> tells cat that we want to add on to the end of an existing file rather than creating a new one. (Or you can edit the file with your favorite editor and add this third line.)

Now try the following:
```
$ hg status
M testfile.txt
```
The M indicates this file has been modified relative to the most recent version that was committed.

To see what changes have been made, try:
```
$ hg diff testfile.txt
```
This will produce something like:
```
diff -r 6e3383561936 testfile.txt
--- a/testfile.txt      Tue Mar 02 23:15:38 2010 -0800
+++ b/testfile.txt      Tue Mar 02 23:23:57 2010 -0800
@@ -1,2 +1,3 @@ This is a new file
 This is a new file
 with only two lines so far
+Adding a third line
```
The + in front of the last line shows that it was added. The two lines before it are printed to show the context. If the file were longer, hg diff would only print a few lines around any change to indicate the context.

The first line printed out above shows the diff command that’s actually being executed: it is doing a diff between this file and the one stored in the revision that Mercurial has given the name 6e3383561936. Internally it creates long hexidecimal names like this (see Hexidecimal numbers) in order to keep things straight if changes made by several different people are merged. There’s a simpler revision number you can discover by typing:
```
$ hg tip
changeset:   0:6e3383561936
tag:         tip
user:        rjl@spinach
date:        Tue Mar 02 23:15:38 2010 -0800
summary:     My first commit of a test file.
```
This shows that the tip (the most recent version of all files being tracked) is changeset 0.

Now let’s commit this changed file:
```
$ hg commit -m "added a third line to the test file"
```
After this, “hg tip” should indicate the changeset of the tip is 1 (along with a long hex string).
So far you have been using Mercurial to keep track of changes in your own directory, on your computer. None of these changes have been seen by Bitbucket, so if someone else cloned your repository from there, they would not see testfile.txt.

Now let’s push these changes back to the Bitbucket repository:

First do:
```
$ hg status
```
to make sure there are no changes that have not been committed. This should print nothing.

Now do:
```
$ hg push
```
This will prompt for your Bitbucket password and should then print something like:
```
searching for changes
adding changesets
adding manifests
adding file changes
added 2 changesets with 2 changes to 1 files
```
Not only has it copied the 1 file over, it has added both changesets, so the entire history of your commits is now stored in the repository. If someone else clones the repository, they get the entire commit history and could revert to any previous version, for example (see Reverting to a previous version).
Check that the file is in your Bitbucket repository: Go back to that web page for your repository and click on the “Source” tab at the top. It should display the files in your repository and show testfile.txt.

Now click on the “Changesets” tab at the top. It should show that you made two commits and display the comments you added with the -m flag with each commit.

Look on the right side, where it says “commit 1: hex-string”. The hex-string is the internal identifier of this commit. If you click on the hex-string it will show the change set for this commit. What you should see is the file in its final state, with three lines. The third line should be highlighted in green, indicating that this line was added in this changeset. A line highlighted in red would indicate a line deleted in this changeset. (See also Bitbucket repositories: viewing changesets, issue tracking.)

This is enough for now!

Homework 1 instructs you to add some additional files to the Bitbucket repository.

Feel free to experiment further with your repository at this point. See More commands in hg for some more examples of how hg can be used.

Table Of Contents

Previous topic

Next topic

This Page

Mercurial (hg)¶

Instructions for cloning the class repository¶

Updating your clone¶

Creating your own Bitbucket repository¶

Further reading¶

Navigation

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Mercurial (hg)¶

Instructions for cloning the class repository¶

Updating your clone¶

Creating your own Bitbucket repository¶

Further reading¶

Navigation