Git and Gerrit in the School of Informatics

Why use this service?

If you only want somewhere to host a git repository, then there are many sites offering this service on the Internet. However, most of them are oriented towards the git fork-and-pull work flow model. In this model, each developer maintains a public git repository in which their version of the upstream code is maintained. Whenever they want to submit a change to upstream, they submit a pull request to the upstream maintainer, who then fetches their changes from that repository and integrates them into the codebase. Gerrit, however, permits a push based development model, where a developer has access directly to upstream repository and can push changes directly into it. This can be done either directly, or via a code review stage, which allows the upstream maintainer to permit or reject changes.

Gerrit, therefore, allows development to occur with git in a slightly more centralised fashion. In particular, it avoids the issue of each developer having to maintain their own public tree, and permits a quicker code-review-integrate cycle than typically occurs with a pull based workflow. However, it still has all of the benefits of a distributed version control model, providing the best of both worlds.

Where can I find it?

GIT protocol access is available from git://git.inf.ed.ac.uk/<project>

Who can use it?

Any DICE user can ask for a repository to be created. Any DICE User, or iFriend, can then be given permission to access that repository. The contents remain the responsibility of the user who originally created the repository, however.

How do I go about using Git and Gerrit?

Set up an account with Gerrit
The first thing you need to do is to register an account with gerrit if you have not already done so. Visiting gerrit for the first time will automatically create an account there for you, which sets up a number of things behind the scenes. You'll note that initially gerrit doesn't know very much about you. Click on Settings at the top right hand side of the screen. You will notice that the box marked username is empty. Choose a suitable username (your DICE username would be a sensible, but not mandatory, option) and type it into the box. Note that this is a one-time operation, you can't change your username once it's been set. Then select Contact Information from the left hand side menu. Give it your Full Name and register an email address with it. Email address registration requires that you confirm your address by clicking on a link in an email you'll receive from gerrit.

Request a new repository
Once you have registered your account, please create a new ticket in the Services Unit RT queue asking for your repository to be created and giving its name and a brief description. You will be notified when your repository has been created.

configure access to your repository
When your project has been registered, you need to configure gerrit so that you, and your co-developers, can actually work on the project. By default, no permissions beyond project ownership are assigned. How you set this up is really up to yourself, and the way that your project wishes to operate. Initially, a single group has been created called "
<project name> Owner", of which you are the sole member. Gerrit divides access control into a number of areas, which are fully described in its access control documentation. Essentially, you can control who may mark code as having been reviewed, who can mark code as verified, who can decide to push reviewed & verified code into the tree, and who can bypass the verification process entirely. You may decide you wish to have separate groups for all, or some of those permissions, or to have a single "project Contributors" group with review and verify permissions, and to give the "project Owner" group submit permission. The choice is yours!

When you've decided how to set up your access control, visit Gerrit's Admin > Groups page to create new groups, and to assign users to the group. Note that to add a user to a group they must have already visited gerrit in order to have an account auto-created. Then, go to Admin > Projects, pick your project from the list, and select the Access tab. You can now assign access categories, and the level of access within that category to each of the groups you have created. Again, see the gerrit documentation for more details on all of this.

Register as a contributer

Gerrit uses ssh for uploads, and ssh public keys for authentication. In order to be able to upload code, you need to create a ssh key that gerrit can use to identify you, or tell gerrit about one that already exists.

To create a new ssh key, if you don't already have one, run
ssh-keygen -t rsa -f ~/.ssh/id_rsa

The public key for this is now stored in ~/.ssh/id_rsa.pub.

To tell gerrit about your key go to Settings > SSH Keys, and paste your public key into the Add SSH Public Key box, or click on the Open Key... option to load it from the filesystem. Click on Add to add the new public key. While you are on this page, make a note of your SSH Username, because you'll need to for the next step.

To make things easier, set up OpenSSH so that it knows about the defaults for the gerrit server. Edit ~/.ssh/config, and add a section like:

Host gerrit.inf.ed.ac.uk
User
IdentityFile ~/.ssh/id_rsa
Port 29418

(where SSH Username is what you were told on the the 'SSH Keys' page)

Note: If you change your preferred email address at a later date, gerrit will change your SSH username to match. Remember to copy this new value into your ~/.ssh/config file or you won't be able to upload any more code!

Importing an existing git repository

If you already have a git repository, which you now wish to manage in Gerrit, or if you simply want to use gerrit as an access control system, and bypass code review entirely, then you need to enable two access categories. For the set of people (yourself, if you're just wanting to push an initial repository, your whole development team if you wish to bypass code review) involved, give their group Push Branch permission, with a range from +1 to +3, and Push Annotated Tag, with a range from +1 to +3

You can then push your existing repository into gerrit by doing

git push -all ssh://gerrit.inf.ed.ac.uk/project

Note: If you didn't set up your SSH configuration as shown above, then you have to explicitly include the port number in this, and all other, command lines

git push -all ssh://gerrit.inf.ed.ac.uk:29418/project

Unless you are intending to bypass code review, go back into Gerrit and disable the Push Branch and Push Annotated Tag permissions that you just granted

Contributing through gerrit

Your project is now open for contributions through the gerrit tool.

Potential contributors can clone copies of your project by running

git clone git://git.inf.ed.ac.uk/project.git

This repository can then be managed as a normal git repository - fetching new changes with git fetch or git pull, checking out branches for work with git checkout and so on.

Gerrit requires that the email address that git knows you as matches an email address that you have listed in gerrit. You can tell git your identity by running

It's strongly recommended that you create a topic branch for each logical set of changes.

When you have a set of changes which you wish to submit upstream, you can see what changes you're about to submit by running

git log -p origin/master..HEAD

Providing you're happy that all of those changes should go upstream, you can submit them by running

git push ssh://gerrit.inf.ed.ac.uk/project HEAD:refs/for/master

Your change is then in the web interface where it may be reviewed, tested, and if all is OK, submitted to the tree. If someone has objections to your change, then you may be asked to amend it. In this case, you should using git commit --amend, or git rebase -i to merge your modifications with the original change, and then submit the modified change to gerrit with

git push ssh://gerrit.inf.ed.ac.uk/projecthash:refs/changes/number

(where hash is the hash of the revised change, obtained by running git show, or git log, and number is the change number that gerrit gave you when you originally submitted it)

Gerrit now support the use of Change IDs in the commit message. A Change ID uniquely identifies a change across all drafts and gerrit can automatically associate a new version of a change back to its original review, even across cherry-picks and rebases. To be picked up by Gerrit, a Change-Id line must be in the bottom portion (last paragraph) of a commit message, and may be mixed together with the Signed-off-by, Acked-by, or other such footers.

To handle Change IDs you need to add a commit-msg hook to your project. Gerrit Code Review provides a standard commit-msg hook which can be installed in the local Git repository to automatically create and insert a unique Change-Id line during git commit. To install the hook, copy it from Gerrit's SSH daemon: