:linkattrs:
= Review UI Overview

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

[[change-screen]]
== Change Screen

The change screen is the main view for a change. It shows the details of a
single change and allows various actions on it.

image::images/user-review-ui-change-screen.png[width=800, link="images/user-review-ui-change-screen.png"]

Here are the main areas of the screen

image::images/user-review-ui-change-screen-annotated.png[width=800, link="images/user-review-ui-change-screen-annotated.png"]


=== Top info

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

image::images/user-review-ui-change-screen-topleft.png[width=600, link="images/user-review-ui-change-screen-topleft.png"]

[[change-status]]
The change status shows the state of the change:

- `Active`:
+
The change is under active review.

- `Merge Conflict`:
+
The change can't be merged into the destination branch due to conflicts.

- `Ready to Submit`:
+
The change has all necessary approvals and fulfils all other submit
requirements. It can be submitted.

- `Merged`:
+
The change was successfully merged into the destination branch.

- `Abandoned`:
+
The change was abandoned. It is not intended to be updated, reviewed or
submitted anymore.

- `Private`:
+
The change is marked as link:intro-user.html#private-changes[Private]. And has
reduced visibility.

- `Revert Created|Revert Submitted`:
+
The change has a corresponding revert change. Revert changes can be created
through UI (see <<actions, Actions section>>).

- `WIP`:
+
The change was marked as "Work in Progress". For example to indicate to
reviewers that they shouldn't review the change yet.

[[star]]
=== Star Change

Clicking the star icon bookmarks the change: 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
link:user-search.html#is[is:starred] search operator.

[[quick-links]]
=== Links Menu

Links menu contains various change related strings for quick copying. Such as:
Change Number, URL, Title+Url, etc. The lines in this menu can also be accessed
via shortcuts for convenience.

image::images/user-review-ui-copy-links.png[width=600, link="images/user-review-ui-copy-links.png"]

[[change-info]]
=== Change metadata

The change metadata block contains detailed information about the change.

image::images/user-review-ui-change-metadata.png[width=600, link="images/user-review-ui-change-metadata.png"]

- [[owner]]Owner/Uploader/Author/Committer:
+
Owner is the person who created the change
+
Uploader is the person who uploaded the latest patchset (the patchset that will
be merged if the change is submitted)
+
Author/Committer are concepts from Git and are retrieved from the commit when
it's sent for review.

- [[reviewers]]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 through reply dialog that is opened by clicking on
the pencil icon or on "Reply" button. Typing into the reviewer text field
activates auto completion of user and group names.
+

- [[cc-list]]CC:
+
Accounts in CC receive notifications for the updates on the change, but don't
need to vote/review. If the CC'ed user votes they are moved to reviewers.
+

- [[attention-set]]link:user-attention-set.html[Attention set]:
+
Users in attention set are marked by "chevron" symbol (see screenshot above).
The mark indicates that there are actions their attention is required on the
change: Something updated/changed since last review, their vote is required,
etc.
+
Changes for which you are currently in attention set can be found using
`attention:<User>` in search and show up in a separate category of personal
dashboard.
+
Clicking on the mark removes the user from attention set.


[[remove-reviewer]]
Reviewers can be removed from the change by selecting the appropriate option on
the chip's hovercard. Removing a reviewer also removes current votes of the
reviewer. The removal of votes is recorded in the change log.

Removing reviewers is protected by permissions:

** Users can always remove themselves.
** The change owner may remove any zero or positive score.
** Users with the link:access-control.html#category_remove_reviewer[
   Remove Reviewer] access right, the branch owner, the project owner
   and Gerrit administrators may remove anyone.

- [[repo-branch-topic]]Project (Repo) / Branch / Topic:
+
The name of the project for which the change was done is displayed as a
link to the link:user-dashboards.html#project-default-dashboard[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
link:access-control.html#category_edit_topic_name[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.

- [[parent]]Parent:
+
Parent commit of the latest uploaded patchset. Or if the change has been merged
the parent of the commit it was merged as into the destination branch.

- [[merged-as]]Merged As:
+
The SHA of the commit corresponding to the merged change on the destination
branch.

- [[revert-created-as]]Revert (Created|Submitted) As:
+
Points to the revert change, if one was created.

- [[cherry-pick-of]]Cherry-pick of:
+
If the change was created as cherry-pick of some other change to a different
branch, points to the original change.

- [[submit-strategy]]Submit Strategy:
+
The link:project-setup.html#submit_type[submit strategy] that will be
used to submit the change. The submit strategy is only displayed for
open changes.

- [[hastags]]Hashtags:
+
Arbitrary string hashtags, that can be used to categorize changes and later use
hashtags for search queries.

[[submit-requirements]]
=== Submit Requirements

image::images/user-review-ui-submit-requirements.png[width=600, link="images/user-review-ui-copy-links.png"]

Submit Requirements describe various conditions that must be fulfilled before
the change can be submitted. Hovering over the requirement will show the
description of the requirement, as well as additional information, such as:
corresponding expression that is being evaluated, who can vote on the related
labels etc.

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

For more detail on Submit Requirements see
link:config-submit-requirements.html[Submit Requirement Configuration] page.

[[actions]]
=== Actions
Actions buttons are at the top right and in the overflow menu.
Depending on the change state and the permissions of the user, different
actions are available on the change:

** [[submit]]`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 link:access-control.html#category_submit[Submit] access right is
assigned.

** [[revert]]`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]]`Abandon`:
+
Abandons the change.
+
The `Abandon` button is only available if the change is open and the
link:access-control.html#category_abandon[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]]`Restore`:
+
Restores the change.
+
The `Restore` button is only available if the change is abandoned and
the link:access-control.html#category_abandon[Abandon] and the
link:access-control.html#category_push[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]]`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 link:access-control.html#category_rebase[Rebase] access right is
assigned. Rebasing merge commits is not supported.

** [[cherry-pick]]`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. 'Cherry-pick committer email'
drop-down is visible for single change cherry-picks when user has more than
one email registered to their account. It is possible to select any of the
registered emails to be used as the cherry-pick committer email. It defaults
to source commit's committer email if it is a registered email of the calling
user, else defaults to calling user's preferred email.
+
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]]`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
link:access-control.html#category_delete_own_changes[Delete Own Changes]
permission, if they are granted the
link:access-control.html#category_delete_changes[Delete Changes] permission,
or if they are an administrator.

** [[plugin-actions]]Further actions may be available if plugins are installed.

+
image::images/user-review-ui-change-screen-change-info-actions.png[width=400, link="images/user-review-ui-change-screen-change-info-actions.png"]

[[files-tab]]
=== File List

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

image::images/user-review-ui-change-screen-file-list.png[width=800, link="images/user-review-ui-change-screen-file-list.png"]

[[magic-files]]
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.

Every file is accompanied by a number of extra information, such as status
(modified, added, deleted, etc.), number of changed lines, type (executable,
link, plain), comments and others. Hovering over most icons and columns reveals
additional information.

Each file can be expanded to view the contents of the file and diff. For more
information see <<diff-view, Diff View>> section.

[[comments-tab]]
=== Comments Tab

Instead of the file list, a comments tab can be selected. Comments tab presents
comments along with related file/diff snippets. It also offers some filtering
opportunities at the top (ex. only unresolved, only comments from user X, etc.)

image::images/user-review-ui-change-screen-comments-tab.png[width=800, link="images/user-review-ui-change-screen-comments-tab.png"]

[[checks-tab]]
=== Checks Tab
Checks tab contains results of different "Check Runs" installed by plugins. For
more information see link:pg-plugin-checks-api.html[Checks API] page.

[[patch-sets]]
=== Patch Sets

The change screen only presents one pair of patch sets (`Patchset A` and
`Patchset B`) at a time. `A` is always an earlier upload than `B` and serves as
a base for diffing when viewing changes in the files. Which patch
sets is currently viewed can be seen from the `Patch Sets` drop-down
panel in the change header. If patchset 'A' is not selected a parent commit of
patchset 'B' is used by default.

image::images/user-review-ui-change-screen-patch-sets.png[width=300, link="images/user-review-ui-change-screen-patch-sets.png"]

[[download]]
=== Download

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

image::images/user-review-ui-change-screen-download-commands.png[width=800, link="images/user-review-ui-change-screen-download-commands.png"]

The available download commands depend on the installed Gerrit plugins.
The most popular plugin for download commands, the
link:https://gerrit-review.googlesource.com/admin/repos/plugins/download-commands[
download-commands,role=external,window=_blank] 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. Additionally each line can copied to clipboard
using number (1..9) of the appropriate line as a keyboard shortcut.

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

image::images/user-review-ui-change-screen-included-in.png[width=800, link="images/user-review-ui-change-screen-included-in.png"]

[[related-changes]]
=== Related Changes

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 that are displayed in separate
sectionsunder each other.

The following sections may be displayed:

- [[related-changes-section]]`Related Changes`:
+
This section 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]]Not current:
+
The patch set of the related change which is related to the current change is
outdated; it is not the current patch set of the change.
+
For ancestor 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]]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.

** [[merged-related-change]]Merged
+
The change has been  merged.
+
If the relationship to submitted change falls under conditions described in
<<not-current, Not current>> the status is orange. Such changes can appear as
both ancestors and descendants of the change.

** [[submittable-related-change]]Submittable
+
All the submit requirements are fulfilled for the related change and it can be
submitted when all of its ancestors are submitted.

** [[closed-ancestor-abandoned]]Abandoned:
+
Indicates an abandoned change.

- [[conflicts-with]]`Merge Conflicts`:
+
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]]`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.
+
If `change.submitWholeTopic` is enabled this section also includes changes with
the same topic. The list recursively includes all changes that can be reached by
ancestor and topic relationships. Only open changes are included in the result.

- [[cherry-picks]]`Cherry-Picks`:
+
This section shows changes with the same link:user-changeid.html[
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.

- [[same-topic]]`Same Topic`:
+
This section shows changes which are part of the same topic. If
`change.submitWholeTopic` is enabled, then this section is omitted and changes
are included as part of <<submitted-together, `Submitted Together`>>

[[reply]]
=== 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, vote on the labels and adjust attention set.

image::images/user-review-ui-change-screen-reply.png[width=800, link="images/user-review-ui-change-screen-reply.png"]

Clicking on the `Reply...` button opens a popup panel.

[[summary-comment]]
A text box allows to type a summary comment for the currently viewed
patch set. Markdown syntax is supported same as in other
<<comments-markdown, Comments>>.

[[vote]]
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 `SEND` button publishes the comments and the votes.

[[quick-approve]]
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.

image::images/user-review-ui-change-screen-quick-approve.png[width=800, link="images/user-review-ui-change-screen-quick-approve.png"]

[[change-log]]
=== Change Log

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

The log 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]]
=== 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.

image::images/user-review-ui-change-screen-change-update.png[width=400, link="images/user-review-ui-change-screen-change-update.png"]

[[plugin-extensions]]
=== 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.

image::images/user-review-ui-change-screen-plugin-extensions.png[width=300, link="images/user-review-ui-change-screen-plugin-extensions.png"]

[[diff-view]]
== Side-by-Side Diff Screen

The side-by-side diff screen shows a single patch (or difference between two
patchsets); 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.

image::images/user-review-ui-side-by-side-diff-screen.png[width=800, link="images/user-review-ui-side-by-side-diff-screen.png"]


[[side-by-side-mark-reviewed]]
The checkbox in front of the file name allows the
patch to be marked as reviewed. The link:#mark-reviewed[Mark Reviewed]
diff preference allows to control whether the files should be
automatically marked as reviewed when they are viewed.

image::images/user-review-ui-side-by-side-diff-screen-reviewed.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-reviewed.png"]

[[patch-set-selection]]
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.

image::images/user-review-ui-side-by-side-diff-screen-patch-sets.png[width=400, link="images/user-review-ui-side-by-side-diff-screen-patch-sets.png"]

[[download-file]]
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.


[[side-by-side-rename]]
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.

image::images/user-review-ui-side-by-side-diff-screen-rename.png[width=400, link="images/user-review-ui-side-by-side-diff-screen-rename.png"]

[[normal-and-rebase-edits]]
=== Normal and Rebase Edits

In the diff view, Gerrit shows added and removed contents with green and red
colors respectively.

image::images/user-review-ui-side-by-side-diff-normal-edits.png[width=800, link="images/user-review-ui-side-by-side-diff-normal-edits.png"]

When comparing two patch-sets against each other, and if both patch-sets have
different bases (parents), Gerrit also identifies parts of the diff that were
modified due to rebase. Those are called “rebase edits” and are highlighted with
different colors.

image::images/user-review-ui-side-by-side-diff-rebase-edits.png[width=800, link="images/user-review-ui-side-by-side-diff-rebase-edits.png"]

Gerrit identifies rebase edits by also inspecting the diff between parents, and
if it detects an edit between parents that’s also an edit between the patch-sets
(after mapping/transforming the edit), then it marks it as a rebase edit. This
first diffs both patch-sets to identify all edits, then potentially excludes
some of them if they were identified as rebase edits.

image::images/user-review-ui-side-by-side-diff-rebase.png[width=400, link="images/user-review-ui-side-by-side-diff-rebase.png"]

If all edits in a file were due to rebase, the file is skipped and is not shown
among the list of files in the ‘files tab’.

[[hazardous-rebases]]
=== Hazardous Rebases

A rebase might be hazardous in some cases. One such example is when users have a
stack of changes (e.g. two changes as in the below figure) then squash both
changes and upload the resulting commit as patch-set 2. In this case, PS1 and
PS2 are identical and Gerrit shows an empty diff, which is a correct diff
but it's hiding the fact that new content got implicitly merged into this change
from the parent change.

image::images/user-review-ui-side-by-side-diff-squash.png[width=400, link="images/user-review-ui-side-by-side-diff-squash.png"]

[[inline-comments]]
=== 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.

[[comments-markdown]]
The comments support markdown. It follows the CommonMark spec, except inline
images and direct HTML are not rendered and kept as plaintext.

[[line-links]]
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.

[[reply-inline-comment]]
Clicking on the `Reply` button opens an editor to type the reply.

Previous comment can be quoted using "Quote" button. A new draft would be open
on the same comment thread with the text of the previoused comment quoted using
markdown syntax.

image::images/user-review-ui-side-by-side-diff-screen-inline-comments.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-inline-comments.png"]

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

[[done]]
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).

image::images/user-review-ui-side-by-side-diff-screen-replied-done.png[width=400, link="images/user-review-ui-side-by-side-diff-screen-replied-done.png"]

[[add-inline-comment]]
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 link:#key-navigation[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 link:#reply[replying] to the change.

[[suggest-fix]]
=== Suggest fix (WIP)
Comments can contain suggested fixes.

Clicking "Suggest Fix" will insert a special code-block in the text of the
comment. The contents of this code block will replace the lines the comment is
attached to (what gets highlighted when hovering over comment).

image::images/user-review-ui-suggest-fix.png[width=400, link="images/user-review-ui-suggest-fix.png"]

The author of the change can then preview and apply the change. This will created
a new patchset with changes applied.

image::images/user-review-ui-apply-fix.png[width=800, link="images/user-review-ui-apply-fix.png"]

[[file-level-comments]]
=== File Level Comments

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

image::images/user-review-ui-side-by-side-diff-screen-file-level-comment.png[width=400, link="images/user-review-ui-side-by-side-diff-screen-file-level-comment.png"]

[[diff-preferences]]
=== 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.

image::images/user-review-ui-side-by-side-diff-screen-preferences.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-preferences.png"]

The following diff preferences can be configured:

- [[ignore-whitespace]]`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]]`Tab Width`:
+
Controls how many spaces should be displayed for a tab.

- [[columns]]`Columns`:
+
Sets the preferred line length. At this position, lines are wrapped.

- [[lines-of-context]]`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.
+
image::images/user-review-ui-side-by-side-diff-screen-expand-skipped-lines.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-expand-skipped-lines.png"]

- [[syntax-highlighting]]`Syntax Highlighting`:
+
Controls whether syntax highlighting should be enabled.
+
The language for the syntax highlighting is automatically detected from
the file extension.

- [[whitespace-errors]]`Show trailing whitespace`:
+
Controls whether trailing whitespace is highlighted.

- [[show-tabs]]`Show Tabs`:
+
Controls whether tabs are highlighted.

- [[mark-reviewed]]`Mark Reviewed`:
+
Controls whether the files of the patch set should be automatically
marked as reviewed when they are viewed.

[[keyboard-shortcuts]]
== 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.


image::images/user-review-ui-change-screen-keyboard-shortcuts.png[width=800, link="images/user-review-ui-change-screen-keyboard-shortcuts.png"]


In addition, Vim-like commands can be used to link:#key-navigation[
navigate] and link:#search[search] within a patch file.

GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------