Support free tutorials:











vogella training Training Books



Gerrit code review - Tutorial

Lars Vogel

Version 2.3

17.03.2014

Revision History
Revision 0.1- 2.3 13.05.2012 - 17.03.2014 Lars
Vogel
bug fixes and improvements

Gerrit tutorial

This tutorial explains the usage of the Gerrit code review system. It describes the setup of Eclipse (with EGit) as well as the command line setup. Contributing to an Eclipse.org project via Gerrit is also described.


Table of Contents

1. Code review
1.1. The code review process
1.2. Advantages of code review
2. The Gerrit code review system
2.1. What is Gerrit?
2.2. How does Gerrit work?
2.3. Gerrit online documentation
3. Installation of Gerrit
3.1. Download Gerrit
3.2. Setup of Gerrit
4. User setup
4.1. Create user
4.2. SSH setup
4.3. HTTPS setup
4.4. Activate new change screen
5. Administrator: upload Git repository
6. Administrator: create example project
7. Developer: clone repository and prepare for review
8. Developer: Creating and updating a Gerrit change request
9. Webreview with Gerrit
9.1. Reviewing a change request
9.2. Publishing your review result
9.3. Keyboard shortcuts
9.4. Getting the change
9.5. Handling merge conflicts
10. Typical problems in working with Gerrit
10.1. non-fast forward
10.2. Remove a commit
10.3. squash commits first
10.4. more error messages
11. Gerrit integration into Eclipse
11.1. Gerrit support in Eclipse
11.2. Mylyn Gerrit
12. Contributing to Eclipse via Gerrit
13. Support free vogella tutorials
13.1. Thank you
13.2. Questions and Discussion
14. Links and Literature

1. Code review

1.1. The code review process

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.

1.2. Advantages of code review

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.

2. The Gerrit code review system

2.1. What is Gerrit?

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.

2.2. How does Gerrit work?

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.

2.3. Gerrit online documentation

You find detailed information about Gerrit at: Gerrit Code Review - A Quick Introduction.

Eclipse specific information can be found on the Gerrit at Eclipse webpage.

3. Installation of Gerrit

3.1. Download Gerrit

Download the latest Gerrit release from Gerrit download page. The download is a .war file which you can directly add to your servlet container, for example, a Jetty or Tomcat installation.

The .war file also contains a Jetty web server and can be started directly for testing or rapid deployment. The following description uses this approach.

3.2. Setup of Gerrit

Copy the .war file into an empty directory.

Switch on the command line to the location of the directory to which you extracted the .war file. Install and start Gerrit with 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 the -d 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

Option Description
Location of Git repositories Location of Git repositories, default is the git directory in the installation folder of your Gerrit installation.
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.


Tip

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 gerrit_site and 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 Ctrl+C If something goes wrong, look into the logs folder.

Tip

The local Gerrit configuration is stored in the ./review_site/etc/ folder.

4. User setup

4.1. Create user

You require a valid Gerrit user to work with Gerrit.

Tip

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.

4.2. SSH setup

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.

Settings in Gerrit

SSH public key setting in Gerrit

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.

SSH public key setting in Gerrit

4.3. HTTPS setup

You can also enter a password for HTTPS access.

HTTP user setup

4.4. Activate new change screen

SSH public key setting in Gerrit

5. Administrator: upload Git repository

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 ProjectsCreate New Project in the web interface.

The new project can be found in the Gerrit web interface under ProjectsList.

Viewing the list of Gerrit repositoriesRemote

Select your project and Access. 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. Especially the access right Push Merge Commit for feature branches named refs/for/refs/heads/* is something only trusted and experienced commiters should be allowed to do.

Viewing the list of Gerrit repositories

6. Administrator: create example project

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.

Note

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 TeamRemotePush. Enter the following URL ssh://<userid>@localhost:29418/demo/gerrittest.git in the wizard and press the Next button.

Initial push to Gerrit

On the next page, click the Add All Branches Spec button.

Initial push to Gerrit

Press the Next button and on the last wizard page the Finish button.

7. Developer: clone repository and prepare for review

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

Configure a remote for Gerrit

The default values in this dialog should be okay. Press the finish button.

Configure a remote for Gerrit

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.

Tip

Use the Properties view on your repository to see the details of your repository configuration.

Gerrit remote configuration

Tip

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.

Tip

You can also do this setup directly via the Git command line.

git config remote.origin.push refs/heads/*:refs/for/* 

8. Developer: Creating and updating a Gerrit change request

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 .

Create change request

Note

The Change-ID is what uniquely identifies the change in Gerrit. The entry is initially set to Change-Id: I0000000000000000000000000000000000000000. 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.

Review Gerrit change request

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.

9. Webreview with Gerrit

9.1. Reviewing a change 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.

Web review

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.

Web review

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.

9.2. Publishing your review result

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.

Web review

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.

Tip

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.

Patch set comparision view

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.

Web review

Tip

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.

9.3. Keyboard shortcuts

Press ? in the Gerrit web user interface to see the actions you can trigger via shortcuts.

Gerrit shortcuts

9.4. Getting the change

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.

Pulling in the change

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.

Tip

EGit allows to fetch a change from Gerrit. For this, right-click on the project TeamRemoteFetch from Gerrit. When working with many projects, it is often easier to right-click on the repository instead and access Fetch from Gerrit from there. You can use 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.

Pulling in the change

9.5. Handling merge conflicts

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 the Rebase button in the Gerrit web interface. If you lack access permission, the manual steps are:

  • Rebase your local branch onto the latest state of origin/master

  • Resolve all conflicts

  • Commit them using RebaseContinue.

  • 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”.

10. Typical problems in working with Gerrit

10.1. non-fast forward

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

Non-fast forward

The solution is to rebase your commit onto origin/master and to update the Gerrit review.

Rebase as solution

See non-fast forward for details.

10.2. Remove a commit

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.

Non-fast forward

Non-fast forward

The solution is to reset your branch and cherrypick the good commits onto it.

Rebase as solution

10.3. squash commits first

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.

Rebase as solution

In this case you need to squash the commits.

Rebase as solution

See squash commits first for a solution.

10.4. more error messages

See Gerrit error message for more error messages and their solutions.

11. Gerrit integration into Eclipse

11.1. Gerrit support in Eclipse

To use Gerrit in Eclipse, clone the repository as before and import your projects. By default EGit creates a configuration that pushes the local master branch to the remote master branch. To connect with Gerrit, change the configuration to push the local master to refs/for/master instead.

After cloning the repository you can configure Gerrit in the Git repository view by right-clicking on the origin remote and selecting Gerrit Configuration.

Gerrit configuration in the Git repository view

You can see the Gerrit review notes in Eclipse. Select Open in Commit Viewer on a commit in the History View. In the Commit Viewer you have an additional tab called Notes. Here you see the data which was created by the Gerrit reviewer.

11.2. Mylyn Gerrit

Mylyn provides an Gerrit connector for the Eclipse IDE.

To use it, install the Mylyn Reviews Connector: Gerrit from the Eclipse Juno update site. This plug-in allows you to create queries for Gerrit reviews.

12. Contributing to Eclipse via Gerrit

This part of the tutorial has moved to Eclipse platform development.

13. Support free vogella tutorials

Maintaining high quality free online tutorials is a lot of work. Please support free tutorials by donating or by reporting typos and factual errors.

13.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

13.2. Questions and Discussion

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.

14. Links and Literature

Git homepage

EGit - Teamprovider for Eclipse

Setting up Gerrit and Jenkins from Alex Blewitt

Contributing to Eclipse via Gerrit