Review UI

Reviewing changes is an important task and the Gerrit Web UI provides many functionalities to make the review process comfortable and efficient.

The UI has three different main views,

The dashboard, which shows all changes that are relevant to you
The change screen, which shows the change with all its metadata
The diff view, which shows changes to a single file

Change Screen

The change screen shows the details of a single change and provides various actions on it.

Here are the main areas of the screen

Top info

Top left, you find the status of the change, and a permalink.

The change status shows the state of the change:

Active:

The change is under active review.
Merge Conflict:

The change can’t be merged due to conflicts.
Ready to Submit:

The change has all necessary approvals and may be submitted.
Merged:

The change was successfully merged into the destination branch.
Abandoned:

The change was abandoned.

Star Change

Clicking the star icon marks the change as a favorite: it turns on email notifications for this change, and the change is added to the list under Your > Starred Changes. They can be queried by the is:starred search operator.

Change metadata

The change metadata block contains detailed information about the change and offers actions on the change.

Reviewers:

The reviewers of the change are displayed as chips.

For each reviewer there is a tooltip that shows on which labels the reviewer is allowed to vote.

New reviewers can be added by clicking on the pencil icon. Typing into the pop-up text field activates auto completion of user and group names.

Reviewers can be removed from the change by clicking on the x icon in the reviewer’s chip token. Removing a reviewer also removes the current votes of the reviewer. The removal of votes is recorded as a message on the change.

Removing reviewers is protected by permissions:
- Users can always remove themselves.
- The change owner may remove any zero or positive score.
- Users with the Remove Reviewer access right, the branch owner, the project owner and Gerrit administrators may remove anyone.
Project / Branch / Topic:

The name of the project for which the change was done is displayed as a link to the default dashboard of the project. If no default dashboard is defined, the link opens a list of open changes on the project.

The name of the destination branch is displayed as a link to a list with all changes on this branch that have the same status as the currently viewed change.

If a topic was assigned to the change it is displayed below the branch. By clicking on the edit icon the topic can be set. This requires the Edit Topic Name access right. To be able to set a topic on a closed change, the Edit Topic Name must be assigned with the force flag.
Submit Strategy:

The submit strategy that will be used to submit the change. The submit strategy is only displayed for open changes.
Actions:

Actions buttons are at the top, and in the overflow menu. Depending on the change state and the permissions of the user, different actions are available on the change:
- Submit:
  
  Submits the change and adds it to the merge queue. If possible the change is merged into the destination branch.
  
  The Submit button is available if the change is submittable and the Submit access right is assigned.
- Revert:
  
  Reverts the change via creating a new one.
  
  The Revert button is available if the change has been submitted.
  
  When the Revert button is pressed, a panel will appear to allow the user to enter a commit message for the reverting change.
  
  Once a revert change is created, the original author and any reviewers of the original change are added as reviewers and a message is posted to the original change linking to the revert.
- Abandon:
  
  Abandons the change.
  
  The Abandon button is only available if the change is open and the Abandon access right is assigned.
  
  When a change is abandoned, a panel appears that allows one to type a comment message to explain why the change is being abandoned.
- Restore:
  
  Restores the change.
  
  The Restore button is only available if the change is abandoned and the Abandon and the Push access right is assigned.
  
  When a change is restored, a panel appears that allows one to type a comment message to explain why the change is being restored.
- Rebase:
  
  Rebases the change. The rebase is always done with content merge enabled. If the rebase is successful a new patch set with the rebased commit is created. If the rebase fails, there are conflicts that have to be resolved manually.
  
  If the change does not depend on another open change, it is rebased onto the tip of the destination branch.
  
  If the change depends on another open change, it is rebased onto the current patch set of that other change.
  
  It is possible to change parent revision of a change. The new parent revision can be another change towards the same target branch, or the tip of the target branch.
  
  The Rebase button is only available if the Rebase access right is assigned. Rebasing merge commits is not supported.
- Cherry-Pick:
  
  Allows to cherry-pick the change to another branch. The destination branch can be selected from a dialog. Cherry-picking a change creates a new open change on the selected destination branch.
  
  It is also possible to cherry-pick a change to the same branch. This is effectively the same as rebasing it to the current tip of the destination branch. This can be used to remove dependencies on other open changes.
  
  Users can only cherry-pick changes to branches for which they are allowed to upload changes for review.
- Delete Change / Delete Revision:
  
  Deletes the change.
  
  For open or abandoned changes, the Delete Change button will be available and if the user is the change owner and is granted the Delete Own Changes permission, if they are granted the Delete Changes permission, or if they are an administrator.
- Further actions may be available if plugins are installed.
Labels & Votes:

Approving votes are colored green; negative votes are colored red.

File List

The file list shows the files that are modified in the currently viewed patch set.

In addition to the modified files the file list contains magic files that are generated by Gerrit and which don’t exist in the repository. The magic files contain additional commit data that should be reviewable and allow users to comment on this data. The magic files are always listed first. The following magic files exist:

Commit Message:

The commit message and headers with the parent commit(s), the author information and the committer information.
Merge List (for merge commits only):

The list of commits that are being integrated into the destination branch by submitting the merge commit.

Patch Sets

The change screen only presents one patch set at a time. Which patch set is currently viewed can be seen from the Patch Sets drop-down panel in the change header.

Download

The Download drop-down panel in the change header offers commands and links for downloading the currently viewed patch set.

The available download commands depend on the installed Gerrit plugins. The most popular plugin for download commands, the download-commands plugin, provides commands to checkout, pull and cherry-pick a patch set.

Each command has a copy-to-clipboard icon that allows the command to be copied into the clipboard. This makes it easy to paste and execute the command on a Git command line.

If several download schemes are configured on the server (e.g. SSH and HTTP) there is a drop-down list to switch between the download schemes. Gerrit automatically remembers the download scheme that was last chosen and selects this download scheme the next time the download commands drop-down panel is opened.

The Patch-File links provide the Git patch file for the currently viewed patch set for download. The patch file can be base64 encoded or zipped.

The Archive links allow one to download an archive with the contents of the currently viewed patch set. The archive is offered in several formats (e.g. tar and tbz2); which formats are available depends on the configuration of the server.

Included In

For merged changes the Included In drop-down panel is available through the overflow menu at the top. It shows the branches and tags in which the change is included. E.g. if a change fixes a bug, this shows which released versions contain the bug-fix (assuming that every release is tagged).

If there are changes that are related to the currently viewed change they are displayed in the third column of the change screen.

There are several lists of related changes and a tab control is used to display each list of related changes in its own tab.

The following tabs may be displayed:

Related Changes:

This tab page shows changes on which the current change depends (ancestors) and open changes that depend on the current change (descendants). For merge commits it also shows the closed changes that will be merged into the destination branch by submitting the merge commit.

The changes are sorted in the same way as the output of 'git log'. This means the relationship between the changes can be inferred from the position of the changes in the list. Changes listed above the current change are descendants; changes below the current change are ancestors.

For merged changes this tab is only shown if there are open descendants.

Related changes may be annotated with dependencies on outdated patch sets, or commits that are not associated to changes under review:
- Not current:
  
  The selected patch set of the change is outdated; it is not the current patch set of the change.
  
  It means that the currently viewed patch set depends on a outdated patch set of the ancestor change. This is because a new patch set for the ancestor change was uploaded in the meantime and as result the currently viewed patch set now needs to be rebased.
  
  If a descendant change is marked "not current" it means that an old patch set of the descendant change depends on the currently viewed patch set. It may be that the descendant was rebased in the meantime and with the new patch set this dependency was removed.
- Indirect descendant:
  
  The selected patch set of the change is an indirect descendant of the currently viewed patch set; it has a dependency to another patch set of this change. E.g. this could mean that a new patch set was uploaded for this change and the descendant change now needs to be rebased. Please note that following the link to an indirect descendant change may result in a completely different related changes listing.
- Closed ancestor:
  
  Indicates a closed ancestor, e.g. the commit was directly pushed into the repository bypassing code review, or the ancestor change was reviewed and submitted on another branch. The latter may indicate that the user has accidentally pushed the commit to the wrong branch, e.g. the commit was done on branch-a, but was then pushed to refs/for/branch-b.
- Abandoned:
  
  Indicates an abandoned change.
Conflicts With:

This section shows changes that conflict with the current change. Non-mergeable changes are filtered out; only conflicting changes that are mergeable are shown.

If this change is merged, its conflicting changes will have merge conflicts and must be rebased. The rebase of the other changes with the conflict resolution must then be done manually.
Submitted Together:

This section shows changes that will be submitted together with the currently viewed change, when clicking the submit button. It includes ancestors of the current patch set.

This may include changes and its ancestors with the same topic if change.submitWholeTopic is enabled. Only open changes with the same topic are included in the list.
Cherry-Picks:

This section shows changes with the same Change-Id for the current project.

Abandoned changes are filtered out.

For each change in this list the destination branch is shown as a prefix in front of the change subject.

If there are no related changes for a tab, the tab is not displayed.

Reply

The Reply… button in the change header allows to reply to the currently viewed patch set; one can add a summary comment, publish inline draft comments, and vote on the labels.

Clicking on the Reply… button opens a popup panel.

A text box allows to type a summary comment for the currently viewed patch set. Some basic markdown-like syntax is supported which renders indented lines preformatted, lines starting with "- " or "* " as list items, and lines starting with "> " as block quotes (also see replying to messages and inline comments).

If the current patch set is viewed, buttons are displayed for each label on which the user is allowed to vote. Voting on non-current patch sets is not possible.

The inline draft comments that will be published are displayed in a separate section so that they can be reviewed before publishing. There are links to navigate to the inline comments which can be used if a comment needs to be edited.

The Post button publishes the comments and the votes.

If a user can approve a label that is still required, a quick approve button appears in the change header that allows to add this missing approval by a single click. The quick approve button only appears if there is a single label that is still required and can be approved by the user.

E.g. if a change requires approvals on the 'Code-Review' and the 'Verified' labels, and there is already a '+1 Verified' vote, then if the user is allowed to vote the max score on 'Code-Review', a Code-Review+2 quick approve button appears that approves the 'Code-Review' label if clicked.

Using the quick approve button also publishes all inline draft comments; a summary comment is only added if the reply popup panel is open when the quick approve button is clicked.

user review ui change screen quick approve

History

The history of the change can be seen in the lower part of the screen.

The history contains messages for all kinds of change updates, e.g. a message is added when a new patch set is uploaded or when a review was done.

Update Notification

The change screen automatically polls for updates to the currently viewed change. If there is an update the user is informed by a popup panel in the bottom right corner.

The polling frequency depends on the server configuration; by default it is 30 seconds. Polling may also be completely disabled by the administrator.

user review ui change screen change update

Plugin Extensions

Gerrit plugins may extend the change screen. Java plugins in the backend can add additional actions to the triple-dot menu block. Frontend plugins can change the UI controls in arbitrary ways.

Side-by-Side Diff Screen

The side-by-side diff screen shows a single patch; the old file version is displayed on the left side of the screen; the new file version is displayed on the right side of the screen.

This screen allows to review a patch and to comment on it.

The checkbox in front of the file name allows the patch to be marked as reviewed. The Mark Reviewed diff preference allows to control whether the files should be automatically marked as reviewed when they are viewed.

user review ui side by side diff screen reviewed

In the header, on each side, the list of patch sets is shown. Clicking on a patch set changes the selection for the patch set comparison and the screen is refreshed to show the diff between the selected patch sets. The currently selected patch set is highlighted by a light blue background.

On the left side Base can be selected to compare a patch set against its base. For merge commits Auto Merge is available instead which allows to compare the patch against the result of the auto merge. The auto merge version may contain Git conflict markers and is useful for reviewing how conflicts are resolved by a patch.

Reviewers that are reviewing a patch for the first time look at its diff against its base; reviewers that have reviewed an old patch version before, may see what has changed since that version by comparing the old patch against the current patch.

user review ui side by side diff screen patch sets

The download icon next to the patch set list allows to download the patch. Unless the mime type of the file is configured as safe, the download file is a zip archive that contains the patch file.

If a file was renamed, the old and new file paths are shown in the header together with a similarity index that shows how much of the file content is unmodified.

user review ui side by side diff screen rename

Inline Comments

Inline comments are displayed directly in the patch file under the code that is commented. Inline comments can be placed on lines or on code blocks.

If an inline comment relates to a code block, this code block is highlighted by a yellow background.

Code blocks with comments may overlap. This means it is possible to attach several comments to the same code.

The lines of the patch file are linkable: simply append '#<linenumber>' to the URL, or click on the line-number. This not only opens a draft comment box, but also sets the URL fragment.

Clicking on the Reply button opens an editor to type the reply.

Quoting is supported, but only by manually copying & pasting the old comment that should be quoted and prefixing every line by "> ". Please note that for a correct rendering it is important to leave a blank line between a quoted block and the reply to it.

user review ui side by side diff screen inline comments

Comments are first saved as drafts, and you can revisit the drafts as you read through code review. Finally, they should be published by clicking the "Reply".

Comments can be unresolved (something should be changed) or resolved (informational). If you have addressed an unresolved comment in a next patchset, you can quickly resolve the comment by clicking "Done" (if it was resolved in a next patchset) or "Ack" (if you acknowledge the comment, but don’t want to make changes).

user review ui side by side diff screen replied done

To add a new inline comment there are several possibilities:

select a code block and press 'c'
go to a line, by clicking on it or by key navigation, and press 'c'
click on a line number

There are many ways to select code for commenting on it. The most frequently used methods are:

by mouse:
- click and drag with the mouse to select a block
- double-click on a word to select it
- double-click and drag with the mouse to select a code block word-wise
- triple-click on a line to select it
- triple-click and drag with the mouse to select a code block line-wise

For typing the new comment, a new comment box is shown under the code that is commented.

Clicking on the Save button saves the new comment as a draft. To make it visible to other users it must be published from the change screen by replying to the change.

File Level Comments

File level comments are added by clicking the 'File' header at the top of the file.

user review ui side by side diff screen file level comment

Diff Preferences

There are several options to control how patch diffs should be rendered. Users can configure their preferences in the diff preferences. The diff preferences can be accessed by clicking on the settings icon in the screen header.

user review ui side by side diff screen preferences

The following diff preferences can be configured:

Ignore Whitespace:

Controls whether differences in whitespace should be ignored or not.
- None:
  
  All differences in whitespace are highlighted.
- Trailing:
  
  Whitespace differences at the end of lines are ignored.
- Leading, Trailing:
  
  Whitespace differences at the beginning and end of lines are ignored.
- All:
  
  All differences in whitespace are ignored.
Tab Width:

Controls how many spaces should be displayed for a tab.
Columns:

Sets the preferred line length. At this position, lines are wrapped.
Lines Of Context:

The number of context lines that should be displayed before and after any diff. If the entire file checkbox is selected, the full file is rendered.

Skipped common lines can be expanded by clicking on the placeholder for the skipped lines.

Clicking on "… skipped <n> common lines …" expands the complete block of skipped lines.

If many lines are skipped there are additional links to expand the context by ten lines before and after the skipped block.
Syntax Highlighting:

Controls whether syntax highlighting should be enabled.

The language for the syntax highlighting is automatically detected from the file extension.
Show trailing whitespace:

Controls whether trailing whitespace is highlighted.
Show Tabs:

Controls whether tabs are highlighted.
Mark Reviewed:

Controls whether the files of the patch set should be automatically marked as reviewed when they are viewed.

Keyboard Shortcuts

Navigation within the review UI can be completely done by keys, and most actions can be controlled by keyboard shortcuts. Typing ? opens a popup that shows a list of available keyboard shortcuts.

In addition, Vim-like commands can be used to navigate and search within a patch file.

Part of Gerrit Code Review