Working with Git and Gerrit Code Review¶
- Working with Git and Gerrit Code Review
The TYPO3 project uses Git and the Gerrit Code Review system to channel commits for review.
What <projectname> means in this documentation¶
When we use <projectname> in the following documentation and examples, this means the project name as used in gerrit. If you are unsure you can find out the correct URL to clone from by going to http://git.typo3.org and copy it from the summary page of the project you're interested in. Here are some examples of <projectname>:
- For a quick "Getting Started" guide, see the Gerrit and Git Quickstart
- Here is a transcript of a session Cloning the FLOW3 Base Distribution
- Here is a transcript of a session Cloning the TYPO3 Phoenix Base Distribution
- If you just want to get the latest sources see: http://wiki.typo3.org/Clone_%28Git%29
Note: Take time to learn and explore git and gerrit!
- See Working with Git
Gerrit Code Review¶
Registering with gerrit¶
To register with gerrit, you need to have an account on typo3.org. Then visit https://review.typo3.org/ and log in using your typo3.org username and password. Click on 'Settings' -> 'Profile', and check that gerrit correctly knows your name and email address (it should; if not it might take a while for the synchronization to take place).
In order to be able to upload code, you now 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 dsa -f ~/.ssh/id_dsa
The public key for this is now stored in ~/.ssh/id_dsa.pub.
To tell gerrit about your key, log in, and go to 'Settings'. Select '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.
Setting up ssh config¶
To make things easier, set up ssh so that it knows about the defaults for the gerrit server. Edit
~/.ssh/config, and add a section like:
Host review.typo3.org User <username> Hostname review.typo3.org IdentityFile ~/.ssh/id_dsa Port 29418
(where <username> is what you logged in with, i.e. your typo3.org username)
To verify your ssh key is working correctly, try using an ssh client to connect to gerrit. You should get the following output if it all works:
$ ssh review.typo3.org gerrit: no shell available Connection to review.typo3.org closed.
Now you can configure git to push to Gerrit whenever you clone something from git.tyo3.org. All you need to do (for git > 1.6.4) is this
git config --global url."ssh://review.typo3.org".pushInsteadOf git://git.typo3.org
Now you can clone from git://git.typo3.org and a push on that clone would go into ssh://git.typo3.org using your configure username and port from above.
The Change-Id hook¶
Gerrit introduces the concept of "Change IDs". This is a unique reference for a particular change, which remains constant regardless of any changes that are made to the implementation. This allows a single reference to be attached to a given modification, irrespective of any rewrites that may occur as a result of review comments. Manually maintaining change ids is a pain, so gerrit provides a git hook which can be used to automatically add a change id to any new modifications you create.
Because hooks cannot be transferred with a clone of a project, you must copy them to your
.git/hooks directory and make them executable. The hook can be downloaded from the gerrit server by running the following in the top level of your git tree
scp -p -P 29418 review.typo3.org:hooks/commit-msg .git/hooks/
Do this for every working copy you clone! Make sure the hook is marked as executable after it is installed (scp should take care of this)!
When using a superproject with submodules, you can use this to install the hook for every submodule:
git submodule foreach 'scp -p -P 29418 review.typo3.org:hooks/commit-msg .git/hooks/'
If you cannot use scp (you should, it takes care of permissions automatically!), you can download the hook via HTTP, e.g. using
wget or a browser, from
Windows users: If you are using msysgit, the hook and scp work as shown here, simply use the git shell included with msysgit.
Different roles for Gerrit¶
The things we did until now described more generally the settings for git and gerrit on your machine.
Now we will get in touch with the two main roles you can have in gerrit.
... to the folks over at OpenAFS that made us stumble over gerrit and whose wiki page we shamelessly used as a base for this page.
... to Sebastian Kurfürst, Peter Niederlag, Christopher Hlubek for their help with git, gerrit and redmine.
... Bastian Waidelich for being the brave Windows test user.
... to Shawn Pearce for being helpful on the gerrit mailing list.
... to the TYPO3 Core Team for being open towards a change in SCM flavor.