What is Mercurial?

Mercurial is a Version Control System that stores all the versions locally while many VCSs rely on the internet to store older versions of the files. It allows users to rever to previous versions of files if necessary as well as collaborate asynchronously on projects and merge their results.

Installing Mercurial on Mac OS X

Check if you have Mercurial

Open a terminal window (/Applications/Utilities/Terminal) and type:

If it returns something similar to:

Mercurial Distributed SCM
basic commands:

It means you have Mercurial already installed. If not, follow the instructions below to install Mercurial:

Getting the right version for your OS and Python interpreter

First, check which operating system version you are using by navigating to the top left corner of your screen and click on:

Now, get the version of python that you're using by typing the following in a terminal window:

With this information, go to http://mercurial.selenic.com/downloads/ and select a version that matches both your Mac OS and Python versions. Pay particular attention to the filename linked to by the different download links as they contain the python version in them but are not otherwise written explicitly on the website. An example of a filename is:

Indicating that this installation package of Mercurial is expecting python 2.7 and OS X 10.8

Setting computer up to use the archive

Configurating SSH

The first thing we need to do is to obtain the keys for the archive you want to use, which in this case are distributed by Neil via email to the accepted students. This will contain two files: classes and classes.pub. The former being the private key and the latter being the public one. We now need to place them in a logical directory located in ~/.ssh/keys. Let's first check that the directory exists:

If the directory doesn't exist, you can create it by using the following command:

Now that we have the folder created, copy the archive keys you're going to use into the folder. You can do this in many different ways. The simplest is probably to open a finder window and drag and drop the key files into the folder. Because folders that start with a . are hidden folders on UNIX operating systems, you can use the command line to open the finder to the correct location:

Alternatively, you can use the copy command to copy the correct files. Remember you can use wildcards like * to copy multiple files at once

Key file permissions

As discussed in the SSH overview above, we need to make sure the keys have the correct permissions set, otherwise it represents a risk and SSH won't let you connect to the archive. Let's check the permissions of the files in the Keys folder:

Permissions for the .pub key(s) should be:

and permissions for the private key file(s) should be:

This is unlikely to be the case right out of the box. So type the following commands to respectively change the public files in the folder:

and the private file of interest, in this case classes:

Cloning the archive

Now that we have the SSH keys configured correctly, we need to clone the archive to our local computer. Because the command is a little long, some people prefer to automate the process by creating a custom script. Please see that section if you want to go that route. Otherwise, use the command below and replace with your relevant settings.

An example of this command being used to clone the How to Make (Almost) Anything Class archive for 2013 (xxx.13):

Now that we've cloned the archive, we need to configure the archive's specific settings

Configuring the archive settings

The archive settings are store in a hidden directory (starts with a .) within the repository

Using your favorite editor, edit (you may need to create it if it doesn't exist) the following file within your repository:

and make sure the content is:

[paths]
default = ssh://hg@fab.cba.mit.edu/863.13

[ui]
ssh = ssh -p 846 -i ~/.ssh/keys/classes
username = Firstname Lastname < email@domain.edu>
editor = mate

[extensions]
convert =
fetch =

[hooks]
changegroup = hg update >&2
              

Make sure on the SSH line, you have the correct path to the private key that was distributed by email.

Creating custom scripts Optional

In order to create a script that will automate the process outlined above, we will need to create a program in the correct folder. In this example, I will use the /usr/bin folder to store our script. Please read the note about this folder on the side if you want to use a less essential folder. Because of the folder's importance for the system, we need to use super-user privileges to be able to write our script to the folder:

An interface appears in your terminal. Copy and Paste the following script:

#!/bin/bash
#
if [ $# -ne 4 ]; then
   echo "Incorrect use of hgclone. Please run command thusly:"
   echo "hgclone archive_name archive_key archive_server server_port"
else
   cmd="hg clone -v -e 'ssh -p $4 -i ~/.ssh/keys/$2' ssh://hg@$3/$1 $1"
   eval $cmd
   cmd="echo -e '\n[ui]\nssh = ssh -p $4 -i ~/.ssh/keys/$2' >> $1/.hg/hgrc"
   eval $cmd
   fi
                

To save the script and exit the nano text editor, press Ctrl-X, confirm (using the Y key and Enter). You should now be back to the terminal. Try executing the script you just saved by doing:

It should complain that you didn't run the script with the correct arguments. Now, all that should be left for us to do is run the script. If you have other issues running the script, check that you have execute (u+x) permissions on the hgclone file (/usr/bin/hgclone).

An example of the hgclone command would be:

Pulling from the archive

This one is easy. The command is below.

Don't forget to incorporate the pulled changes into your local directory:

Occasionally when your version clashes with the one you are trying to update, you might get an error telling you there are outstanding changes or that you need to merge. See the merging section below on how to do that.

Adding and committing changes

Show the current status of your local archive

The first thing you need to do when adding changes to the archive is to check the status of the archive using the following command:

This should return a list of the files like the one below:

M people/charles.fracchia/vcs.html
? people/charles.fracchia/about.html

The M flag represents a file that is tracked by mercurial but has been modified since the last commit. The ? flag means that the file is not being tracked by the version control system.

Adding and forgetting files

In this case, I recently created this about.html page, and want to include it in the next commit. To do that, I use the command below:

Re-running the status command should now show that the file will be added to the next commit:

M people/charles.fracchia/vcs.html
A people/charles.fracchia/about.html

If afterall you change your mind and don't want to include the file to the next commit use the forget command:

Committing

Committing in mercurial is akin to creating a snapshot in time of your archive. You could refer to this as a version of your archive. Once you have selected the files that should go into your commit (see Adding and Forgetting section), you can commit your version by using the following command:

Try to be descriptive in your commit message, it will be extremely helpful when you have to look back and understand what was done.

Merging

Merging occurs when you have two parrallel branches of development that need to be unified. This often happens when you have been offline (aka haven't pulled and updated your archive) in a while and changes have been made in parallel. Sometimes, these changes will conflict with eachother and you will need to actively choose which changes to keep and which you throw. I will not be explaining how to do this, there is a good guid on this here.

In order to merge your changes into the current head commit type:

As mercurial suggests after the merge command, don't forget to commit that merge into a version. I often use an explicit comment to show this specific merge:

Pushing

Pushing to the archive uploads your commit history to the server. This means that you can make intermediary versions (and encouraged) as you go along, even if you can't reach the server. Once you restore your ability to connect to the mercurial repository server, you can upload your changes using:

Terminal commands