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.
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.
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 email@example.com 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 firstname.lastname@example.org. 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 email@example.com, after they have registered their SSH public key with the service, you will then be able to authorize the user firstname.lastname@example.org access to your respository. More info below on how to authorize users.
Cloning/Creating a Repository
You can clone any repository you have read access to by issuing
git clone email@example.com:reponame
where reponame is the name of the repository you wish to clone. If reponame does not yet exist, a new repository of that name will be created with you as owner. (You will get a warning that you have cloned an empty repository.)
Note that only departmental users are authorized to create a new repository on our servers. So if you are a collaborator from outside the department, it's key that the person you are working with has created the initial copy of the repository.
If you are starting with work that already exists in a local git repository, you can add a remote branch reference pointing to our git service by
cd to reponame ie "cd /tmp/reponame/"
git remote add origin firstname.lastname@example.org: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
Some users have reported getting a permission denied error after this last step. The way around this is to do the creation-by-cloning step above (into an alternate location, so you don't overwrite your local work) and then do the git push from where your work is.
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 email@example.com command [options]
The following commands are available:
You can view the permissions on a repository you own by issuing
ssh firstname.lastname@example.org 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 the repositories hosted on the service for which you have read access.
You can only remove a repository from our server that you own. This can be done by issuing
ssh email@example.com rmrepo reponame
where reponame is the name of the repository.
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 firstname.lastname@example.org setdesc reponame < filenamewhere 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.
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 email@example.com to have read permissions you should create a file like
R = firstname.lastname@example.org
RW = dep1 dept2 dept3
Once you have this file you can update the permissions on the repository by issuing
ssh email@example.com 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.
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.