Copyright © 2012, 2014, 2013 Lars Vogel
|Revision 0.1- 2.3||13.05.2012 - 17.03.2014||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.
It is also commonplace to do an automated test build of the proposed merge using continuous integration tools like Jenkins or Hudson to check for compile time errors.
In general a structure code review process has the following advantages:
Early error detection: build problems are detected almost immediately by automatic preview integration test builds. Logical flaws can be spotted by the human reviewer before any code is merged.
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. This keeps code readable and easier to maintain.
Knowledge exchange: the code review process allows newcomers to see the code of other more experienced developers and to get instant 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 contributor 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 line changed.
Development takes place at the Gerrit project hosted by Google Code.
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.
It is still possible to bypass code review by pushing directly to /refs/heads if sufficient rights have been granted.
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 or rapid deployment. 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 on Linux based systems.
# 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
On Microsoft Windows based systems you need to invoke the
daemon directly. From a command shell switch to the folder
run the following command to start the server.
cd gerrit_site java -jar bin/gerrit.war daemon -d
This starts Gerrit.
To stop it again, kill the running process using
If something goes wrong, look into the
The local Gerrit configuration is stored in the
You require a valid Gerrit user to work with Gerrit.
In a Gerrit installation in which you are not the administrator, you ask the administrator to create a user for you, but in your test installation you create your own users.
Login to Gerrit via http://localhost:8080/login/. The first user to login automatically gets the administrator status.
If you want to use SSH you have to upload your SSH key. If you prefer to use HTTPS, skip this step and go to Section 4.3, “HTTPS setup”.
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
Since version 2.6.1 you can also click→ in the web interface.
The new project can be found in the Gerrit web interface under→ .
Select your project and
Push Merge Commit
for feature branches named
is something only trusted and experienced commiters should be allowed to do.
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.
and select that you want to clone an existing repository. Enter the
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 okay. 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 screenshot. 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 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.
The entry is initially set to
During the commit, this is replaced with an ID generated by the Git tooling.
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 or the filename link to see change changes introduced by the change. You can double-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. A -1 is cleared once a new patch set is uploaded while a -2 serves as a veto which is "sticky" and carried over to the next patch-set blocking it until revoked.
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 while amending the 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.
While a single developer with sufficient rights can give +2 and merge it right away, the four-eye principle, which requires that at least two developers review the change before it is applied to the code base, is considered best practice.
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 Ctrl+Space to select existing changes and create local branches for the change to test the changes in isolation. It is suggested to use the last five numbers from the Gerrit change preview URL to keep an overview.→ → . When working with many projects, it is often easier to right-click on the repository instead and access from there. You can use
The submit step 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 easiest way to do so is via thebutton in the Gerrit web interface. If you lack access permission, the manual steps are:
Rebase your local branch onto the latest state of
Resolve all conflicts
Commit them using→ .
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”.
You get this error message if you try to release a commit in Gerrit to the Git repository and the change would result in a non-fastword merge. The Gerrit service is typically configured with the setting to allow only fast-forward merges.
This is the case if the pushed commit is not based on current tip of the remote branch, e.g., origin/master if you develop on this branch
The solution is to rebase your commit onto
origin/master and to
update the Gerrit review.
See non-fast forward for details.
Another common problem is that you create a series of commits and one of the commits is rejected during review. In this case you cannot merge the other commits as they still have a dependency to the "bad" commit.
The solution is to reset your branch and cherrypick the good commits onto it.
Gerrit rejects to push a commit if it contains the same Change-ID as a predecessor commit. You forgot to amend the existing commit but used the same Gerrit Change-ID.
In this case you need to squash the commits.
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 connect with
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
This part of the tutorial has moved to Eclipse platform development.
Maintaining high quality free online tutorials is a lot of work. Please support free tutorials by donating or by reporting typos and factual errors.
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.