Gerrit - Quick Guide
Gerrit - Overview
Gerrit is a web based code review tool which is integrated with Git and built on top of Git version control system (helps developers to work together and maintain the history of their work). It allows to merge changes to Git repository when you are done with the code reviews.
Gerrit was developed by Shawn Pearce at Google which is written in Java, Servlet, GWT(Google Web Toolkit). The stable release of Gerrit is 2.12.2 and published on March 11, 2016 licensed under Apache License v2.
Why Use Gerrit?
Following are certain reasons, why you should use Gerrit.
You can easily find the error in the source code using Gerrit.
You can work with Gerrit, if you have regular Git client; no need to install any Gerrit
client.
Gerrit can be used as an intermediate between developers and git repositories.
Features of Gerrit
Gerrit is a free and an open source Git version control system.
The user interface of Gerrit is formed on Google Web Toolkit.
It is a lightweight framework for reviewing every commit.
Gerrit acts as a repository, which allows pushing the code and creates the review for your commit.
Advantages of Gerrit
Gerrit provides access control for Git repositories and web frontend for code review.
You can push the code without using additional command line tools.
Gerrit can allow or decline the permission on the repository level and down to the
branch level.
Gerrit is supported by Eclipse.
Disadvantages of Gerrit
Reviewing, verifying and resubmitting the code commits slows down the time to market.
Gerrit can work only with Git.
Gerrit is slow and it's not possible to change the sort order in which changes are
listed.
You need administrator rights to add repository on Gerrit.
Gerrit - Installation
Before you can use Gerrit, you have to install Git and perform some basic configuration changes. Following are the steps to install Git client on different platforms.
Installation of Git Client
Linux
You can install the Git on Linux by using the software package management tool. For instance, if you are using Fedora, you can use as −
sudo yum install git
If you are using Debian-based distribution such as Ubuntu, then use the following command −
sudo apt-get install git
Windows
You can install Git on Windows by downloading it from the Git website. Just go to msysgit.github.io link and click on the download button.
Mac
Git can be installed on Mac using the following command −
brew install git
Another way of installing Git is, by downloading it from Git website. Just go to Git install on Mac link, which will install Git for Mac platform.
Gerrit - Configure Git
Once you have installed Git, you need to customize the configuration variables to add your personal information. You can get and set the configuration variables by using Git tool called git config along with the -l option (this option provides the current configuration).
git config -l
When you run the above command, you will get the configuration variables as shown in the following image
You can change the customized information any time by using the commands again. In the next chapter, you will learn how to configure the user name and user Email by using git config command.
Gerrit - Set Your Username & Email
You can track each commit by setting name and email variables. The name variable specifies the name, while the email variable identifies the email address associated with Git commits. You can set these using the following commands −
git config --global user.email "your_email@mail.com"
git config --global user.name "your_name"
When you run the above commands, you will get the user name and email address as shown in the following image.
Gerrit - Generate New SSH Key
SSH stands for Secure Shell or sometimes Secure Socket Shell protocol used for accessing network services securely from a remote computer. You can set the SSH keys to provide a reliable connection between the computer and Gerrit.
You can check the existing SSH key on your local computer using the following command in Git Bash −
$ ls ~/.ssh
After clicking the enter button, you will see the existing SSH key as shown in the following image −
If you don't find any existing SSH key, then you need to create a new SSH key.
Generating New SSH Key
You can generate a new SSH key for authentication using the following command in Git Bash −
$ ssh-keygen -t rsa -C "your_email@mail.com"
If you already have a SSH key, then don't a generate new key, as they will be overwritten. You can use ssh-keygen command, only if you have installed Git with Git Bash.
When you run the above command, it will create 2 files in the ~/.ssh directory.
Gerrit - Add Your SSH Key
You can add SSH key to the ssh-agent on different platforms discussed further.
Linux
Use the following command on Linux system to add SSH key
cat /home/<local-user>/.ssh/id_rsa.pub
Windows
Open the GIT GUI and go to Help → Show SSH Key as shown in the following image.
Then, click the Copy To Clipboard button, to copy the key to the clipboard.
Mac
In Mac OS X, you can copy id_rsa.pub contents to the clipboard using the following command.
$ pbcopy < ~/.ssh/id_rsa.pub
Gerrit - Add SSH Key to your Gerrit Account
SSH key can be added to the Gerrit account using the following steps −
Step 3 − Then in the top right corner, click your username and select the Settings option.
Here, we have created an account with the name John to make use of Gerrit
Step 4 − Click the "SSH Public keys" option on the left-side menu and paste the SSH Public key in the field.
Gerrit - Add SSH Key to use with Git
You can add SSH key to Git using the following commands −
$ eval 'ssh-agent'
$ ssh-add ~/.ssh/id_rsa
$ ssh -p 29418 <user_name>@gerrit.wikimedia.org
In the above screenshot, you can see that xyz123 is a instance shell account name, which is used while creating Gerrit account and Abc123 is a user name of your Gerrit account.
Gerrit - Download Examples Using Git
You can download the example using Git along with the source code of any project organized at gerrit.wikimedia.org using the following Git Bash command.
$ git clone
ssh://<user_name>@gerrit.wikimedia.org:29418/mediawiki/extensions/examples
The git clone command clones a directory into a new directory; in other words gets a copy of an existing repository. When you run the above command, you will get a screenshot similar to the following.
The above command clones the 'examples' repository and receives the objects, files, etc. from that repository and stores it in your local branch.
Gerrit - Installing Git-Review
You can work with Gerrit by installing git-review on different platforms as discussed in this chapter.
Windows
In Windows, you can install the git-review as listed in the following steps.
Step 1 − First install Python for installing git-review.
Step 2 − Keep the Python installation in the default directory (like C:\Python27) instead of installing in any other directory.
Step 3 − Next, set the environment variables for Python scripts directory using the path as C:\Python27\;C:\Python27\Scripts\;
git_review_install
Step 4 − With version 2.7, Python will install pip automatically. For older version of Python 2.7, you can install pip as described in this link.
Step 5 − Run open Git Bash and install the git-review using the following command.
$ pip install git-review
Linux
In Linux, you can install git-review as described in the following steps −
Step 1 Users of Linux platform do not have root access on shared host. Hence, without root access, you can install git-review locally in user directory using the following commands −
virtualenv --python=/usr/bin/python2.6 virtualenv
virtualenv/bin/pip install git-review==1.21
Step 2 − You can extend the path to the local binaries using two ways −
PATH=$PATH:~/virtualenv/bin/
PATH=~/virtualenv/bin/:$PATH
Step 3 − Now, use the following command to set up the work with Gerrit.
git review -s
or
~/virtualenv/bin/git-review -s
Step 4 − With root access, git-review can be installed using the following command.
sudo apt-get install git-review
Step 5 − If there is no apt-get after installing Python, then use the following commands.
$ sudo easy_install pip
$ sudo pip install git-review==1.21
Step 6 − Run the following command to work with Gerrit.
git review -s
Mac OS X
In Mac, you can install the git-review using the following steps.
Step 1 − Install the Homebrew from this link.
Step 2 − Next, install the git-review using the following command.
brew install git-review
Gerrit - Configuring Git-Review
Gerrit is built on top of Git version control system, which extracts the code from other host, pushing changes to the code, submitting the code for review, etc. The default remote name of Git is origin and we tell git-review to use this name 'origin' by using the following command.
$ git config --global gitreview.remote origin
Gerrit - Setting Up Git-Review
Git-review can be used to send git branches to Gerrit for reviewing. You can set up gitreview using the following command in the project directory.
$ git review -s
Git-review can be used as the command line tool for configuring Git clone, submitting the branches to Gerrit, fetching the existing files, etc. Git-review looks for the remote named gerrit for working with Gerrit by default.
If git-review finds the Gerrit remote, then it will submit the branch to HEAD:refs/for/master at the remote location and if there is no Gerrit remote access, then git-review looks for the .gitreview file at the root of the repository along with the gerrit remote information.
Git-review processes the following internally −
It will check whether the remote repository works or not for submitting the branches.
If there is no Gerrit remote access, then it will ask for the username and try to access the repository again.
It will create a remote access called gerrit that points to Gerrit.
It will install the commit-msg hook.
Gerrit - Update Master
You can make the master branch up-to-date using the following command. The git-pull command fetches from another local branch or integrates with another repository.
git pull origin master
The command will pull changes from the origin remote (URL of remote to fetch from), master branch and merge the changes to local checked-out branch.
The origin master is a cached copy of the last pulled from the origin.
Git pull is a combination of git fetch (fetches new commits from the remote repository) and git merge (integrates new commits into local branch).
Git pull merges the local branch with the remote branch by default.
Gerrit - Create a Branch
You can create a branch on the local machine using the following command.
$ git checkout -b name_of_branch origin/master
The above command creates a new branch as shown in the following screenshot.
Here, we have used branch123 as the new local branch. You can show the new branch from the 'master' using the following command.
$ git branch
The above command produces the result as shown in the following screenshot.
Git checkout navigates between the branch, updates the files in the working directory, and informs Git to record the commits on that branch.
Gerrit - Make & Commit Your Change
When you modify the code in the local file system, you can check for the changes within the directory using the following command.
$ git diff
In the project directory, we will modify some changes in the file called Example/Example.hooks.php and run the above command. We will get the result as shown in the following screenshot.
You can check the changes made to the files or the directory using the following command.
$ git status
The above command allows to see which changes have been staged, which have not, and which files are not tracked by Git.
Next, you can add the changes in the working directory and update the file in the next commit using following command.
$ git add Example/Example.hooks.php
After adding the file, again run the git status command to review the changes added to the staging area as shown in the following screenshot.
You can see the difference between the index and your last commit, and what contents have been staged, using the following command.
$ git diff --cached
You can push the changes to the remote directory from the local repository using the following command.
$ git commit
When you run the above command, it will ask to add the commit message for your changes. This message will be seen by other people when you push the commit to the other repository.
Add the commit message and run the command again as git commit, which will display the commit message as shown in the following screenshot.
Gerrit - Prepare Push Change Set to Gerrit
You need to review the changes in Gerrit before merging them into the master. The changes can be synchronized that have occurred in the master. Use the following command within the branch that you have been working on.
$ git pull --rebase origin master
The above command will fetch the changes or commits from the remote branch and rebase the commits on top of the master.
When you are done with the changes and rebased the commits, you can push your change set to Gerrit for review.
Git pull --rebase is often used when changes do not deserve a separate branch.
Git pull is a combination of git fetch and git merge; where as git pull --rebase is a combination of git fetch and git rebase.
First, run the command as git pull origin master as shown in the following screenshot.
Now use the command as git rebase master to rebase the commits as shown in the following screenshot.
Gerrit - Push Your Change Set to Gerrit
You can submit the patches for review by using the git-review command. The change set can be pushed to Gerrit, by running the git review -R command as shown in the following screenshot.
The -R option informs git-review not to complete rebase before submitting git changes to Gerrit.
You can submit the code to other branch rather than the master, using the following command.
git review name_of_branch
It is also possible to submit the code to a different remote, using the following command.
git review -r name_of_remote
Gerrit - View the Change / Next Steps
The changes can be viewed in Gerrit dashboard by clicking in this link.
Click the modified author name link, and you will get the following screenshot.
Click the diffusion link to see the changed files with other details as shown in the following screenshot.
Gerrit - Editing via the Web-Interface
You can edit the project via the web interface after logging in to the Gerrit account as shown in the following steps.
Step 1 − Go to Gerrit dashboard by clicking this link. You will get the following screenshot.
Step 2 − Next click the mediawiki/extensions/examples link specified under Project column.
Step 3 − Click the General link in the toolbar as shown in the following screenshot.
Step 4 − When you open the General link, it will show a screenshot as the following.
Step 5 − Click the Create Change button and it will open a popup window with some details as shown in the following screenshot.
Step 6 − Enter the information and click the Create button.
After creating the change, it will display the information as shown in the following screenshot.
Step 7 − Click Edit and then click Add. Now select the file you want to edit. Here we have selected the file Example/i18n/en.json.
When you open the file, it will show the json data as specified in the following screenshot.
Step 8 − Click Save and then click the Close button.
Step 9 − Finally click the Publish button to publish the edited file
Step 10 − You can change commit message by clicking the Commit Message link as shown in the following screenshot.
Step 11 − Press e on the keyboard and add some extra information, if you wish to Click Save and then click the Close button.
Gerrit - Review before Merge
Code review is an important part of the workflow in Gerrit. The basic concept is that the code must be reviewed before being merged.
The workflow of the code for MediaWiki can be reviewed before merging it and also extensions can be reviewed which customizes the MediaWiki looks and works. There is one special case in which you can push the internationalization and localization commits.
You can push all the commits to a remote branch when you finish the development. Someone will fetch the changes into local and merge those fetched changes into the local master by creating merge commit. You can push these changes to refs/for/master.
Gerrit - Project Owners
Project owner means that the project belongs to the person mentioned. Project owners is a virtual group in which you cannot add members or other groups in it. The project owner provides access rights to allow permission on the project to different groups.
You can view the access rights of your project using the following steps.
Step 1 − Open Gerrit dashboard by clicking this link.
Step 2 − Click Projects → List option. Search the project in your project list and click it as shown in the following screenshot.
Step 3 − When you open your project, click the Access option as shown in the following screenshot.
Step 4 − Click the edit option. You can change the access rights by clicking the dropdown menu. Click the Save Changes button as shown in the following screenshot.
How to Comment, Review, and Merge
Anyone can review the code and comment on the code in Gerrit. Consider the following steps −
Step 1 − Login to Gerrit to open the Gerrit dashboard as specified in the previous chapter.
Step 2 − Now, click any subject which contains Gerrit project, branch, updated date, etc. as shown in the following screenshot.
Step 3 − Next, it will display a screen. Click the Commit Message option as shown in the following screenshot.
The important fields of the change set are like Reviewers, Add Reviewer, Side-by-side off, etc. Comparing patch sets includes selecting the old version history list, expanding the newer patch set details, etc. Reviewing and merging or rejecting the code includes abandon change button, submitting patch button, etc. which are not present in the current version of Gerrit.
