Copyright © 2012, 2013 Lars Vogel
|Revision 0.2 - 2.2||13.06.2012 - 07.10.2013||Lars
|bug fixes and improvements|
Table of Contents
During a code review process a proposed change is reviewed by other developers. Every contributer can suggest changes and update the suggested changes. Once the change is accepted by all relevant parties, it is applied to the code base.
For an efficient process it is important that the code review is conducted in a supportive environment where constructive feedback is given to enhance the change.
While a code review process can be implemented without any tool support, it is typically more efficient if a structured code review system is used. Gerrit is a code review system developed for the Git version control system.
In general a structure code review process has the following advantages:
Early error detection: errors are early identified in the process.
Conformity with source code standards: code review allows the team to identify early in the process any violations with the code standards of the team.
Knowledge exchange: the code review process allows newcomers to see the code of other more experienced developers and to get early feedback on their suggested changes.
Shared code ownership: by reviewing code of other developers the whole team gets a solid knowledge of the complete code base.
Code reviews in open tools provide people without the permission to push to a repository with a simple way to contribute their suggested changes and to get feedback.
Gerrit is a web based code review system, facilitating online code reviews for projects using the Git version control system. The user interface of Gerrit is based on Google Web Toolkit and its Git implementation is based on JGit.
A developer can use Gerrit to suggest a code change. Other developers can review the code change and suggest improvements. If a Gerrit change request needs improvement, it is possible to update it with a new set of changes. Once the suggested changes are accepted by the reviewers, they can be applied via Gerrit to the underlying Git repository.
Gerrit makes code reviews easier by showing changes in a side-by-side display. It also allows the reviewer to add comments to every single change.
The homepage of Gerrit is the following URL: Gerrit code review.
Gerrit works as a wrapper around a Git repository. It can prevent users from pushing directly to the Git repository. If you push to Gerrit, you use a certain path (ref specification) which tells Gerrit that you want to do a code review. This ref specification is /ref/for/master.
If you push to this ref specification, Gerrit creates a new review request or makes an update of an existing one. Gerrit uses the Change-Id information in the commit message to identify if the push is a new commit or an update of an existing review request.
A change consists of one or more patch sets. One patch set corresponds to one Git commit.
Download the latest Gerrit release from
Gerrit download page. The download is a
file which you can directly add to your servlet container, for
example, a Jetty or Tomcat installation.
file also contains a Jetty web server and can be started directly for
testing. The following description uses this approach.
file into an empty directory.
Switch on the command line to the location of the directory to which
you extracted the
Install and start
the following command.
java -jar gerrit*.war init -d review_site
The installation procedure allows you to configure your Gerrit
installation. The installation is done in the folder specified with
parameter, in this example "review_site".
The installation procedure asks a few question, pressing enter uses the default value which is typically fine for a test installation. A few of these options are discussed in the following table.
Table 1. Gerrit setup options
|Location of Git repositories||
Location of Git repositories, default is the
|Database server type||Gerrit supports several databases, by default it uses a preconfigured H2 database.|
|Listen on port||Allows you to configure the port Gerrit is listening to, Gerrit by default listens on port 29418 for SSH access and on port 8080 for web access. This can be changed if the ports are already used.|
|Authentication method||The easiest way of configuring access to Gerrit is to use OpenID Single Sign-on which is also the default setting. Use ? to see all available settings for this option.|
Use development_become_any_account to enable general access to Gerrit. This is a nice setting for testing. If started with this setting, you have a Become link in the web interface which allows you to login and to create a new account.
After a successful installation Gerrit starts automatically you can start and stop it again with the following commands.
# assumes you installed Gerrit in # the home directory under gerrit # start if not running ~/gerrit/review_site/bin/gerrit.sh start # stop it again ~/gerrit/review_site/bin/gerrit.sh stop
The local Gerrit configuration is stored in the
You require a valid Gerrit user to work with Gerrit.
Login to Gerrit via http://localhost:8080/login/. The first user to login automatically gets the administrator status.
From the user drop down menu select Settings and select SSH Public Keys to upload your public SSH key.
Based on your SSH key you are now able to exchange data with the Gerrit server.
Select Profile to assign a Username to your user.
This part is only relevant for the administrator. Create a new Git repository called gerrittest via EGit or the Git command line.
Create a the new Git repository in Gerrit via the following command.
# assumes that Gerrit runs on port 29418 # on localhost ssh -p 29418 <userid>@localhost gerrit create-project demo/gerrittest
The new project can be found in the Gerrit web interface under→ .
Select your project and. For testing give push rights to all registered users, which is the default after a fresh installation. In a productive environment you can configure Gerrit to be more restrictive.
Also for testing create a new Java project called com.vogella.gerrit.example in Eclipse that gets stored in a local Git repository. Add a few classes to it.
The following pushes the changes directly to the Git repository without a review request in Gerrit. Administrators are allowed to do this.
Afterwards push the local Git repository to Gerrit by selecting Next button.→ → . Enter the following URL ssh://<userid>@localhost:29418/demo/gerrittest.git in the wizard and press the
On the next page, click the Add All Branches Spec button.
Press the Next button and on the last wizard page the Finish button.
In this exercise you switch roles and act as a normal developer. You can use the administrator Gerrit user you created earlier or create a new user.
You need a fresh clone of the Git repository which the administrator created. Open a new workspace for this.
Open the Git Repositories view and select that you want to clone an existing repository. Enter the following URL: ssh://<user-id>@localhost:29418/demo/gerrittest.git
After you cloned the repository, right-click in the Git Repositories view on the origin remote and select Gerrit Configuration....
The default values in this dialog should be ok. Press the finish button.
This sets your push configuration for this remote to refs/for/master which tells Gerrit that you created or updated an review request. To valid the push configuration, right-click on your remote and select Configure push and ensure that the setting is similar to the following screenshots. It also adds a flag to your repository to tell EGit to always create a Gerrit Change-id.
Use the Properties view on your repository to see the details of your repository configuration.
The refs/for/master this ensures that every push is handled by Gerrit. If you use the /refs/heads/master ref mapping, you can directly push to the Git repository. This option is typically restricted to administrators.
You can also do this setup directly via the Git command line.
git config remote.origin.push refs/heads/*:refs/for/*
In the following description we make a change in our local repository and create a Gerrit change request.
Create a new local branch starting from the origin/master branch.
Perform some changes in your Java project. Commit the changes and ensure to select the Add Change-Id button in the Git Staging view .
The Change-Id is what uniquely identifies the change in Gerrit.
Push the change. As you adjusted your push configuration this should create a review request. In the Gerrit web interface you see the pushed change and can review it.
Do a few new changes to your Java project and commit them to your local Git repository. Ensure that you amend the existing commit. This makes sure the existing change id is used and avoids that Gerrit cannot apply your change because of a dependency cycle on the commits. Push your new commit to Gerrit, this should update the existing review request.
To review a Gerrit review request, open http://localhost:8080/. You see all change requests. Click on one change request to see the changes.
Click on the Side-by-Side link to see change changes introduced by the change. You can click on a line to comment on the change.
Clicking on Up to change brings you back to the change.
Gerrit allows you to review the commit message. Providing a good commit message is also important to understand the history of the repository later. Reviewing a commit message is done the same way as reviewing a file. The commit message appears at the top of the file list.
Click on Review to review the change. In the default configuration a +2 vote by one person is required to integrate the change into the main Git repository.
If you vote -1 and -2, you indicate that the patch still requires rework or that you disagree with the suggested change.
If the review process has resulted in required changes by the reviewers, the author of the patch (or someone else) can adjust the patch. In his local repository he amends the original commit and pushes his changes again to Gerrit. He can also adjust the commit message in his amended commit. If the developer uses the same Change-Id, the Gerrit review system identifies the change and updates the review request.
Gerrit allows you to select the Patch Set in the Comparison view of a file. This way you can review the changes after your last review.
After the patch is of sufficient quality, the reviewer can give a +2 evaluation of the change and afterwards press the Publish and Submit button.
In a typical Gerrit setup one developer is not allowed to give +2. This requires that at least two developers review the change before it is applied to the code base.
Press ? in the Gerrit web user interface to see the actions you can trigger via shortcuts.
It is possible to pull the changes from the Gerrit review into another local Git repository. The Gerrit page lists the required commands on the change. This is depicted in the following screenshot.
The other developer can adjust the change and amend the commit. If he pushes it to Gerrit, the review request is updated. Such a procedure should be coordinated by the author of the original change to avoid that two developers do the same work.
EGit allows to fetch a change from Gerrit. For this right-click on the project→ → . You can use Ctrl+Space to select existing changes and create local branches for the change to test the changes in isolation.
The push to Gerrit may fail due to merge conflicts. In that case you have to resolve the merge conflicts in your local branch and then push another patch set. The steps are:
Rebase your local branch onto the latest state of
Resolve all conflicts
Commit your rebase work using the amend option
Push your change again to Gerrit for review
After this change a new patch set is created for the change. The new patch set has again to pass the code review. Submit the change again to apply it to your Git repository. For more problems with Gerrit see Section 10, “Typical problems in working with Gerrit”.
With this error message Gerrit rejects a push if the remote branch can’t be fast forwarded onto the pushed commit. This is the case if the pushed commit is not based on the current tip of the remote branch. See non-fast forward for a solution.
Gerrit rejects to push a commit if it contains the same Change-ID as a predecessor commit. You forgot to amend the existing commit. See squash commits first for a solution.
See Gerrit error message for more error messages and their solutions.
To use Gerrit in Eclipse, clone the repository as before and
your projects. By
default EGit creates a configuration that
branch to the remote master branch. To use
the configuration to push the local master to
After cloning the repository you can configure Gerrit in the Git repository view by right-clicking on the origin remote and selecting Gerrit Configuration.
You can see the Gerrit review notes in Eclipse. Select Notes. Here you see the data which was created by the Gerrit reviewer.on a commit in the History View. In the Commit Viewer you have an additional tab called
Several Eclipse.org projects use the Gerrit code review system. This makes it relatively simple to contribute a code change to the related Eclipse project.
You need to create an Eclipse.org user account to contribute to an Eclipse project. You also need to sign a contributor license agreement (CLA). With the CLA you confirm that you have the rights to contribute the code to Eclipse.org.
First step is to create a user via the following URL: Create a new Eclipse.org account.
Afterwards you need to sign the CLA for this new user. The Eclipse CLA FAQ describes the process and purpose of the CLA. At the end this document contains a link for signing the CLA. You find it under the following URL: Eclipse CLA FAQ.
The Eclipse Gerrit installation usually needs a few hours to recognize a new user and a new CLA. After creating both, please wait a bit before trying to push your contribution.
You need to upload your SSH key to the Gerrit installation to that you can push changes to Gerrit via SSH. For this open the following URL: Gerrit at Eclipse.
Login with your Eclipse Bugzilla account and password. Afterwards select Settings as highlighted in the following screenshot.
Select Profile and note down your user. This user is later required for the push configuration.
Upload your public SSH key to Gerrit to be able to push to it.
Eclipse allows you to create an SSH key via→ → → →
Once you have your user and CLA, you can clone the Eclipse.org repository of your choice. For example, the Eclipse platform UI repository is located on the following URL.
The username registration and CLA signing is not required for cloning the Eclipse repositories. They are only required for contributing a Gerrit review request.
You need to configure the push configuration to push to Gerrit. For this select your remote, right-click on it and select Gerrit configuration .
In the following dialog, enter your Gerrit user from before. Ensure to use the 29418 port and remove the "gitroot" String from the push-url. The following screenshot demonstrates that for the Eclipse platform UI Git repository.
For details on the configuration of Gerrit see Section 7, “Developer: clone repository and prepare for review”.
After you finished the configuration you can push to the Eclipse Gerrit review system. You need to sign off every commit. EGit simplifies that via the sign-of push button. The Add Change-Id push button allows you to include a Change-Id entry to the commit message. Both buttons are highlighted in the following screenshot.
To get picked up by Gerrit, the Change-Id must be in the last paragraph together with the rest of the footer. Do not separate it from the Signed-off-by message with a new-line character to avoid problems.
The update of the Gerrit review request is the same as described in the general section about the Gerrit usage in this tutorial. Especially follow the guideline to:
Deliver a patch as a single commit (you may want to squash your commits first), because each commit generates a separate change.
If you want to update a Gerrit review request, 'amend' the existing commit - this creates a new patch set in the previous change
You find all open Gerrit review under the following URL: https://git.eclipse.org/r/. Comments from everybody, also non-committers are welcome in Gerrit for review requests.
If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.