Working with Git and Gerrit » History » Version 45

Philipp Müller, 2015-03-18 14:42

1 1 Karsten Dambekalns
h1. Working with Git and Gerrit Code Review
2 22 Karsten Dambekalns
4 1 Karsten Dambekalns
5 38 Peter Niederlag
The TYPO3 project uses Git and the Gerrit Code Review system to channel commits for review.
6 20 Karsten Dambekalns
7 42 Michael Voehringer
Here is what you need to know to contribute, more details on Git are available in the "Pro Git book":, the "Gerrit documentation": and other resources (see "helpful links" section below).
8 1 Karsten Dambekalns
9 28 Karsten Dambekalns
h2. What <projectname> means in this documentation
11 38 Peter Niederlag
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 and copy it from the summary page of the project you're interested in. Here are some examples of <projectname>:
12 28 Karsten Dambekalns
14 38 Peter Niederlag
15 28 Karsten Dambekalns
16 26 Karsten Dambekalns
h2. Quickstart Guides
17 1 Karsten Dambekalns
18 26 Karsten Dambekalns
* For a quick "Getting Started" guide, see the [[Gerrit and Git Quickstart]]
19 44 most wanted
* "Contribution Walkthrough with CommandLine":
20 26 Karsten Dambekalns
* 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]]
22 25 Sebastian Kurfuerst
23 40 Björn Pedersen
* If you just want to get the latest sources see:
25 26 Karsten Dambekalns
*Note:* Take time to learn and explore git and gerrit!
27 1 Karsten Dambekalns
h2. Git
28 24 Karsten Dambekalns
29 32 Stefano Kowalke
* See [[Working with Git]]
30 1 Karsten Dambekalns
31 24 Karsten Dambekalns
h2. Gerrit Code Review
32 1 Karsten Dambekalns
h3. Registering with gerrit
35 26 Karsten Dambekalns
To register with gerrit, you need to have an account on Then visit and log in using your 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).
36 1 Karsten Dambekalns
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
<pre>ssh-keygen -t dsa -f ~/.ssh/id_dsa</pre>
The public key for this is now stored in ~/.ssh/
42 23 Karsten Dambekalns
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.
44 27 Karsten Dambekalns
45 31 Stefano Kowalke
h3. Setting up ssh config
47 1 Karsten Dambekalns
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:
49 23 Karsten Dambekalns
User <username> 
50 34 Stefano Kowalke
51 1 Karsten Dambekalns
IdentityFile ~/.ssh/id_dsa 
Port 29418</pre>
53 23 Karsten Dambekalns
(where <username> is what you logged in with, i.e. your username)
54 1 Karsten Dambekalns
55 23 Karsten Dambekalns
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:
56 1 Karsten Dambekalns
<pre>$ ssh
57 23 Karsten Dambekalns
gerrit: no shell available
Connection to closed.</pre>
59 4 Karsten Dambekalns
60 45 Philipp Müller
Now you can configure git to push to Gerrit whenever you clone something from All you need to do (for git > 1.6.4) is this
61 30 Karsten Dambekalns
<pre>git config --global url."ssh://".pushInsteadOf git://</pre>
Now you can clone from git:// and a push on that clone would go into ssh:// using your configure username and port from above.
66 36 Stefano Kowalke
h3. 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.
69 43 Markus Klein
*Important:* TYPO3 CMS uses a different commit-msg hook. Please find more information "here":
70 36 Stefano Kowalke
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
<pre>scp -p -P 29418 .git/hooks/</pre>
*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:
<pre>git submodule foreach 'scp -p -P 29418 .git/hooks/'</pre>
If you cannot use scp (you should, it takes care of permissions automatically!), you can download the hook via HTTP, e.g. using @curl@, @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.
84 41 Chris topher
h3. Different roles for Gerrit
85 1 Karsten Dambekalns
86 37 Stefano Kowalke
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.
* [[Working with Gerrit as a Developer]]
* [[Working with Gerrit as a Reviewer]]
91 29 Bastian Waidelich
h2. Helpful links
* "Git Homepage":
* "Pro Git book":
* "Git ready - tutorials":
* "Gerrit documentation":
98 4 Karsten Dambekalns
h2. Thanks
100 1 Karsten Dambekalns
... 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.
102 2 Karsten Dambekalns
... to Sebastian Kurfürst, Peter Niederlag, Christopher Hlubek for their help with git, gerrit and redmine.
105 23 Karsten Dambekalns
... Bastian Waidelich for being the brave Windows test user.
106 26 Karsten Dambekalns
... to Shawn Pearce for being helpful on the gerrit mailing list.
108 5 Karsten Dambekalns
109 1 Karsten Dambekalns
... to the TYPO3 Core Team for being open towards a change in SCM flavor.