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 (id_rsa.pub) from each person who needs read or write access to the repository. You may already have such a file 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.

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 ~/jgeorge.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 then email the public key file to David Brunkow or Jim George, and we will add you to the list of git users. Please include a short description of why you want access to the repository as well. You can obtain email information from the Contacts page.

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 basically just 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. CSU-CHILL remote git repositories are kept on host lab.chill.colostate.edu. Your first move is to 'clone' the remote repository on your local machine. If you already have a directory with the same name as the repository, you should rename it as something else. When you enter 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

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, the 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 the vi editor, shows you what files you're committing, also shows what files have changed. You are expected to insert comments at the top of the file, documenting what changes were made. Then when you write your comments out and exit vi, and the commit will be completed. If you quit vi without writing your comments, the commit will be aborted.

Doing these commits to your local repository is a good way to track changes you make to the files. It might be useful to do a commit at the end of each day you work on the project. When you are ready to send a new working version to the remote repository on lab, you just do a push command:

git push

This will merge your changes into the remote repository.

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.

These are the basics. There is also much git documentation online to refer to.

Information about git may be found in the git tutorial.