Re: [PATCH v2] Add note that conflict resolution is still performed

[Junio C Hamano <gitster@pobox.com>]

Matthias Beyer <mail@beyermatthias.de> writes:

> We should note that conflict resolution is still performed, even if
> `--no-rerere-autoupdate` is specified, to make sure users do not get
> confused by the setting and assume this disables rerere conflict
> resultion altogether.
>
> CC: Phillip Wood <phillip.wood@dunelm.org.uk>
> CC: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Matthias Beyer <mail@beyermatthias.de>
> ---
>  Documentation/git-cherry-pick.txt | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
> index 78dcc9171f..b92aa1f9da 100644
> --- a/Documentation/git-cherry-pick.txt
> +++ b/Documentation/git-cherry-pick.txt
> @@ -160,6 +160,10 @@ effect to your index in a row.
>  --no-rerere-autoupdate::
>  	Allow the rerere mechanism to update the index with the
>  	result of auto-conflict resolution if possible.
> +	The `--no-rerere-autoupdate` option does not prevent the conflict
> +	resolution, but prevents the index from being updated. This gives the
> +	user a chance for a final sanity check before using linkgit:git-add[1]
> +	to add the result.

$ git grep -l "^--rerere-autoupdate::" Documentation
Documentation/git-am.txt
Documentation/git-cherry-pick.txt
Documentation/git-merge.txt
Documentation/git-rebase.txt
Documentation/git-revert.txt

I made a cursory scan of these and I suspect the existing two-line
description are shread among all of them.  At this point it may make
sense to split the description to a separate file to be included by
these places (the attached patch may be a starting point) in a
patch, and then follow up with the text change in a follow-up patch.

A tangent that may be worth thinking about, that does not have to be
part of this topic (as it probably will involve code change).

It makes sense that "--no-rerere-autoupdate" does not disable the
"rerere" mechanism (when it is enabled, of course), because it makes
sense to reuse recorded resolution without updating the index with
the result.

However, it may make sense to have "--rerere-autoupdate" option to
enable the "rerere" mechanism when it is disabled, because with
"rerere" disabled, there is nothing to auto-update.

Anyway, here is the preliminary restructuring patch.

----- >8 --------- >8 --------- >8 --------- >8 --------- >8 -----
Subject: [PATCH] doc: consolidate --rerere-autoupdate description

The `--rerere-autoupdate` option is shared across 5 commands, and
are described the same way because it works exactly the same way in
these commands.

Create a separate file and include it from the help pages for these
commands, so that we can improve the description at one place to
improve all of them at once, and keep them in sync.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-am.txt          | 5 +----
 Documentation/git-cherry-pick.txt | 5 +----
 Documentation/git-merge.txt       | 5 +----
 Documentation/git-rebase.txt      | 5 +----
 Documentation/git-revert.txt      | 5 +----
 Documentation/rerere-options.txt  | 4 ++++
 6 files changed, 9 insertions(+), 20 deletions(-)

diff --git c/Documentation/git-am.txt w/Documentation/git-am.txt
index 09107fb106..320da6c4f7 100644
--- c/Documentation/git-am.txt
+++ w/Documentation/git-am.txt
@@ -112,10 +112,7 @@ default.   You can use `--no-utf8` to override this.
 	am.threeWay configuration variable. For more information,
 	see am.threeWay in linkgit:git-config[1].
 
---rerere-autoupdate::
---no-rerere-autoupdate::
-	Allow the rerere mechanism to update the index with the
-	result of auto-conflict resolution if possible.
+include::rerere-options.txt[]
 
 --ignore-space-change::
 --ignore-whitespace::
diff --git c/Documentation/git-cherry-pick.txt w/Documentation/git-cherry-pick.txt
index 78dcc9171f..1e8ac9df60 100644
--- c/Documentation/git-cherry-pick.txt
+++ w/Documentation/git-cherry-pick.txt
@@ -156,10 +156,7 @@ effect to your index in a row.
 	Pass the merge strategy-specific option through to the
 	merge strategy.  See linkgit:git-merge[1] for details.
 
---rerere-autoupdate::
---no-rerere-autoupdate::
-	Allow the rerere mechanism to update the index with the
-	result of auto-conflict resolution if possible.
+include::rerere-options.txt[]
 
 SEQUENCER SUBCOMMANDS
 ---------------------
diff --git c/Documentation/git-merge.txt w/Documentation/git-merge.txt
index 3125473cc1..fee1dc2df2 100644
--- c/Documentation/git-merge.txt
+++ w/Documentation/git-merge.txt
@@ -90,10 +90,7 @@ invocations. The automated message can include the branch description.
 If `--log` is specified, a shortlog of the commits being merged
 will be appended to the specified message.
 
---rerere-autoupdate::
---no-rerere-autoupdate::
-	Allow the rerere mechanism to update the index with the
-	result of auto-conflict resolution if possible.
+include::rerere-options.txt[]
 
 --overwrite-ignore::
 --no-overwrite-ignore::
diff --git c/Documentation/git-rebase.txt w/Documentation/git-rebase.txt
index a872ab0fbd..ff0b643ec0 100644
--- c/Documentation/git-rebase.txt
+++ w/Documentation/git-rebase.txt
@@ -376,10 +376,7 @@ See also INCOMPATIBLE OPTIONS below.
 +
 See also INCOMPATIBLE OPTIONS below.
 
---rerere-autoupdate::
---no-rerere-autoupdate::
-	Allow the rerere mechanism to update the index with the
-	result of auto-conflict resolution if possible.
+include::rerere-options.txt[]
 
 -S[<keyid>]::
 --gpg-sign[=<keyid>]::
diff --git c/Documentation/git-revert.txt w/Documentation/git-revert.txt
index 8463fe9cf7..0105a54c1a 100644
--- c/Documentation/git-revert.txt
+++ w/Documentation/git-revert.txt
@@ -112,10 +112,7 @@ effect to your index in a row.
 	Pass the merge strategy-specific option through to the
 	merge strategy.  See linkgit:git-merge[1] for details.
 
---rerere-autoupdate::
---no-rerere-autoupdate::
-	Allow the rerere mechanism to update the index with the
-	result of auto-conflict resolution if possible.
+include::rerere-options.txt[]
 
 --reference::
 	Instead of starting the body of the log message with "This
diff --git c/Documentation/rerere-options.txt w/Documentation/rerere-options.txt
new file mode 100644
index 0000000000..8f4849e272
--- /dev/null
+++ w/Documentation/rerere-options.txt
@@ -0,0 +1,4 @@
+--rerere-autoupdate::
+--no-rerere-autoupdate::
+	Allow the rerere mechanism to update the index with the
+	result of auto-conflict resolution if possible.