Review UI

The focus of the change screen is on the commit message since this is the most important information about a change. The numeric change ID and the change status are displayed right above the commit message.

The numeric change ID is a link to the change and clicking on it refreshes the change screen. By copying the link location you can get the permalink of the change.

The change status shows the state of the change:

The commit info block shows information about the commit of the currently viewed patch set.

It displays the author and the committer as links to a list of this person’s changes that have the same status as the currently viewed change.

The commit ID, the parent commit(s) and the Change-Id are displayed with a copy-to-clipboard icon that allows the ID to be copied into the clipboard.

If a Git web browser, such as gitweb or Gitiles, is configured, there is also a link to the commit in the Git web browser.

If a merge commit is viewed this is highlighted by an icon.

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

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:

The checkboxes in front of the file names allow files to be marked as reviewed.

The type of a file modification is indicated by the character in front of the file name:

If a file is renamed or copied, the name of the original file is displayed in gray below the file name.

Repeating path segments are grayed out.

Inline comments on a file are shown in the Comments column.

Draft comments, i.e. comments that have been written by the current user but not yet published, are highlighted in red.

New comments from other users, that were published after the current user last reviewed this change, are highlighted in bold.

The size of the modifications in the files can be seen in the Size column. The footer row shows the total size of the change.

The size information is useful to easily spot the files that contain the most modifications; these files are likely to be the most relevant files for this change. The total change size gives an estimate of how long a review of this change may take.

When the "Show Change Sizes As Colored Bars" user preference is enabled, the Size column shows the sum of inserted and deleted lines as one number. In addition, the change size is shown as a bar. The size of the bar indicates the amount of changed lines, and its coloring shows the proportion of insertions (green) to deletions (red).

When the "Show Change Sizes As Colored Bars" user preference is disabled, the colored bar is not shown. For added and renamed files, the Size column shows the number of inserted and deleted lines. For new files, the column only shows the total number of lines in the new file. No size is shown for binary files and deleted files.

In the header of the file list, the Diff Against selection can be changed. This selection allows one to choose if the currently viewed patch set should be compared against its base or against another patch set of this change. The file list is updated accordingly.

The file list header also provides an Open All button that opens the diff views for all files in the file list.

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. It shows the number of the currently viewed patch set and the total number of patch sets, in the form: "current patch set/number of patch sets".

If a non-current patch set is viewed this is indicated by the Not Current change state. Please note that some operations are only available on the current patch set.

Another indication is a highlighted drop-down label.

The patch set drop-down list shows the list of patch sets and allows to switch between them. The patch sets are sorted in descending order so that the current patch set is always on top.

Draft patch sets are marked with DRAFT.

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.

For merged changes the Included In drop-down panel is available in the change header.

The Included In drop-down panel shows the branches and tags in which the change is included. E.g. if a change fixes a bug, this allows to quickly see in which released versions the bug-fix is contained (assuming that every release is tagged).

The star icon in the change header allows to mark the change as a favorite. Clicking on the star icon again, unstars the change.

Starring a change turns on email notifications for this change.

Starred changed are listed under My > Starred Changes. and can be queried by the is:starred search operator.

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:

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

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

Note that you can set the text and tooltip of the button in gerrit.config.

If the current patch set is viewed, radio 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.

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.

Messages with new comments from other users, that were published after the current user last reviewed this change, are automatically expanded.

It is possible to directly reply to a change message by clicking on the reply icon in the right upper corner of a change message. This opens the reply popup panel and prefills the text box with the quoted comment. Then the reply can be written below the quoted comment or inserted inline. Lines starting with "> " will be rendered as a block quote. Please note that for a correct rendering it is important to leave a blank line between a quoted block and the reply to it.

Inline comments are directly displayed in the change history and there are links to navigate to the inline comments.

The Expand All button expands all messages; the Collapse All button collapses all messages.

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.

Gerrit plugins may extend the change screen; they can add buttons for additional actions to the change info block and display arbitrary UI controls below the change info block.

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. To link to a certain line in the patch file, '@<line-number>' must be appended to the patch link, e.g. http://host:8080/#/c/56857/2/Documentation/user-review-ui.txt@665. To link to a line in the old file version, '@a<line-number>' must be appended to the patch link. These links can be used to directly link to certain inline comments.

If the diff preference Expand All Comments is set to Expand, all inline comments will be automatically expanded.

In the header of the comment box, the name of the comment author and the timestamp of the comment are shown. If avatars are configured on the server, the avatar image of the comment author is displayed in the top left corner. Below the actual comment there are buttons to reply to the comment.

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.

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

The Cancel button cancels the editing and discards any changes to the draft comment.

Clicking on the Discard button deletes the inline draft comment.

Draft comments are marked by the text "Draft" in the header in the place of the comment author.

A draft comment can be edited by clicking on the Edit button, or deleted by clicking on the Discard button.

Clicking on the Done button is a quick way to reply with "Done" to a comment. This is used to mark a comment as addressed by a follow-up patch set.

To add a new inline comment there are several possibilities:

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

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.

Clicking on the Discard button deletes the new comment.

Comments that apply to a whole file can be added on file level.

File level comments are added by clicking on the comment icon in the header above the file.

Clicking on the comment icon opens a comment box for typing the file level comment.

For searching within a patch file, a Vim-like search is supported. Typing / opens the search box. Typing in the search box immediately highlights matches in the patch file with a yellow background. Using JavaScript regular expressions in the search term is supported. The search is case insensitive. After confirming the search by ENTER one can navigate between the matches by n / N to go to the next / previous match. Skipped lines are automatically expanded if they contain a match and one navigates to it.

For additional possibilities to search please check the Vim documentation. There are other useful ways to search, e.g. while the cursor is on a word, pressing * or # searches for the next or previous occurrence of the word.

Searching by Ctrl-F finds matches only in the visible area of the screen unless the Render diff preference is set to Slow.

Vim-like commands can be used to navigate within a patch file:

Please check the Vim documentation for further information.

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.

The diff preferences popup allows to change the diff preferences. By clicking on the Save button changes to the diff preferences are saved permanently. Clicking on the Apply button applies the new diff preferences to the current screen, but they are discarded when the screen is refreshed. The Save button is only available if the user is signed in.

The following diff preferences can be configured: