|A change represents a single commit under review. Each change is identified
|by a <<change-id>>.
|Multiple git commits can share the same Change-Id, allowing you to update a
|change as you receive feedback through the code review process. In Gerrit,
|commits that share the same Change-Id are referred to as _patch sets_. When a
|change is approved, only the latest version of a commit is submitted to the
|You can view a specific change using Gerrit's Review screen. This screen
|provides the following information for each change:
|* Current and previous patch sets
|* <<Change properties>>, such as owner, project, and target branch
|* Votes on link:config-labels.html[Review Labels]
|* The <<change-id>>
|== Change properties
|When you open a change in Gerrit, the Review screen displays a number of
|properties about that change.
||The date on which the change was last updated.
||The contributor who created the change.
||The user that uploaded the current patch set (e.g. the user that executed the
|`git push` command, or the user that triggered the patch set creation through
|an action in the UI).
||The contributor responsible for the change. Often used when a change has
|mulitple reviewers to identify the individual responsible for final approval.
||A list of one or more contributors responsible for reviewing the change.
||A list of one or more contributors who are kept informed about the change, but
|are not required to review it.
||The name of the Gerrit project.
||The branch on which the change was made.
||An optional topic.
||The <<submit-strategies,submit strategy>> for the change.
||Displays the Code Review status for the change.
|In addition, Gerrit displays the status of any additional labels, such as
|the Verified label, that have been configured for the server. See
|link:config-labels.html[Review Labels] for more information.
|== Change Message
|Next to the list of change properties is the change message. This message
|contains user-supplied information regarding what the change does. To modify
|the change message, click the *Edit* link.
|By default, the change message contains the Change-Id. This ID contains a
|permanent link to a search for that Change-Id in Gerrit.
|== Related Changes
|In some cases, a change may be dependent on another change. These changes are
|listed next to the change message. These related changes are grouped together in
|several categories, including:
|* Relation Chain. These changes are related by parent-child relationships,
| regardless of <<topic,topic>>.
|* Merge Conflicts. These are changes in which there is a merge conflict with
| the current change.
|* Submitted Together. These are changes that share the same <<topic,topic>>.
|An arrow indicates the change you are currently viewing.
|Changes can be grouped by topics. Topics make it easier to find related changes
|by using the topic search operator. Changes with the same topic also appear in
|the *Relation Chain* section of the Review screen.
|Grouping changes by topics can be helpful when you have several changes that,
|when combined, implement a feature.
|Assigning a topic to a change can be done in the change screen or through a `git
|For more information about using topics, see the user guide:
|link:cross-repository-changes.html[Submitting Changes Across Repositories by using Topics].
|== Submit strategies
|Each project in Gerrit can employ a specific submit strategy. This strategy is
|listed in the change properties section of the Review screen.
|The following table lists the supported submit strategies.
||Fast Forward Only
||No merge commits are produced. All merges must be handled on the client, before
|submitting the change.
|To submit a change, the change must be a strict superset of the destination
||Merge If Necessary
||The default submit strategy. If the change being submitted is a strict superset
|of the destination branch, then the branch is fast-forwarded to the change. If
|not, a merge commit is automatically created at submit time. This is identical
|to the `git merge --ff` command.
||Always produce a merge commit, even if the change is a strict superset of the
|destination branch. This is identical to the `git merge --no-ff` command.
|It is often used when users of the project want to be able to read the history
|of submits by running the `git log --first-parent` command.
||Always cherry pick the patch set, ignoring the parent lineage and instead
|creating a new commit on top of the current branch.
|When cherry picking a change, Gerrit automatically appends a short summary of
|the change's approvals and a link back to the change. The committer header is
|also set to the submitter, while the author header retains the original patch
|NOTE: Gerrit ignores dependencies between changes when using this submit type
|unless `change.submitWholeTopic` is enabled and depending changes share the same
|topic. This means submitters must remember to submit changes in the right order
|when using this submit type.
||Rebase if Necessary
||If the change being submitted is a strict superset of the destination branch,
|the branch is fast-forwarded to the change. If not, the change is automatically
|rebased and the branch is fast-forwarded to the change.
||Similar to Rebase If Necessary, but creates a new patch set even if fast
|forward is possible. This strategy is also similar to Cherry Pick; however,
|Rebase Always does not ignore dependencies.
|Any project owner can use the Project screen to modify the method Gerrit uses
|to submit a change.
|Gerrit uses a Change-Id to identify which patch sets belong to the same review.
|For example, you make a change to a project. A reviewer supplies some feedback,
|which you address in an amended commit. By assigning the same Change-Id to both
|commits, Gerrit can attach those commits to the same change.
|Change-Ids are appended to the end of a commit message, and resemble the
|Author: A. U. Thor <email@example.com>
|Date: Thu Aug 20 12:46:50 2009 -0700
| Improve foo widget by attaching a bar.
| We want a bar, because it improves the foo by providing more
| wizbangery to the dowhatimeanery.
| Bug: #42
| Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
| Signed-off-by: A. U. Thor <firstname.lastname@example.org>
| CC: R. E. Viewer <email@example.com>
|Gerrit requires that the Change-Id is in the footer (last paragraph) of a
|commit message. It can be combined with a Signed-off-by, CC, or other lines. For
|instance, the previous example has a Change-Id, along with a Signed-off-by and
|Notice that the Change-Id is similar to the commit id. To avoid confusing the
|two, a Change-Id typically begins with an `I`.
|While there are several ways you can add a Change-Id, the standard
|method uses git's link:cmd-hook-commit-msg.html[commit-msg hook]
|to automatically add the Change-Id to each new commit.
|== The Link footer
|Gerrit also supports the Link footer as an alternative to the Change-Id
|footer. A Link footer looks like this:
| Link: https://gerrit-review.googlesource.com/id/Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
|The advantage of this style of footer is that it usually acts
|as a link directly to the change's review page, provided that
|the change has been uploaded to Gerrit. Projects such as the
|have a convention of adding links to commit messages using the
|If multiple changes have been uploaded to Gerrit with the same
|change ID, for example if a change has been cherry-picked to multiple
|branches, the link will take the user to a list of changes.
|The base URL in the footer is required to match the server's base URL.
|If the URL does not match, the server will not recognize the footer
|as a change ID footer.
|The link:cmd-hook-commit-msg.html[commit-msg hook] can be configured
|to insert Link footers instead of Change-Id footers by setting the
|property `gerrit.reviewUrl` to the base URL of the Gerrit server.
|Part of link:index.html[Gerrit Code Review]