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.
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".
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.
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! ;))
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
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 <user@machine.domain>
To save the file:
- press [control]+O to save the file (then the enter key)
- press [control]+X to exit the editor
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
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
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.
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 ).
Tutorial originally by Anna Kaziunas France
Modified by Zaerc - Last Updated Februari, 10th 2015