Merge changes Ibe599add,I829c2747,I19b99d7e,If65e6062,I0cf5013b
* changes: project-configuration: reference the more complete doc Merge docs about "requireChangeId" into "config-project-config.txt" Move "createNewChangeForAllNotInTarget" to "config-project-config.txt" Move docs about "submit type" to "config-project-config.txt" Move docs about project state to "config-project-config.txt"
This commit is contained in:
Edwin Kempin
@@ -118,7 +118,7 @@ Description values containing spaces should be quoted in single quotes
|
||||
Defaults to MERGE_IF_NECESSARY unless
|
||||
link:config-gerrit.html#repository.name.defaultSubmitType[
|
||||
repository.<name>.defaultSubmitType] is set to a different value.
|
||||
For more details see link:project-configuration.html#submit_type[
|
||||
For more details see link:config-project-config.html#submit-type[
|
||||
Submit Types].
|
||||
|
||||
--use-content-merge::
|
||||
|
||||
@@ -59,7 +59,7 @@ Description values containing spaces should be quoted in single quotes
|
||||
|
||||
+
|
||||
For more details see
|
||||
link:project-configuration.html#submit_type[Submit Types].
|
||||
link:config-project-config.html#submit-type[Submit Types].
|
||||
|
||||
--content-merge::
|
||||
If enabled, Gerrit will try to perform a 3-way merge of text
|
||||
|
||||
@@ -3666,9 +3666,9 @@ The default submit type for newly created projects. Supported values
|
||||
are `INHERIT`, `MERGE_IF_NECESSARY`, `FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`,
|
||||
`REBASE_ALWAYS`, `MERGE_ALWAYS` and `CHERRY_PICK`.
|
||||
+
|
||||
For more details see link:project-configuration.html#submit_type[Submit Types].
|
||||
For more details see link:config-project-config.html#submit-type[Submit Types].
|
||||
+
|
||||
Default is link:project-configuration.html#submit_type_inherit[`INHERIT`].
|
||||
Default is link:config-project-config.html#submit_type_inherit[`INHERIT`].
|
||||
+
|
||||
This submit type is only applied at project creation time if a submit type is
|
||||
omitted from the link:rest-api-projects.html#project-input[ProjectInput]. If the
|
||||
|
||||
@@ -96,7 +96,41 @@ The project section includes configuration of project settings.
|
||||
|
||||
These are the keys:
|
||||
|
||||
- Description
|
||||
[[description]]description::
|
||||
+
|
||||
A description for the project.
|
||||
|
||||
[[state]]state:
|
||||
+
|
||||
This setting defines the state of the project. A project can have the
|
||||
following states:
|
||||
|
||||
- `Active`:
|
||||
+
|
||||
The project is active and users can see and modify the project according
|
||||
to their access rights on the project.
|
||||
|
||||
- `Read Only`:
|
||||
+
|
||||
The project is read only and all modifying operations on it are
|
||||
disabled. E.g. this means that pushing to this project fails for all
|
||||
users even if they have push permissions assigned on it.
|
||||
+
|
||||
Setting a project to this state is an easy way to temporary close a
|
||||
project, as you can keep all write access rights in place and they will
|
||||
become active again as soon as the project state is set back to
|
||||
`Active`.
|
||||
+
|
||||
This state also makes sense if a project was moved to another location.
|
||||
In this case all new development should happen in the new project and
|
||||
you want to prevent that somebody accidentally works on the old
|
||||
project, while keeping the old project around for old references.
|
||||
|
||||
- `Hidden`:
|
||||
+
|
||||
The project is hidden and only visible to project owners. Other users
|
||||
are not able to see the project even if they have read permissions
|
||||
granted on the project.
|
||||
|
||||
|
||||
[[receive-section]]
|
||||
@@ -125,11 +159,27 @@ property is inherited from the parent project.
|
||||
|
||||
[[receive.requireChangeId]]receive.requireChangeId::
|
||||
+
|
||||
Controls whether or not the Change-Id must be included in the commit message
|
||||
in the last paragraph. Default is `INHERIT`, which means that this property
|
||||
is inherited from the parent project. The global default for new hosts
|
||||
is `true`
|
||||
+
|
||||
The `Require Change-Id in commit message` option defines whether a
|
||||
link:user-changeid.html[Change-Id] in the commit message is required
|
||||
for pushing a commit for review. If this option is set, trying to push
|
||||
a commit for review that doesn't contain a Change-Id in the commit
|
||||
message fails with link:error-missing-changeid.html[missing Change-Id
|
||||
in commit message footer].
|
||||
|
||||
It is recommended to set this option and use a
|
||||
link:user-changeid.html#create[commit-msg hook] (or other client side
|
||||
tooling like EGit) to automatically generate Change-Id's for new
|
||||
commits. This way the Change-Id is automatically in place when changes
|
||||
are reworked or rebased and uploading new patch sets gets easy.
|
||||
|
||||
If this option is not set, commits can be uploaded without a Change-Id,
|
||||
but then users have to remember to copy the assigned Change-Id from the
|
||||
change screen and insert it manually into the commit message when they
|
||||
want to upload a second patch set.
|
||||
|
||||
Default is `INHERIT`, which means that this property is inherited from
|
||||
the parent project. The global default for new hosts is `true`
|
||||
|
||||
This option is deprecated and future releases will behave as if this
|
||||
is always `true`.
|
||||
|
||||
@@ -210,6 +260,25 @@ the implicit merge check.
|
||||
Default is `INHERIT`, which means that this property is inherited from
|
||||
the parent project.
|
||||
|
||||
[[receive.createNewChangeForAllNotInTarget]]receive.createNewChangeForAllNotInTarget::
|
||||
+
|
||||
The `create-new-change-for-all-not-in-target` option provides a
|
||||
convenience for selecting link:user-upload.html#base[the merge base]
|
||||
by setting it automatically to the target branch's tip so you can
|
||||
create new changes for all commits not in the target branch.
|
||||
|
||||
This option is disabled if the tip of the push is a merge commit.
|
||||
|
||||
This option also only works if there are no merge commits in the
|
||||
commit chain, in such cases it fails warning the user that such
|
||||
pushes can only be performed by manually specifying
|
||||
link:user-upload.html#base[bases]
|
||||
|
||||
This option is useful if you want to push a change to your personal
|
||||
branch first and for review to another branch for example. Or in cases
|
||||
where a commit is already merged into a branch and you want to create
|
||||
a new open change for that commit on another branch.
|
||||
|
||||
[[change-section]]
|
||||
=== Change section
|
||||
|
||||
@@ -250,7 +319,7 @@ submit settings:
|
||||
- 'mergeContent': Defines whether to automatically merge changes. Valid values
|
||||
are 'true', 'false', or 'INHERIT'. Default is 'INHERIT'.
|
||||
|
||||
- 'action': defines the link:project-configuration.html#submit_type[submit type]. Valid
|
||||
- 'action': defines the #submit-type[submit type]. Valid
|
||||
values are 'fast forward only', 'merge if necessary', 'rebase if necessary',
|
||||
'merge always' and 'cherry pick'. The default is 'merge if necessary'.
|
||||
|
||||
@@ -410,3 +479,95 @@ Part of link:index.html[Gerrit Code Review]
|
||||
|
||||
SEARCHBOX
|
||||
---------
|
||||
|
||||
[[submit-type]]
|
||||
=== Submit Type
|
||||
|
||||
The method Gerrit uses to submit a change to a project can be
|
||||
modified by any project owner through the project console, `Projects` >
|
||||
`List` > my/project. In general, a submitted change is only merged if all
|
||||
its dependencies are also submitted, with exceptions documented below.
|
||||
The following submit types are supported:
|
||||
|
||||
[[submit_type_inherit]]
|
||||
* Inherit
|
||||
+
|
||||
This is the default for new projects, unless overridden by a global
|
||||
link:config-gerrit.html#repository.name.defaultSubmitType[`defaultSubmitType` option].
|
||||
+
|
||||
Inherit the submit type from the parent project. In `All-Projects`, this
|
||||
is equivalent to link:#merge_if_necessary[Merge If Necessary].
|
||||
|
||||
[[fast_forward_only]]
|
||||
* Fast Forward Only
|
||||
+
|
||||
With this method no merge commits are produced. All merges must
|
||||
be handled on the client, prior to uploading to Gerrit for review.
|
||||
+
|
||||
To submit a change, the change must be a strict superset of the
|
||||
destination branch. That is, the change must already contain the
|
||||
tip of the destination branch at submit time.
|
||||
|
||||
[[merge_if_necessary]]
|
||||
* Merge If Necessary
|
||||
+
|
||||
If the change being submitted is a strict superset of the destination
|
||||
branch, then the branch is fast-forwarded to the change. If not,
|
||||
then a merge commit is automatically created. This is identical
|
||||
to the classical `git merge` behavior, or `git merge --ff`.
|
||||
|
||||
[[always_merge]]
|
||||
* Always Merge
|
||||
+
|
||||
Always produce a merge commit, even if the change is a strict
|
||||
superset of the destination branch. This is identical to the
|
||||
behavior of `git merge --no-ff`, and may be useful if the
|
||||
project needs to follow submits with `git log --first-parent`.
|
||||
|
||||
[[cherry_pick]]
|
||||
* Cherry Pick
|
||||
+
|
||||
Always cherry pick the patch set, ignoring the parent lineage
|
||||
and instead creating a brand new commit on top of the current
|
||||
branch head.
|
||||
+
|
||||
When cherry picking a change, Gerrit automatically appends onto the
|
||||
end of the commit message a short summary of the change's approvals,
|
||||
and a URL link back to the change on the web. The committer header
|
||||
is also set to the submitter, while the author header retains the
|
||||
original patch set author.
|
||||
+
|
||||
Note that Gerrit ignores dependencies between changes when using this
|
||||
submit type unless
|
||||
link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`]
|
||||
is enabled and depending changes share the same topic. So generally
|
||||
submitters must remember to submit changes in the right order when using this
|
||||
submit type. If all you want is extra information in the commit message,
|
||||
consider using the Rebase Always submit strategy.
|
||||
|
||||
[[rebase_if_necessary]]
|
||||
* Rebase If Necessary
|
||||
+
|
||||
If the change being submitted is a strict superset of the destination
|
||||
branch, then the branch is fast-forwarded to the change. If not,
|
||||
then the change is automatically rebased and then the branch is
|
||||
fast-forwarded to the change.
|
||||
|
||||
When Gerrit tries to do a merge, by default the merge will only
|
||||
succeed if there is no path conflict. A path conflict occurs when
|
||||
the same file has also been changed on the other side of the merge.
|
||||
|
||||
[[rebase_always]]
|
||||
* Rebase Always
|
||||
+
|
||||
Basically, the same as Rebase If Necessary, but it creates a new patchset even
|
||||
if fast forward is possible AND like Cherry Pick it ensures footers such as
|
||||
Change-Id, Reviewed-On, and others are present in resulting commit that is
|
||||
merged.
|
||||
|
||||
Thus, Rebase Always can be considered similar to Cherry Pick, but with
|
||||
the important distinction that Rebase Always does not ignore dependencies.
|
||||
|
||||
[[content_merge]]
|
||||
If `Allow content merges` is enabled, Gerrit will try
|
||||
to do a content merge when a path conflict occurs.
|
||||
|
||||
@@ -209,7 +209,7 @@ verifications from a build server] before changes are merged. In
|
||||
addition you can benefit from Gerrit's merge strategies that can
|
||||
automatically merge/rebase commits on server side if necessary. You can
|
||||
control the merge strategy by configuring the
|
||||
link:project-configuration.html#submit_type[submit type] on the project. If you
|
||||
link:config-project-config.html#submit-type[submit type] on the project. If you
|
||||
bypass code review you always need to merge/rebase manually if the tip
|
||||
of the destination branch has moved. Please keep this in mind if you
|
||||
choose to not work with code review because you think it's easier to
|
||||
@@ -239,7 +239,7 @@ To see the options of your project:
|
||||
|
||||
An important decision for a project is the choice of the submit type
|
||||
and the content merge setting (see the `Allow content merges` option).
|
||||
The link:project-configuration.html#submit_type[submit type] is the method
|
||||
The link:config-project-config.html#submit-type[submit type] is the method
|
||||
Gerrit uses to submit a change to the project. The submit type defines
|
||||
what Gerrit should do on submit of a change if the destination branch
|
||||
has moved while the change was in review. The
|
||||
@@ -281,7 +281,7 @@ link:#prolog-submit-type[Prolog]. This way you can use different submit
|
||||
types for different branches.
|
||||
|
||||
Please note that there are other submit types available; they are
|
||||
described in the link:project-configuration.html#submit_type[Submit Type]
|
||||
described in the link:config-project-config.html#submit-type[Submit Type]
|
||||
section.
|
||||
|
||||
[[labels]]
|
||||
|
||||
@@ -383,7 +383,7 @@ rules] to control when a change becomes submittable.
|
||||
|
||||
How the code modification is applied to the target branch when a change
|
||||
is submitted is controlled by the
|
||||
link:project-configuration.html#submit_type[submit type] which can be
|
||||
link:config-project-config.html#submit-type[submit type] which can be
|
||||
link:intro-project-owner.html#submit-type[configured on project-level].
|
||||
|
||||
Submitting a change may fail with conflicts. In this case you need to
|
||||
|
||||
@@ -48,198 +48,7 @@ Either restart the server, or flush the `project_list` cache:
|
||||
[[project_options]]
|
||||
== Project Options
|
||||
|
||||
[[submit_type]]
|
||||
=== Submit Type
|
||||
|
||||
The method Gerrit uses to submit a change to a project can be
|
||||
modified by any project owner through the project console, `Projects` >
|
||||
`List` > my/project. In general, a submitted change is only merged if all
|
||||
its dependencies are also submitted, with exceptions documented below.
|
||||
The following submit types are supported:
|
||||
|
||||
[[submit_type_inherit]]
|
||||
* Inherit
|
||||
+
|
||||
This is the default for new projects, unless overridden by a global
|
||||
link:config-gerrit.html#repository.name.defaultSubmitType[`defaultSubmitType` option].
|
||||
+
|
||||
Inherit the submit type from the parent project. In `All-Projects`, this
|
||||
is equivalent to link:#merge_if_necessary[Merge If Necessary].
|
||||
|
||||
[[fast_forward_only]]
|
||||
* Fast Forward Only
|
||||
+
|
||||
With this method no merge commits are produced. All merges must
|
||||
be handled on the client, prior to uploading to Gerrit for review.
|
||||
+
|
||||
To submit a change, the change must be a strict superset of the
|
||||
destination branch. That is, the change must already contain the
|
||||
tip of the destination branch at submit time.
|
||||
|
||||
[[merge_if_necessary]]
|
||||
* Merge If Necessary
|
||||
+
|
||||
If the change being submitted is a strict superset of the destination
|
||||
branch, then the branch is fast-forwarded to the change. If not,
|
||||
then a merge commit is automatically created. This is identical
|
||||
to the classical `git merge` behavior, or `git merge --ff`.
|
||||
|
||||
[[always_merge]]
|
||||
* Always Merge
|
||||
+
|
||||
Always produce a merge commit, even if the change is a strict
|
||||
superset of the destination branch. This is identical to the
|
||||
behavior of `git merge --no-ff`, and may be useful if the
|
||||
project needs to follow submits with `git log --first-parent`.
|
||||
|
||||
[[cherry_pick]]
|
||||
* Cherry Pick
|
||||
+
|
||||
Always cherry pick the patch set, ignoring the parent lineage
|
||||
and instead creating a brand new commit on top of the current
|
||||
branch head.
|
||||
+
|
||||
When cherry picking a change, Gerrit automatically appends onto the
|
||||
end of the commit message a short summary of the change's approvals,
|
||||
and a URL link back to the change on the web. The committer header
|
||||
is also set to the submitter, while the author header retains the
|
||||
original patch set author.
|
||||
+
|
||||
Note that Gerrit ignores dependencies between changes when using this
|
||||
submit type unless
|
||||
link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`]
|
||||
is enabled and depending changes share the same topic. So generally
|
||||
submitters must remember to submit changes in the right order when using this
|
||||
submit type. If all you want is extra information in the commit message,
|
||||
consider using the Rebase Always submit strategy.
|
||||
|
||||
[[rebase_if_necessary]]
|
||||
* Rebase If Necessary
|
||||
+
|
||||
If the change being submitted is a strict superset of the destination
|
||||
branch, then the branch is fast-forwarded to the change. If not,
|
||||
then the change is automatically rebased and then the branch is
|
||||
fast-forwarded to the change.
|
||||
|
||||
When Gerrit tries to do a merge, by default the merge will only
|
||||
succeed if there is no path conflict. A path conflict occurs when
|
||||
the same file has also been changed on the other side of the merge.
|
||||
|
||||
[[rebase_always]]
|
||||
* Rebase Always
|
||||
+
|
||||
Basically, the same as Rebase If Necessary, but it creates a new patchset even
|
||||
if fast forward is possible AND like Cherry Pick it ensures footers such as
|
||||
Change-Id, Reviewed-On, and others are present in resulting commit that is
|
||||
merged.
|
||||
|
||||
Thus, Rebase Always can be considered similar to Cherry Pick, but with
|
||||
the important distinction that Rebase Always does not ignore dependencies.
|
||||
|
||||
[[content_merge]]
|
||||
If `Allow content merges` is enabled, Gerrit will try
|
||||
to do a content merge when a path conflict occurs.
|
||||
|
||||
[[project-state]]
|
||||
=== State
|
||||
|
||||
This setting defines the state of the project. A project can have the
|
||||
following states:
|
||||
|
||||
- `Active`:
|
||||
+
|
||||
The project is active and users can see and modify the project according
|
||||
to their access rights on the project.
|
||||
|
||||
- `Read Only`:
|
||||
+
|
||||
The project is read only and all modifying operations on it are
|
||||
disabled. E.g. this means that pushing to this project fails for all
|
||||
users even if they have push permissions assigned on it.
|
||||
+
|
||||
Setting a project to this state is an easy way to temporary close a
|
||||
project, as you can keep all write access rights in place and they will
|
||||
become active again as soon as the project state is set back to
|
||||
`Active`.
|
||||
+
|
||||
This state also makes sense if a project was moved to another location.
|
||||
In this case all new development should happen in the new project and
|
||||
you want to prevent that somebody accidentally works on the old
|
||||
project, while keeping the old project around for old references.
|
||||
|
||||
- `Hidden`:
|
||||
+
|
||||
The project is hidden and only visible to project owners. Other users
|
||||
are not able to see the project even if they have read permissions
|
||||
granted on the project.
|
||||
|
||||
=== Use target branch when determining new changes to open
|
||||
|
||||
The `create-new-change-for-all-not-in-target` option provides a
|
||||
convenience for selecting link:user-upload.html#base[the merge base]
|
||||
by setting it automatically to the target branch's tip so you can
|
||||
create new changes for all commits not in the target branch.
|
||||
|
||||
This option is disabled if the tip of the push is a merge commit.
|
||||
|
||||
This option also only works if there are no merge commits in the
|
||||
commit chain, in such cases it fails warning the user that such
|
||||
pushes can only be performed by manually specifying
|
||||
link:user-upload.html#base[bases]
|
||||
|
||||
This option is useful if you want to push a change to your personal
|
||||
branch first and for review to another branch for example. Or in cases
|
||||
where a commit is already merged into a branch and you want to create
|
||||
a new open change for that commit on another branch.
|
||||
|
||||
[[require-change-id]]
|
||||
=== Require Change-Id
|
||||
|
||||
The `Require Change-Id in commit message` option defines whether a
|
||||
link:user-changeid.html[Change-Id] in the commit message is required
|
||||
for pushing a commit for review. If this option is set, trying to push
|
||||
a commit for review that doesn't contain a Change-Id in the commit
|
||||
message fails with link:error-missing-changeid.html[missing Change-Id
|
||||
in commit message footer].
|
||||
|
||||
It is recommended to set this option and use a
|
||||
link:user-changeid.html#create[commit-msg hook] (or other client side
|
||||
tooling like EGit) to automatically generate Change-Id's for new
|
||||
commits. This way the Change-Id is automatically in place when changes
|
||||
are reworked or rebased and uploading new patch sets gets easy.
|
||||
|
||||
If this option is not set, commits can be uploaded without a Change-Id,
|
||||
but then users have to remember to copy the assigned Change-Id from the
|
||||
change screen and insert it manually into the commit message when they
|
||||
want to upload a second patch set.
|
||||
|
||||
=== Maximum Git Object Size Limit
|
||||
|
||||
This option defines the maximum allowed Git object size that
|
||||
receive-pack will accept. If an object is larger than the given size
|
||||
the pack-parsing will abort and the push operation will fail.
|
||||
|
||||
With this option users can be prevented from uploading commits that
|
||||
contain files which are too large.
|
||||
|
||||
Normally the link:config-gerrit.html#receive.maxObjectSizeLimit[maximum
|
||||
Git object size limit] is configured globally for a Gerrit server. At
|
||||
the project level, the maximum Git object size limit can be further
|
||||
reduced, but not extended. The displayed effective limit shows the
|
||||
maximum Git object size limit that is actually used on the project.
|
||||
|
||||
The defined maximum Git object size limit is inherited by any child
|
||||
project.
|
||||
|
||||
[[require-signed-off-by]]
|
||||
=== Require Signed-off-by
|
||||
|
||||
The `Require Signed-off-by in commit message` option defines whether a
|
||||
link:user-signedoffby.html[Signed-off-by] line in the commit message is
|
||||
required for pushing a commit. If this option is set, trying to push a
|
||||
commit that doesn't contain a Signed-off-by line in the commit message
|
||||
fails with link:error-not-signed-off-by.html[not Signed-off-by
|
||||
author/committer/uploader in commit message footer].
|
||||
See details at link:config-project-config.html#project-section[project section].
|
||||
|
||||
[[branch-admin]]
|
||||
== Branch Administration
|
||||
|
||||
@@ -5760,7 +5760,7 @@ change. The labels are lexicographically sorted.
|
||||
Whether the change was reviewed by the calling user.
|
||||
Only set if link:#reviewed[reviewed] is requested.
|
||||
|`submit_type` |optional|
|
||||
The link:project-configuration.html#submit_type[submit type] of the change. +
|
||||
The link:config-project-config.html#submit-type[submit type] of the change. +
|
||||
Not set for merged changes.
|
||||
|`mergeable` |optional|
|
||||
Whether the change is mergeable. +
|
||||
|
||||
@@ -3626,7 +3626,7 @@ statistics of a Git repository.
|
||||
|
||||
[[submit-type-info]]
|
||||
=== SubmitTypeInfo
|
||||
Information about the link:project-configuration.html#submit_type[default submit
|
||||
Information about the link:config-project-config.html#submit-type[default submit
|
||||
type of a project], taking into account project inheritance.
|
||||
|
||||
Valid values for each field are `MERGE_IF_NECESSARY`, `FAST_FORWARD_ONLY`,
|
||||
|
||||
Reference in New Issue
Block a user