# Gerrit Code Review Cheatsheet

## Install the commit-msg hook in your repository

    scp -p -P 29418 username@git.eclipse.org:hooks/commit-msg .git/hooks/

This will ask for a password. It is the password that you have to generate in the SSH Keys section of settings in your Gerrit account.

You can alternatively download the file. The hook helps append a Change-Id to your commit message.

EGit can also generate a Gerrit Change-Id into your commit message both manually or in an automated way.

## To create a new change

- JGit

    git push ssh://username@git.eclipse.org:29418/jgit/jgit.git HEAD:refs/for/master

- EGit

    git push ssh://username@git.eclipse.org:29418/egit/egit.git HEAD:refs/for/master

Or, if you've followed the instructions on Adding_a_dedicated_remote you can simply do:

    git push review

Since the current repository has the right definition for 'review', you won't need to remember the canonical push URL

## To update an existing change with a new commit

    git push ssh://username@git.eclipse.org:29418/egit/egit.git HEAD:refs/for/master

This works because Gerrit links the new commit to the prior change based upon the Change-Id footer in the commit message. (This is automatically generated by the commit-msg hook you installed above.) If you refuse to use the commit-msg hook, or don't have a Change-Id footer, you should read the Gerrit documentation on change-id lines and replacing changes.

Note: To be picked up by Gerrit, a Change-Id line must be in the bottom portion (last paragraph) of a commit message, and may be mixed together with the Signed-off-by, Acked-by, or other such footers. So if your Change-Id line is ignored it's probably not in the last paragraph :).

## To compare bulk diffs using Git

Since each Gerrit review patchset actually commits its own tree, you can pull out the trees and compare them.

If you've got a large changeset, and you want to be able to do diffs between them via (command line) git instead of browsing on the web, then you can fetch the individual changes and then perform a diff. For example, http://git.eclipse.org/r/2 shows the 'download' section for each patchset. In this case, it looks like:

- Patch Set 1 `git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/1 (1d3331a91bd477d3f70cde9613576cf9688ac358)`
- Patch Set 2 `git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/2 (13ab9a43d4d512963556a92e889b1204d32f8e68)`
- Patch Set 3 `git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/3 (d14cc645655683ba3e30a35833fb2282142e898f)`
- Patch Set 4 `git pull ssh://username@git.eclipse.org/jgit refs/changes/02/2/4 (43de8d385b614c72fd796e17da75d381f6e0cc25)`

Performing a `git pull` will both get the bits and merge them into your tree, which won't do what you want for comparison. So, in order to get the bits (but not merge), you need to do a `git fetch` instead. Let's say we want to diff the last two patches against each other rather than reviewing the entire patchset again:

    git fetch ssh://username@git.eclipse.org/jgit refs/changes/02/2/3
    git fetch ssh://username@git.eclipse.org/jgit refs/changes/02/2/4

    git diff d14cc645655683ba3e30a35833fb2282142e898f 43de8d385b614c72fd796e17da75d381f6e0cc25

    # or git diff d14cc6 43de8d

If you're doing this from within an already checked out project, you can do `git fetch origin` (or any other remote name in `.git/config}`.

Git fetched data will stay around in your repository, but will be 'orphaned' if no references point to it. To clean up, you can run `git gc` or wait until this happens automatically.

## To trigger Hudson build for a change

We have build jobs jgit.gerrit on https://hudson.eclipse.org/jgit/, and egit.gerrit and egit-github.gerrit on https://hudson.eclipse.org/egit/ which are triggered automatically when a new change or a new patchset for an existing change is pushed for review. These jobs will comment on the respective change when the build is started and when it's finished and vote on the change according to the build and test results.

Sometimes you may want to retrigger such a build e.g. because it may have failed due to some temporary problem. Committers can manually trigger these jobs in the following way:

- Go to Trigger a Gerrit event manually page
- Search for a change you'd like to build
- Select the patch set(s) you want to trigger
- Press Trigger Selected button

If you are not a committer and need to retrigger a build ask for that on the mailing list.

## To approve a change

- Click on Publish Comments
- Vote with the radio buttons

## To add a reviewer

Once you've pushed your commit to Gerrit for review, you can go to the web page ( https://git.eclipse.org/r/) and see your changes. By clicking on the review, there's an option to add a reviewer by e-mail address; they'll then be sent a message indicating that they'd like your review on the item.

It's usually not necessary to add any reviewers, it should be reviewed by the committers sooner or later. If this hasn't happened, you can look for people that did changes in the same area and add them as reviewers. It's also ok to comment on a change to "bump" its visibility.

## Code Review

The code review category indicates your opinion on the quality of the code, and how well it fits within the purpose of the existing surrounding code. A +2 vote from any committer is required before submission can occur. A -2 vote from any committer will block submission.

## IP Review

The IP review category indicates whether or not the change has been properly logged under the Eclipse IP Process. Under that process, any committer should mark his/her change +1 if they were the sole author of the change. For any other change, a committer should only mark +1 after ensuring the Legal Paperwork has been done. A +1 vote is required to submit a change, while a -1 vote will block submission.

## Submission Guidelines

We strive to use Gerrit to improve our understanding of the code base and improve quality.

In order to ensure a proper review happens, some simple guidelines should be followed:

- vote 0/-1 for not-ready-to-submit (AKA WIP) own proposals, +1 otherwise;
- If a changeset is not-ready-to-submit, please put [RFC] or [DRAFT] in the message to let people know
- let non-trivial changes be in review for at least 24 hours
- if you want your changeset reviewed by someone, please add them as a reviewer

## Tips & Tricks

### Class Loading Issues

If you encounter strange class loading issues during runtime (e.g. on UI test executions) the following might help:

Enable tracing in your launch configuration to get information how imported packages are resolved at runtime. Select the Tracing tab in your launch configuration, select "Enable tracing", select plug-in org.eclipse.osgi, select category resolver/wiring on the right side.

Category:Draft_Documentation