forge.typo3.org

h1. Working with Git and Gerrit Code Review

{{>toc}}

For FLOW3 and TYPO3 Phoenix we are using Git and the Gerrit Code Review system to channel commits for review.

Here is what you need to know to contribute, more details on Git are available in the "Pro Git book":http://progit.org/book/, the "Gerrit documentation":https://review.typo3.org/Documentation/index.html and other resources (see "helpful links" section below).

h2. 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 git.typo3.org and copy it from the summary page of the project you're interested in. Here are some examples of <projectname>:

 FLOW3/Distributions/Base

FLOW3/Packages/Party

TYPO3v5/Distributions/Base

h2. Quickstart Guides

* 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]]

*Note:* Take time to learn and explore git and gerrit!

h2. Git

* See [[Working with Git]]

h2. Gerrit Code Review

h3. 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

<pre>ssh-keygen -t dsa -f ~/.ssh/id_dsa</pre>

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.

h3. Push and Pull from different URLS

In our environment its necessary to pull from git://git.typo3.org but push to review.typo3.org.

You can set this globally for git by editing the git config file.

*Note:* You need git > 1.6.4

<pre>git config --global url."ssh://USERNAME@review.typo3.org:29418".pushInsteadOf git://git.typo3.org</pre>

Now you can clone from git://git.typo3.org and a push on that clone would go into ssh://USERNAME@git.typo3.org:29418. 

You can leave out username and port, if you configure those centrally in your SSH configuration.

h3. 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:

<pre>Host review.typo3.org 

User <username> 

IdentityFile ~/.ssh/id_dsa 

Port 29418</pre>

(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:

<pre>$ ssh review.typo3.org

gerrit: no shell available

Connection to review.typo3.org closed.</pre>

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

<pre>git config --global url."ssh://review.typo3.org".pushInsteadOf git://git.typo3.org</pre>

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.

h3. [[Working with Gerrit as a Developer]]

h3. [[Working with Gerrit as a Reviewer]]

h2. Helpful links

* "Git Homepage":http://www.git-scm.com/

* "Pro Git book":http://progit.org/book/

* "Git ready - tutorials":http://gitready.com/

* "Gerrit documentation":https://review.typo3.org/Documentation/index.html

h2. Thanks

... to the folks over at "OpenAFS":http://openafs.org/ 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.