Installing Mercurial on Unix (Mac/Linux/Cygwin)

NOTE: This is a fork of the tutorial with some URLs and ports replaced with those specific to the Amsterdam Fab Lab. We're running an on-line Mercurial server and some settings are different. The goal is to make things less confusing instead of more; hopefully this tutorial achieves the former.

ALSO NOTE: Once you've set up your keys and configured Mercurial, you can skip to step 6.

Mercurial is a free, distributed source control management tool. This tutorial covers how to install Mercurial on the Mac OS and clone the Fab Academy archive.

NOTE: after each line of code you type in - you need to hit the enter key.

Step 1: Install Mercurial

You need to download and install Mercurial (there is an installer for Mac): http://mercurial.selenic.com/

On windows you will need to install Cygwin instead, mercurial is a part of it but needs to be explicitly selected during installation, along with "openssh" and "nano".

Step 2: Key files

You need to put the two key files (mercurial and mercurial.pub) where Mercurial (SSH actually) can find them.

Download the keys that your instructor sent you in an email. They are named "mercurial" and "mercurial.pub". You will need to place them in the keys directory. To do this, save the key files to your desktop (for example) from the email.

Open terminal (On Mac OS: from the Finder menu > Go > Utilities > Terminal)

You will be in your home directory by default. Your prompt could look something like::

MyComputerName:~ MyHomeDirectoryName$ 

Where "MyComputerName" is the name of your hard disk and the "MyHomeDirectoryName is the username you created to login to Mac OS.

Let's start by creating the directory where the key files need to go.

Type the following text into the terminal after the prompt:

mkdir -pv ~/.ssh/keys

If you get a "permission denied" error, the directory might be owned by another user (such as the administrator account). Then type the following command before trying again:

sudo chown -Rv `whoami`: ~/.ssh

Your system may ask you for a password - type in the password you use as an adminstrator on your Mac (this is the same password you use to log into your computer).

Then you need to copy both of the keys from your where you saved them (like on the desktop) to the keys directory that you created earlier.

Type:

cp -v ~/Desktop/mercurial ~/Desktop/mercurial.pub ~/.ssh/keys/

Both keys are now located in the .ssh directory. You can check to see by typing: "ls -l ~/.ssh/keys" to list the contents of the directory. You should see that mercurial and mercurial.pub are listed.

Step 3: Permissions for the Private Key

You need to set permissions for your private key so that only you have read/write access to them.

Type:

chmod -v 600 ~/.ssh/keys/mercurial 
chmod -v 644 ~/.ssh/keys/mercurial.pub

Checking the file permissions, typing:

ls -l ~/.ssh/keys

should show you something very similar to:

total 5
-rw------- 1 username username 1675 Feb 24 21:37 mercurial
-rw-r--r-- 1 username username  392 Feb 24 21:37 mercurial.pub

The "-rw-------" part is important! If it looks different ssh will probably ask you for a password (which doesn't exist so good luck with that! ;))

Step 4: Configuring SSH

You will need to configure SSH. You can do this by creating and editing a config file within your .ssh directory.

Open the file with the nano text editor

Type:

nano ~/.ssh/config

The nano text editor will open in the terminal window.

Add the following text to the file:

Host mercurial
  HostName Penemue.zaerc.com
  User hg
  IdentityFile ~/.ssh/keys/mercurial

To save the file:
- press [control]+O to save the file (then the enter key)
- press [control]+X to exit the editor

Note: Do not add any extension to the file.

Step 5: Edit the Mercurial Configuration File

Now you need to edit your personal mercurial configuration file.

Type:

nano ~/.hgrc

A text editor will open inside of the terminal window.

Add the following text to the file: 
[ui]
username = First Last <[email protected]>

To save the file:
- press [control]+O to save the file (then the enter key)
- press [control]+X to exit the editor

Step 6 Clone the Archive

For convenience, we will clone it to the desktop. So we'll need to move there first (or anywhere else where you want your clone)

Type:

cd ~/Desktop

Now we're ready to obtain our very own clone of the archive, let's start with the tutorials archive

Type:

hg clone ssh://mercurial/academy.2015.tutorials

If you are cloning for the first time, you may be told that the "authenticity of the host cannot be established" and are given the option to type "yes" or "no".

The authenticity of host 'penemue.zaerc.com (82.94.213.60)' can't be established.
RSA key fingerprint is 2a:ca:4d:c5:81:95:e6:f7:9b:b8:af:2d:21:ba:55:b3.
Are you sure you want to continue connecting (yes/no)? yes
remote: Warning: Permanently added 'penemue.zaerc.com,82.94.213.60' (RSA) to the
list of known hosts.
  

Type "yes"

You should see the following (at least similar) response in the terminal as the archive is cloned.

destination directory: academy.2015.tutorials
requesting all changes
adding changesets
adding manifests
adding file changes
added 24 changesets with 350 changes to 320 files
updating to branch default
320 files updated, 0 files merged, 0 files removed, 0 files unresolved
Note: The number of files listed varies with the number of files in archive.

Success!

Next, you can clone the students archive for the region you are in.

For cloning the European students archive Type:

hg clone ssh://mercurial/academy.2015.europe

For cloning the Asian students archive Type:

hg clone ssh://mercurial/academy.2015.asia

Step 7: Updating the Archive

First move into the directory of your clone of the archive

Type:

cd ~/Desktop/academy.2015.tutorials

Now try pulling new changes into your archive

Type:

hg pull

You should see a response like this:

pulling from ssh://mercurial/academy.2015.tutorials
searching for changes
no changes found

However, if you get a response like this:

pulling from ssh://mercurial/academy.2015.tutorials
searching for changes
adding changesets adding manifests adding file changes added 1 changesets with 2 changes to 2 files 2 files updated, 0 files merged, 0 files removed, 0 files unresolved (run 'hg update' to get a working copy)

Then somebody else has made a change in the mean time, and you need to update

Type:

hg update

Congratulations! You have been successful and you can now work with the archive. Look over the Mercurial basics and resources page.

Troubleshooting:

If you are asked for a password:
Press "Control-C" and read the error. Usually Mercurial can't find the keys or the key file permissions are wrong. (see steps 2, 3 & 4 ).

Working With Mercurial

Look over the Mercurial basics and resources page.

Tutorial originally by Anna Kaziunas France

Modified by Zaerc - Last Updated Februari, 10th 2015