Installing Mercurial on Mac OS

NOTE: This is a fork of the tutorial with some URLs and ports replaced with those specific to the Providence Fab Lab at AS220. We're running a local 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 you can skip to step 5.

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.

• Step 1: Install Mercurial
• Step 2: Key Files
• Step 3: Permissions for the Private Key
• Step 4: Setting the Port
• Step 5 Clone the Archive
• Step 6: Edit the Configuration File
• Step 7: Update the Archive
• Working with Mercurial
  
  

Step 1: Install Mercurial

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

Step 2: Key files

You need to put key files (academy and academy.pub) where Mercurial can find them.

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

You will be in your home directory by default. Your prompt with 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.

Type the following text into the terminal after the prompt:

ls ~/.ssh  

You system will 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).

Type:

mkdir ~/.ssh        

Within the .ssh directory you need to create another directory called keys.
To do this type:

mkdir ~/.ssh/keys

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

Change your location in the terminal by moving to the Desktop folder.

Type:

cd ~/Desktop

You need to move both of the keys from your desktop to the keys directory that you created earlier.

Type:

mv academy ~/.ssh/keys

Then type:

mv academy.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 academy and academy.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 600 ~/.ssh/keys/academy 

chmod 644 ~/.ssh/keys/academy.pub

Step 4: Setting the port

You can skip this step since our local server is using port 22, which is the default.

Step 5 Clone the Archive

Now we need to clone the archive for you region: na=North America, sa=South America, eu=Europe, as=Asia, af=Africa. Ask your Local Instructor or Remote Guru what archive to clone. In this example we are copying the North American (na) repository.

For convenience, we will clone it to the desktop.

Copy the text and paste it into the terminal:

hg clone -e "ssh -i ~/.ssh/keys/academy" ssh://as220mercurial@mercurial.as220.org/hg/repos/academy.2015/na providence.academy.2015

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".

Type "yes"

You should see the following response (or a similar response) in the terminal as the archive is cloned. Success!

requesting all changes
adding changesets
adding manifests
adding file changes
added 10 changesets with 119 changes to 112 files
updating to branch default
111 files updated, 0 files merged, 0 files removed, 0 files unresolved

Next, clone the tutorials archive so you can edit and add to the tutorials as we go along. The tutorials are in the /doc archive:

hg clone -e "ssh -i ~/.ssh/keys/academy" ssh://as220mercurial@mercurial.as220.org/hg/repos/academy.2015/doc providence.academy.2015.tutorials

Step 6: Edit the Configuration File

Now you need to edit your archive's personal configuration file. To do this you need to move into the archive folder that you just created on the desktop. It is called academy.2015

Type:

cd providence.academy.2015

You are now within the academy.2015 directory.

To edit your archive's personal configuration file (called hgrc) to reflect your name and email we need to open the file in a editior:

Type:

nano .hg/hgrc

A text editor will open inside of the terminal window. This text should already be in the file:

[paths]
default = ssh://hg@fabacademy.org/academy.2015/Web/na

Put the following text in the file: 

[ui]
username = First Last <user@machine.domain>
ssh = ssh -i ~/.ssh/keys/academy -C
[hooks]
changegroup = hg update >&2

• Change the First and Last Name to your first and last name.
• Change the "<user@machine.domain>" text to your email address.

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

Step 7: Update the Archive

Now try updating your archive by typing:

hg pull

you should see a response like this:

pulling from ssh://as220mercurial@mercurial.as220.org/hg/repos/academy.2015/na
searching for changes
no changes found

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

However, if you get a response like this:

pulling from ssh://as220mercurial@mercurial.as220.org/hg/repos/academy.2015/na
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)

Type "hg update", now you are successful.

Troubleshooting:

If you are asked for a password:
then Mercurial can't find the keys or the key file permissions are wrong. (see steps 2 & 3).

Working With Mercurial

Look over the Mercurial basics and resources page.