Documentation/concept-changes.txt - gerrit - Git at Google

 = Changes

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

 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
 * Comments
 * Votes on link:config-labels.html[Review Labels]
 * The <<change-id>>

 [[change-properties]]
 == Change properties

 When you open a change in Gerrit, the Review screen displays a number of
 properties about that change.

 .Change Properties
 |===
 |Property|Description

 |Updated
 |The date on which the change was last updated.

 |Owner
 |The contributor who created the change.

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

 |Assignee
 |The contributor responsible for the change. Often used when a change has
 mulitple reviewers to identify the individual responsible for final approval.

 |Reviewers
 |A list of one or more contributors responsible for reviewing the change.

 |CC
 |A list of one or more contributors who are kept informed about the change, but
 are not required to review it.

 |Project
 |The name of the Gerrit project.

 |Branch
 |The branch on which the change was made.

 |Topic
 |An optional topic.

 |Strategy
 |The <<submit-strategies,submit strategy>> for the change.

 |Code Review
 |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]]
 == 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]]
 == 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.

 [[topic]]
 == Topics

 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
 push` command.

 For more information about using topics, see the user guide:
 link:cross-repository-changes.html[Submitting Changes Across Repositories by using Topics].

 [[submit-strategies]]
 == 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.

 .Submit Strategies
 |===
 |Strategy|Description

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

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

 |Cherry Pick
 |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
 set author.

 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.

 |Rebase Always
 |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.

 [[change-id]]
 == Change-Id

 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
 following:

 ....
 commit 29a6bb1a059aef021ac39d342499191278518d1d
 Author: A. U. Thor <author@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 <author@example.com>
     CC: R. E. Viewer <reviewer@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
 CC line.

 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
 link:https://www.kernel.org/doc/html/latest/maintainer/configure-git.html#creating-commit-links-to-lore-kernel-org[Linux kernel]
 have a convention of adding links to commit messages using the
 Link footer.

 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.

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

 SEARCHBOX
 ---------
	= Changes

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

	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
	* Comments
	* Votes on link:config-labels.html[Review Labels]
	* The <<change-id>>

	[[change-properties]]
	== Change properties

	When you open a change in Gerrit, the Review screen displays a number of
	properties about that change.

	.Change Properties
	\|===
	\|Property\|Description

	\|Updated
	\|The date on which the change was last updated.

	\|Owner
	\|The contributor who created the change.

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

	\|Assignee
	\|The contributor responsible for the change. Often used when a change has
	mulitple reviewers to identify the individual responsible for final approval.

	\|Reviewers
	\|A list of one or more contributors responsible for reviewing the change.

	\|CC
	\|A list of one or more contributors who are kept informed about the change, but
	are not required to review it.

	\|Project
	\|The name of the Gerrit project.

	\|Branch
	\|The branch on which the change was made.

	\|Topic
	\|An optional topic.

	\|Strategy
	\|The <<submit-strategies,submit strategy>> for the change.

	\|Code Review
	\|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]]
	== 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]]
	== 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.

	[[topic]]
	== Topics

	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
	push` command.

	For more information about using topics, see the user guide:
	link:cross-repository-changes.html[Submitting Changes Across Repositories by using Topics].

	[[submit-strategies]]
	== 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.

	.Submit Strategies
	\|===
	\|Strategy\|Description

	\|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
	branch.

	\|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 Merge
	\|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.

	\|Cherry Pick
	\|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
	set author.

	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.

	\|Rebase Always
	\|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.

	[[change-id]]
	== Change-Id

	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
	following:

	....
	commit 29a6bb1a059aef021ac39d342499191278518d1d
	Author: A. U. Thor <author@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 <author@example.com>
	CC: R. E. Viewer <reviewer@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
	CC line.

	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
	link:https://www.kernel.org/doc/html/latest/maintainer/configure-git.html#creating-commit-links-to-lore-kernel-org[Linux kernel]
	have a convention of adding links to commit messages using the
	Link footer.

	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.

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

	SEARCHBOX
	---------