Notes on Mercurial Installation
Added 9-20-11: Quick start tutorial. The old instructions have more explanations, so read them if you want to learn what it is you're doing as you type these commands!
Mac OS X:
1. Save the ssh keys from the email to your Downloads directory.
2. Download and install Mercurial from here: http://mercurial.selenic.com/
It will look like nothing was installed to Applications…instead, it gives you a new set of command line tools, notably the command "hg."
3. Go to Applications -> Utilities and open the application Terminal.
Type the following:
mkdir ~/.ssh
mv ~/Downloads/classes.txt ~/Downloads/classes (might be necessary)
mv ~/Downloads/classes ~/.ssh
mv ~/Downloads/classes.pub ~/.ssh
sudo chmod 600 ~/.ssh/classes
echo -en "host fab.cba.mit.edu\nport 846" > ~/.ssh/config
Change path in red below to wherever you would like to store the archive (or leave on Desktop):
mkdir ~/Desktop/Archive
hg clone -e "ssh -i ~/.ssh/classes" ssh://hg@fab.cba.mit.edu/863.11 ~/Desktop/Archive
Change to your name and email address, then paste the entire line into the terminal:
echo -en "\n\n[ui]\nusername = First Last <email@mit.edu>\nssh = ssh -i ~/.ssh/classes -C\n\n[extensions]\nconvert =\nfetch =\n\n[hooks]\n\nchangegroup = hg update >&2" >> ~/Desktop/Archive/.hg/hgrc
Done. You should be able to go to your class directory via the Finder and edit your index.html file to begin creating your class page. See "Using Mercurial" below.
Windows:
1. Save the ssh keys from the email to your Downloads directory.
2. Download the Cygwin installer from here: http://cygwin.com/install.html
Run setup.exe. Click through the defaults until you get to Select Packages. Select openssh under Net (click on "Default" to change it to "Install"), vim under Editors, and mercurial under Devel at minimum. Finish install (this can take a while).
3. Open Cygwin from Applications. Type the following:
mkdir ~/.ssh
mv /cygdrive/c/Users/<username>/Downloads/classes.txt /cygdrive/c/Users/<username>/Downloads/classes (might be necessary)
mv /cygdrive/c/Users/<username>/Downloads/classes ~/.ssh
mv /cygdrive/c/Users/<username>/Downloads/classes.pub ~/.ssh
chmod 600 ~/.ssh/classes
echo -en "host fab.cba.mit.edu\nport 846" > ~/.ssh/config
Change path in red below to wherever you would like to store the archive (or leave on Desktop):
mkdir /cygdrive/c/Users/<username>/Desktop/Archive
Optionally, make a shortcut so you don't have to keep retyping that!
ln -s /cygdrive/c/Users/<username>/Desktop/Archive 2011archive
hg clone -e "ssh -i ~/.ssh/classes" ssh://hg@fab.cba.mit.edu/863.11 2011archive
Change to your name and email address, then paste the entire line into the terminal:
echo -en "\n\n[ui]\nusername = First Last <email@mit.edu>\nssh = ssh -i ~/.ssh/classes -C\n\n[extensions]\nconvert =\nfetch =\n\n[hooks]\n\nchangegroup = hg update >&2" >> 2011archive/.hg/hgrc
4. If you will be using TortoiseHg (install from here), you need to add ssh to your PATH. Right click on My Computer, choose Properties, click "advanced system settings," click on Environment Variables. Scroll down to Path under System Variables and click edit. Add the following to the end of the Variable value list:
;C:\cygwin\bin\
Using Mercurial:
Get comfortable with this workflow.
Or install one of the GUIs listed here: http://academy.cba.mit.edu/classes/project_management/archive.html
Old tutorial with more details:
This was written for Mac OS X users, but many of the commands will be the same on Linux and Cygwin for Windows. Don't type blindly, it's entirely possible there are errors…
1. Download and install Mercurial from here: http://mercurial.selenic.com/
It will look like nothing was installed to Applications…instead, it gives you a new set of command line tools, notably the command "hg."
2. Download the two key files (863.10 and 863.10.pub) from the email and save them somewhere you will remember them, like the Desktop.
3. Copy the files to the ~/.ssh directory.
~/.ssh is a Unix file path telling you exactly where the directory ".ssh" is on your system. The ~ is a shortcut for your home directory, which is /Users/<your username> (that means a directory with your username is inside the "Users" directory, which is in turn inside the "/" directory, also known as the root directory because it is the root of the directory tree, ie. everything else is inside it). So .ssh is a directory inside /Users/<your username>. But you can't see it from the Finder because it's a hidden directory (denoted by the '.' at the beginning). So we need to copy the files using the command line.
To get to a command line, open the Terminal in Applications -> Utilities
Type 'pwd' after the $, so:
pwd
and hit enter.
It should say /Users/your username. This is because (unless you change this) you always start in your home directory. You can use the command:
ls
to list everything in that directory
To move up one level, type:
cd ..
(cd is "change directory," the '..' means the directory one level up).
To go into a specific directory in the one you are in, type
cd <name of directory>
To go to any directory regardless of where you are, you have to type the absolute path, for instance:
cd /Users/username>/Desktop
Something enormously helpful is hitting tab once you've typed a few letters…it will autocomplete names of files in the directory you're dealing with.
When you are comfortable with pwd, ls, and cd …
Make a .ssh directory, if you don't already have one.
To check:
cd ~/ (go back to your home directory)
ls -a (the -a flag reveals hidden files)
If you don't see .ssh listed, you need to make one using the make directory command:
mkdir .ssh
Now you can copy the key files into your .ssh directory. The command to copy a file is "cp" and it takes two arguments, the file to copy and the place to copy it to. For example (this may vary depending on where you put your key files):
cp /Users/<your username>/Desktop/863.10 ~/.ssh
Using absolute paths to make it really clear, but if you're still in your home directory you could do it based on that:
cp Desktop/863.10 .ssh
Now repeat this to copy 863.10.pub over.
Change directories to .ssh and use ls to make sure both files are there!
4. Edit the config file in ~/.ssh
This instruction is about editing the config file in .ssh to change the port to connect to for ssh (ssh is a way of securely connecting to a remote directory used here to get the files for the class under Mercurial version control).
To create and edit that file, we can use the command line editor "vim"
vim ~/.ssh/config
Once inside vim, type the letter 'i' to enter "insert mode"
Now type these two lines:
host fab.cba.mit.edu
port 846
To save and close the file, hit the esc key to exit insert mode, enter ':' to enter command mode, enter wq to "write" and "quit," and then hit enter.
sequence is [esc] [ : ] [w] [q] [enter]
You should now be back to the command prompt. Go to the ~/.ssh directory and make sure there is a file called config there.
5. Change permissions on the 863.10 key file
Do:
sudo chmod 600 ~/.ssh/863.10
The sudo command makes that command run with administrator privileges.
chmod changes the permissions on the file, in this case the 863.10 file.
This is done so that nobody but your user can see the private key (and so that it actually looks like a private key to the ssh command, otherwise it will complain when you do the next step).
6. Clone repository:
Before running this command, use cd to go to a directory where you want all the files to end up! For example I put mine in ~/Desktop/Courses/HowToMake but yours could be anywhere you want it.
Now run:
hg clone -e "ssh -i ~/.ssh/863.10" ssh://hg@fab.cba.mit.edu/863.10 archive
(You can change the name "archive" to whatever you want to call the folder).
7. Edit repository configuration file:
Use vim as in previous instructions, OR you could do this:
open <path where you put the cloned directory>/863.10/.hg/hgrc
This will open it in TextEdit and you can edit it directly, then use the GUI menus to save and close the file.
Basically append (don't replace what's already in there) all this to the file (remember to add your name and email address:
[ui]
username = First Last <user@machine.domain>
ssh = ssh -i ~/.ssh/863.10 -C
[extensions]
convert =
fetch =
[hooks]
changegroup = hg update >&2
…then save and close.
8. Add your directory and class page.
cd <path where you put the cloned directory>/863.10/people
mkdir firstname.lastname
cd firstname.lastname
vim index.html
Type something (doesn't matter what for now but eventually will be html for your class page) into the index page file and then save and close the file as in the vim instructions earlier.
9. Add the file to version control, commit and push your changes.
hg pull
hg update
hg add .
hg commit -m "adding this file"
hg push
10. Start using the archive! Here's a Mercurial workflow cheatsheet.