Week 02 - Jan 25th 2012 - Collaborative Technical Development, Documentation and Project Management

Weekly Assignment - Build a personal website

In order to interact with the fablab server we need to use Mercurial distributed revision control software. Mercurial can be run from the command line, or using a third-party GUI. The process of setting up a MacOS GUI was not particularly well documented, so I have included below a summary of the steps I found to allow successful connection to the fablab repository.

Instructions for connecting to the fablab repository from MacOS using MagHg:

Step 1: Download everything you need

  • Mercurial binary packages - the base installation that you can use from Terminal.
  • MacHg - MacOS native GUI.
  • DiffMerge - compare and merge software required for MacHg. See here for other options.
  • Two ssh keys - academy and academy.pub, provided by your lab manager. Place them in your home directory (~/) for now.

      • Step 2: Install the software components

      • Install Mercurial - unzip Mercurial-2.0.2-py2.6-macosx10.6.zip and run the installer package. No application will be visibly installed but you can open Terminal and type hg version and if all is well you will see a short copyright notice.
      • Install MacHg - unzip MacHg0.9.25.zip and drag the MacHg program to the Applications directory.
      • Install DiffMerge - mount DiffMerge.3.3.2.1139.dmg and drag the DiffMerge program to the Applications directory.

      Step 3: Setup the ssh keys and config file

    • Make the ~/.ssh directory: open Terminal, ensure you are in the home directory with cd ~ then create ~/.ssh with mkdir .ssh. Move both keys in with mv academy .ssh and mv academy.pub .ssh. Change to the .ssh directory with cd .ssh and confirm the keys are there with ls - academy and academy.pub should be listed.
    • Alter the access permissions for the private key: sudo chmod 600 ~/.ssh/academy.
    • Create a config file to store the fablab settings: vim ~/.ssh/config brings up a text editor; press i to enter insert mode and type the following
      Host fablab HostName fab.cba.mit.edu Port 846 User hg IdentityFile ~/.ssh/academy
      Press Esc to exit insert mode, then :wq and Enter to 'w'rite the file contents and 'q'uit. To confirm the file setup, type cat ~/.ssh/config to diplay the config file contents.

    Step 4: MacHg preferences

    • Open the MacHg application. In the preferences, make the following changes:
    • Mercurial tab - set both 'For Diffs use:' and 'For Merges use:' to DiffMerge using the drop-down boxes.
    • Advanced tab - click 'Edit' next to '~/Application Support/MacHg/hgrc' and add the following to the bottom of the file (substituting in your details):
      [ui] username = Firstname Lastname (your@email.com)
      Save and close the hgrc file, and close the preferences pane.

    Step 5: Get started with MacHg

    • Click 'Clone a Repository' to bring up the settings panel. Add the following details:
      Short Name: fablab Server URL: ssh://fablab/academy.2012 Username: hg
      At this point the connection to the server will appear to fail so click 'Test in Terminal'. A Terminal window will open and will prompt you to indicate whether you really do want to connect; type yes and press Enter to confirm the connection. Close the Terminal window, and now the MacHg settings panel should indicate a successful connection (you may need to re-enter the username to cause MacHg to try the connection again).
    • Click 'Add and Clone' and select the location on your computer that you would like to use to store the local copy of the repository. The current state of the repository will be downloaded to your computer.

    From here you can follow the general Mercurial instructions for routine interaction with the repository, and if you find soemthing you can't do with the GUI you always have the option of using the command line. Normal rules apply; trying to push without merging will give an error that should not be overridden ('forced').

    For further info on MacOS Terminal commands see here. The tutorial found here and the MacHg help document here provided the starting points for this setup. If you find any issues, please do let me know!

    <<< Week 01

    Week 03 >>>