Option to create a new change for every commit not in target
One not-so-well-known feature of gerrit is that, you can set a
%base for the RevWalk in ReceiveCommits when pushing changes to
Gerrit. This makes it possible to push a commit for review and
override Gerrits default algorithm for creating new changes on
push to refs/for/*. For instance, one could submit a commit in
a private branch and, afterward, push the same commit to a
release branch.
Specifying the tip of the destination branch as the %base would
have an effect of creating a new change for every commit reachable
from the pushed commit and not reachable from the target branch.
This behavior seems to be wanted by some Gerrit users and is
implemented as a project config option by this change (although
it contradicts the Gerrit's philosophy of reviewing one commit once).
If a %base is explicitly set on during uploading changes,
new-change-for-all-not-in-target is ignored.
To avoid incidental pushes with merges,
new-change-for-all-not-in-target rejects uploads if changes
contain merge commits. In such cases to push a merge commit, you
need to explicitly set the %base parameter as described in
Uploading Changes / Selecting Merge Base documentation.
Bug: issue 1195
Change-Id: Ifa90184352c912885e52d2060356fcc039d0ef03
diff --git a/Documentation/project-configuration.txt b/Documentation/project-configuration.txt
index 4b755f3..439fbc5 100644
--- a/Documentation/project-configuration.txt
+++ b/Documentation/project-configuration.txt
@@ -150,6 +150,25 @@
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
The `Require Change-Id in commit message` option defines whether a
