Site Tools


How to use IoTivity Gerrit

Gerrit is a web-based code review tool built to work together with the git version control system. Gerrit offers side-by-side difference viewing and inline commenting to make the mechanics of code reviewing painless. The basic concept is you make changes to a local branch and git push the commits to the iotivity repository. Gerrit intercepts these changes and turns them into a review page, giving you back a link to a web page. From here you can request reviews, as well as request the Jenkins autobuild system to build with your change applied - normally reviewers will want to see that your commit will apply before approving it.


Configure ssh access

Step 1: Create SSH keys

If you don't already have an ssh keypair, create one. On a Linux system, this command from a shell will do it:

$ ssh-keygen -t rsa -C "Your name <your_email_address>"

Example for John Doe:

$ ssh-keygen -t rsa -C "John Doe"

After pressing the Enter key at several prompts, an ssh key-pair will be created in ~/.ssh as id_rsa and

Step 2: Setting up SSH

Edit ~/.ssh/config using your favorite text editor and add these lines:

    Hostname ""
    IdentityFile ~/.ssh/id_rsa
    User <Linux Foundation ID>
    Port 29418

If you are lucky enough to be working from a location that does not need a proxy, this should be enough. If you are inside a corporate network, a proxy is very likely to be needed. The details of what will work are likely to vary, but using netcat (command named nc or connect has worked for many. Here are a couple of examples for adding to the stanza for the gerrit server:

ProxyCommand nc -X5 -x <proxy-address>:<port> %h %p
ProxyCommand connect -S <proxy-address>:<port> %h %p
Step 3: Upload SSH public key to Gerrit and Register personal info

Log in to IoTivity Gerrit

Upload SSH pubkey to Gerrit

Settings (top right) --> SSH Public Keys --> Add Key...

Paste your SSH public key there, then click 'Add'. In the Gerrit UI, you can also register your email address and update your full name:

Settings --> Contact Information --> Register New Email...
Settings --> Contact Information --> Full Name..

After you register the email, you will receive an email which contains an activation link. Please copy the link to your browser to activate the account.

Step 4: Verify your SSH connection

You can verify your Gerrit connection by executing this command:

$ ssh

If your settings are correct, you will see the message beginning with the below (and then telling you how to proceed). If not, check SSH proxy and SSH public key on Gerrit.

****    Welcome to Gerrit Code Review    ****

Configure Git for Gerrit Access

Once you have configured your information with Gerrit, you need at a minimum to configure your local git.

$ git config --global "First_Name Last_Name"
$ git config --global "account@host"

For example:

$ git config --global "John Doe"
$ git config --global ""

Note: It is recommended that you use the same email address you used for your Gerrit account for the “” setting. Make sure you have developer access first.

Cloning Project Source

The list of IoTivty projects is found on the Projects and Functions page. Please read and remeber where to find this page: to get a change approved, you will have to get the appropriate maintainer/sub-maintainer to vote +2 on it, which means you need to know who to invite to review.

The project list is also available by query:

$ ssh gerrit ls-projects | grep <Gerrit_Project>

Clone the required package by executing the following command:

$ git clone ssh://<Gerrit_Project>

An example is shown below:

$ git clone ssh://

You will need to install an IoTivity-specific commit hook in your local git tree. This hook generates a ``Change-Id`` line whenever you commit a change. Gerrit tracks submissions by ``Change-Id`` so this is mandatory. Note this is placed in your working tree so only applies to activity on this tree, not all git operations.

$ cd iotivity
$ scp .git/hooks/

If you cloned a project without supplying additional options, you just have the master branch tracking upstream. You will probably want to also track the current release branch. This is a one-time setup, git has many ways to get there but here is one example:

$ git checkout --track origin/1.3-rel

Important Gerrit Operations

Submit a patch for review

See the page on submitting changes to Gerrit.

Pull a patch from Gerrit

If you want to pull a patch from Gerrit, perhaps to verify it, or modify and resubmit, Gerrit will simplify things by showing what you need.

  • Copy the command to download the patch of interest from the Gerrit review page.
  • Paste the command into command line.

Note: sometimes you may get an error that looks like:

ssh: connect to host port 29418: Bad file number fatal: Could not read from remote repository.

Please make sure you have the correct access rights and that the repository exists.

Reviewing Patches on Gerrit


Watch a project

If you are interested in a package that has an important relation to yours, like a dependency, then you can watch those projects. You will receive a notification when a patchset is uploaded to Gerrit. Adjust the Watched Projects settings to monitor projects.

Settings (top right) --> Watched Projects --> input Project Name -> click 'Watch'

You can restrict to certain files only in a given project by providing a regular expression match in the “Only If” field. Example:

file:^examples/.* OR file:^ocsdk/occoap/.* OR file:^.*/SConscript$
Replace a Patch Set

To add a new patch set that replaces an existing patch set with an updated version of the same logical modification, send the new commit to the same branch the previous one was sent to. The command is the same as described above for the initial push. Make sure the Commit-id has not changed. If you have worked in a local branch, and kept it after pushing, you should be able to update your patch set by editing, running ``git add`` to add the changed files, then ``git commit –amend`` to update your change, before pushing.

Rebase a Patch set

It frequently happens that while your patch is being reviewed, other changes are accepted to the target branch which would cause a merge problem with your patch. Gerrit will often detect this, and in the web interface show you a message in red, “cannot merge”. If you manually go through the steps to merge, the merge will become a new commit, and the commit ID will change. Since Gerrit works off the commit ID, if you push this, it will look like a new change. In order to avoid this, you can rebase instead, and follow the instructions in the previous step. Gerrit also has a button in the web interface to attempt a rebase, which if it works, is perhaps easier than fiddling manually - but then the local branch containing your work will also need to be updated. If there are any conflicts needing manual resolution, the Gerrit function will quit and you should rebase yourself.

Command Line Tools

A number of Gerrit commands can be sent through ssh. The Review command is of particular interest:

ssh -p <port> <host> gerrit review [--message <MESSAGE>] [--verified <N>] [--code-review <N>] [--abandon] {COMMIT | CHANGEID,PATCHSET}...

The Gerrit documentation site has detailed documentation on "gerrit review". The full set of gerrit commands is also available.

There is is also a tool developed for the OpenStack project called git-review which attempts a nicer interface to working with gerrit than issuing ssh commands. TODO: add some examples.

Patch Reviewing

You can review patch sets by using the command line, for example, to verify, approve, and submit the patch c0ff33:

$ ssh gerrit review --verified=+1 --code-review=+2 --submit -m "Comment" c0ff33

Please use the web interface instead if you have line-by-line comments.

Abandon a Patch

To drop an uploaded patch, just click the Abandon button in the Gerrit Web UI or use the command line interface as in this example:

$ ssh gerrit review –abandon -m “Explanation for abandoning” c0ff33

More detailed instructions

Gerrit has a documentation tab in the web UI, and a '–help' command from the command line:

$ ssh gerrit --help
how_to_use_gerrit.txt · Last modified: 2017/12/08 16:04 by mwichmann