Tumble Subversion Repository README

This document contains information on how to use subversion, specifically on how to access the Tumble package code. The material is intended for those not familiar with version control software, or those who have used CVS, but not subversion. For instructions on building the Tumble code, please see the README file provided with the source.

To get access to the repository, you must have ONE of:
1) An apache account on lax.orasis.cs.cmu.edu
2) A machine account on lax.orasis.cs.cmu.edu
3) An SSL certificate signed by the lax.orasis.cs.cmu.edu certificate

To get an account please email Mark Olah.

For the Impatient

Here are the commands to get you started using the apache account:

$ mkdir ~/tumble
$ cd ~/tumble
$ svn co --username user https://lax.orasis.cs.cmu.edu/repos/tumble/trunk

In this case the password will be your apache password for lax. If you also have a machine account for lax, you can checkout with:

$ svn co --username user svn+ssh://lax.orasis.cs.cmu.edu/repos/tumble/trunk

In this case the password in the machine account password

What is Subversion

Subversion is a version control program. It is a modern replacement for CVS. Many of the commands used with CVS also work in subversion, and the syntax is also reasonably similar.

The subversion executable is called 'svn'. The executable is commonly followed by a command and several flags and/or arguments. For information on the details of using subversion, see The Subversion Book, a free on-line copy of the O'Reilly book, as well as the Subversion Project page.

Getting Subversion

The command-line subversion program is available as source code, as well as in pre-built binary packages for: RedHat, Debian, Suse, FreeBSD, Solaris, OSX, and Win32 at the Subversion Download page. For Win32 users a GUI version TortoiseSVN is also available.

Using Subversion to get Tumble

To work with a subversion repository you first make a local, working copy of the repository.

1. Make a new empty directory to store the working copy
   $ mkdir ~/tumble
   $ cd ~/tumble

2. Check out the main line of development (the trunk). This is the stable code.
   To authenticate with an apache account on lax, use:
   $ svn co --username user https://lax.orasis.cs.cmu.edu/repos/tumble/trunk
   To authenticate with a machine account on lax, use:
   $ svn co --username user svn+ssh://lax.orasis.cs.cmu.edu/repos/tumble/trunk
   
   
   

You now have all of the Tumble code.

Other common Subversion Operations

Note: all commands should be run from the repository directory you are interested in working from (most likely the trunk directory). The commands will affect files and directories recursively up the tree (not down), so that you will not have updated/committed all files unless you run the commands from the trunk directory.

On a daily basis, you should update your working copy to incorporate changes to the code:
$ svn up

To check the status of your changes to the code run:
$ svn status

To remove any changes you have made to a file:
$ svn revert foo.c

To commit your changes, run:
$ svn ci
NOTE: It is good practice to update right before a commit (don't worry, update will never overwrite your changes)

Subversion is unlike CVS in that it versions the whole repository, not just a list of files. For this reason when you want to make 'meta' changes within the repository like adding, removing, copying, or moving files and directories you must use the subversion commands, not the file system commands. If you don't use the subversion commands, subversion will become confused when it can no longer find files you have moved. You should almost always commit your changes right before and after moving and deleting files. This is not required, but some headache inducing problems might occur if you wait too long to commit and someone makes changes to the file you wanted to delete.

To add files or directories:
$ svn add foo.c
$ svn add mydir

To make new directories:
$ svn mkdir mynewdir

To copy files or directories
$ svn cp foo.c foo2.c
$ svn cp mydir newlocation

To move fies or directories
$ svn mv foo.c bar.c
$ svn mv mydir newlocation

To remove files or directories:
$ svn rm foo.c
$ svn rm mydir
NOTE: when you delete directories, they will not disappear until after a commit. This is because there is information in the directory that needs to be communicated. DO NOT delete them by hand. This will only confuse subversion and you will have to re-update your repository and delete them again. Subversion will delete the directories from your disk automatically after a commit.

For more subversion information, please refer to The Subversion Book.

Using ssh-agent for password-less login (very convenient)

As you may have noticed already, every subversion command that requires access to the server requires you to log in via SSH. Entering your password so frequently can be very annoying, so annoying that you will be tempted to set up the frustratingly unfriendly ssh-agent program which maintains a keychain for you. This allows you to log into remote machines without entering your password. You simply have to enter your password once to add your key to the keychain.

This text is meant for OpenSSH users. For windows users try using the Putty ssh package.

What follows is a description on how to set up your computer, named, “foo.example.com” to connect to a host, named, “bar.example.com”. To begin, you must create a public/private key pair with the ssh-keygen program and distribute the public key to the machines on which you have accounts.

foo$ ssh-keygen -t dsa
foo $ cat ~/.ssh/id_dsa.pub | ssh user@bar.example.com “cat - >> ~/.ssh/authorized_keys2"

The commands given set up a DSA key, which is the most modern key available with OpenSSH, and the most secure. If you need to login to machines running older versions of OpenSSH, you may be required to use RSA or RSA1 keys. The procedure is essentially the same, however you must specify the key type with ssh-keygen, and be sure to add RSA1 keys to ~/.ssh/authorized_keys instead of ~/.ssh/authorized_keys2

When prompted for a password, you really should enter a password, and hopefully one different then your normal password. If someone figures out the password to your private key, then they can gain access to ALL of the systems you have password-less logins setup with.

Also make sure the following files and directories have the right settings (assuming your username is 'foo')

Setting up ssh-agent

This is the tricky part of the password-less setup. Thus, there are several methods for setting this up and lots of debate about which one to use. The basic idea is that you run ssh-agent and somehow communicate to all of your shells the location of this process. Then you run ssh-add once per key. It adds the keys to your keychain, and everyone is happy. Unfortunately, I don't know of any method which is superior in every way, in every situation. Most methods involve using your shell scripts to set up a per-login ssh-agent session, making your startx command run as a child process of ssh-agent, or using a program external to OpenSSH.

This is the best source I have found on the subject: http://www-106.ibm.com/developerworks/linux/library/l-keyc.html
The author has written a program, called, Keychain, which ensures you only need to set up one ssh-agent per user, not one per session as most other methods require.

The OpenSSH Manual has detailed information about how ssh-agent and ssh-add work.

Startx method

If you will be setting up ssh-agent only on your desktop machine, and use “startx” to start your XWindows session, I recommend this method as it has presented me with the least number of headaches.

In your .bashrc file, add:
alias startx="ssh-agent startx"

In your .xinitrc file, add near the top:
xterm -e ssh-add

When you start your X session, you will be prompted for your password. No need to source any shell scripts.