Revision Control

At the heart of most software development is some form of revision control, also known as version control or source control. While it's fairly straight forward for a single developer or even a small number of developers to share a source respository, it becomes more complicated when you grow to large numbers or wish to work with outside contributors. To effectively do this type of development, one really needs a centralized service.

Git Services

We offer a centralized git service built upon gitolite. This is a lightweight centralized git repository, similar to what you will find at places like github.

This webpage is not intended to be a git tutorial. If you need an introduction to git in general, we suggest you talk with a local developer or read the official git tutorial.

Authentication

All gitolite authentication is done through SSH public keys. In order to use our service, you will need to email your SSH public key to problem@cs.brown.edu requesting access. The git server will reference you by your uid (unix username).

If you intend to collaborate with people outside the department, either you or the outside user will need to email their SSH public key to problem@cs.brown.edu. The git server will reference these users by their email address.

It's important to understand how the service identifies users, because this is how you will handle authorizing users access to your git repositories. For instance, if you (unix username of foo) creates a git repository on the server, the service knows that the user foo owns this particular repository. If want to collaborate with someone outside the department with the email address of bar@foobar.org, after they have registered their SSH public key with the service, you will then be able to authorize the user bar@foobar.org access to your respository. More info below on how to authorize users.

Publishing a Repository

Only departmental users are authorized to create a new repository on our servers. So if you are a collaborator, it's key that the person you are working with has created initial copy of the repository. Start with a local git repository. Add a remote branch reference pointing to our git service by

cd to reponame  ie "cd /tmp/reponame/"
git init
git add .
git commit -m *comments*
git remote add origin git@src.cs.brown.edu:reponame

where reponame is the name of the repository you wish to create. Repository names must be unique, so you might want to list the existing repositories trying to push your changes. Once you've defined a remote branch you can push your repository up to the server by running

git push origin master

Cloning a Repository

You can clone any repository you have read access to by issuing

git clone git@src.cs.brown.edu:reponame

where reponame is the name of the repository you wish to create.

Commands

Our git service provides a variety of commands users can use to view and owners can use to manage repositories. All commands are issued to service by running

ssh git@src.cs.brown.edu command [options]

The following commands are available:

getperms

You can view the permissions on a repository you own by issuing

ssh git@src.cs.brown.edu getperms reponame

where reponame is the name of the repository. This will output syntax in exactly the same format as our setperms file above.

list

List the repositories hosted on the service for which you have read access.

rmrepo

You can only remove a repository from our server that you own. This can be done by issuing

ssh git@src.cs.brown.edu rmrepo reponame

where reponame is the name of the repository.

setdesc

Only the creator of a repository can set the description on a repository. A portion of the description is show when a user requests a list of projects on the server. To set a description, you first need to create a text file containing the information you want published. You can publish the description to a repository by running:

ssh git@src.cs.brown.edu setdesc reponame < filename

where reponame is the name of the repository and filename is the file you created with the desired permissions. Note the presence of the < character before the filename.

setperms

Only the creator of a repository can set the permissions on the repository. To set permissions, you first need to create a text file listing the complete permissions you want to set on the repository. Available options are:

R      - for read permissions
RW  - for read write permissions

One of these should be the first character in each line of the file, followed by an equals sign and then a space separated list of users you want to grant permissions to. Say you wanted the departmental users dept1, dept2 and dept3 to have read write permissions and our collaborator bar@foobar.org to have read permissions you should create a file like

R = bar@foobar.org
RW = dep1 dept2 dept3

Once you have this file you can update the permissions on the repository by issuing

ssh git@src.cs.brown.edu setperms reponame < filename

where reponame is the name of the repository and filename is the file you created with the desired permissions. Note the presence of the < character before the filename. 

Advanced


Using an Alternate SSH Key

Suppose you want to use an alternate ssh key for git operations.  Git does not provide any command line options for configuring the ssh connection, so you'll need to do all the configuration via ssh.  You'll need to setup and ssh client configuration file, typically ~/.ssh/config, and add an entry that looks something like:

    Host src.cs.brown.edu
      User git
      IdentityFile ~/.ssh/id_rsa 

The bold portion is the only thing you should need to modify.