Distributed Version Control system

The CHILL facility now uses the distributed version control system, Git., we have switched over from using the legacy CVS system.

We maintain a master repository at the CHILL site, which retains the "golden" copy of the code base. Users may clone this repository and work independently, and those with write access can push their changes back to the master repository. In order to comply with CSU IP policy, anonymous access to the git repository is not enabled, you must have an account to use the system.

The following guide to accessing the repository assumes a Linux machine.

Overview

Everyone accesses the repository via ssh as single user called gitosis. User gitosis exists only on our server, and is restricted to do only repository maintenance tasks. Gitosis checks your ssh credentials against your public key which the administrator has stored in a special directory. This way, remote users do not have to have a login account on the server.

Key Generation

We need a ssh public key file from each person who needs read or write access to the repository. You may already have such a file (usually called id_rsa.pub) in your ~/.ssh directory. If not, you can create one on the machine from which you would like to access the CHILL Git repository :

ssh-keygen -t rsa

You will be prompted for a directory (the default .ssh is fine) and a passphrase. A passphrase is optional, but recommended, you'll need to enter it each time you access the remote repository.

It is not necessary to use the RSA cypher, if your system already has a key with a different cypher (such as DSA), that will work too, but the file names will be different. Contact your system administrator.

This will create a file called ~/.ssh/id_rsa with your private key and ~/.ssh/id_rsa.pub with your public key. Copy the public key to some convenient location, then rename it to username.pub

cp ~/.ssh/id_rsa.pub ~/my_name.pub

Of course, use your own user name here. It is not necessary to use exactly the same user name as your local login, but it helps us distinguish one key from another.

Creating an account

Next, you can email the public key file to Git Request. Please include a short description of why you want access to the repository as well.

Getting Started on your machine

On your local machine, you may need to install the git software. You can probably do this easily using yum or apt-get to download and install git.

Next, you need to modify your ssh setup to use a different port when contacting the CHILL servers, this is a security measure. Edit the ~/.ssh/config file. Create one if it doesn't exist, and add the following lines:

Host git.chill.colostate.edu
        Port 20789

With git, you have your own git repository on your local machine. This is a directory called cdp (assume repository name is cdp) where you develop the software. The version tracking information is stored in hidden directories within cdp.Your first move is to 'clone' the CHILL repository on your local machine, using the command:

git clone gitosis@git.chill.colostate.edu:cdp.git

Git will create a directory called cdp in your present working directory, and copy all the files and version information from lab's repository to your cdp directory.

Routine Usage

The gitolite server manages authorization of who gets access to what repository. To query the list of repositories one has access to, one can give

ssh gitosis@git.chill.colostate.edu info

Since it's possible that others are uploading files to the remote repository, it's a good idea to do a:

git pull

before you start working with the cdp code to assure that your local repository is up to date. Your typical workflow would be to edit, compile, debug programs in your cdp directories. You can do commits to your local repository as often as you want to track the changes you are making to the files. To do a commit, you first 'add' all files that have changed, then do a 'commit'.

So for example, say you modify hyid.c, config.h, generic_kdp_yw.c, you would commit these changes to your local repository with:

git add hyid.c config.h generic_kdp_yw.c
git commit

git commit brings up a text editor (vi, by default), shows you what files you're committing, also shows what files have changed. You can insert comments documenting what changes were made. Save and exit from the editor (:wq in vi) to complete the commit, or exit without saving changes to abort without committing.

When you are ready to send a new working version to the remote repository on lab, you do a push command:

git push

This will merge your changes into the remote repository. This will only work if write permissions are enabled.

If git detects conflicts merging in the changes on a pull or push, which it cannot resolve, it will tell you what files had problems. You then need to edit those files, look for the conflicts which will be flagged by a <<<<<< or >>>>>, and resolve them yourself.

More information about git may be found in the git tutorial.