diff mbox series

[3/3] doc: notes: unify configuration variables definitions

Message ID d39e826756e79ce7fe270175ad0d5ae523528af9.1657819649.git.matheus.bernardino@usp.br (mailing list archive)
State New, archived
Headers show
Series doc: unify config info on some cmds | expand

Commit Message

Matheus Tavares July 14, 2022, 5:44 p.m. UTC 
Unify duplicated configuration descriptions from git-notes.txt and
config.txt in order to facilitate maintenance and update. There are some
discrepancies between these two files: git-notes.txt received two
updates that were not made in config.txt: see 66c4c32
("Documentation/notes: simplify treatment of default display refs",
2010-05-08) and c5ce183 ("Documentation/notes: clean up description of
rewriting configuration", 2010-05-08 ). And there was also an update to
config.txt not propagated to git-notes.txt: see 2b4aa89 ("Documentation:
basic configuration of notes.rewriteRef", 2011-09-13). Let's make sure
to include all these three updates in the unified version.

Signed-off-by: Matheus Tavares <matheus.bernardino@usp.br>
---
 Documentation/config/notes.txt | 62 ++++++++++++++++------------------
 Documentation/git-notes.txt    | 54 ++---------------------------
 2 files changed, 31 insertions(+), 85 deletions(-)

Comments

Junio C Hamano July 14, 2022, 7:45 p.m. UTC | #1 
Matheus Tavares <matheus.bernardino@usp.br> writes:

>  	`cat_sort_uniq`.  Defaults to `manual`.  See "NOTES MERGE STRATEGIES"
> -	section of linkgit:git-notes[1] for more information on each strategy.
> +	section
> +ifdef::git-notes[above]
> +ifndef::git-notes[of linkgit:git-notes[1]]
> +	for more information on each strategy.

This is the first use of the single line ifdef/ifndef in our
Documentation.  I assume you have verified the rendered output on
both AsciiDoc and AsciiDoctor?

> -	"notes.mergeStrategy".  See the "NOTES MERGE STRATEGIES" section in
> -	linkgit:git-notes[1] for more information on the available strategies.
> +	"notes.mergeStrategy".  See the "NOTES MERGE STRATEGIES" section
> +ifdef::git-notes[above]
> +ifndef::git-notes[in linkgit:git-notes[1]]
> +	for more information on the available strategies.

Ditto.

>  notes.displayRef::
> -	The (fully qualified) refname from which to show notes when
> -	showing commit messages.  The value of this variable can be set
> -	to a glob, in which case notes from all matching refs will be
> -	shown.  You may also specify this configuration variable
> -	several times.  A warning will be issued for refs that do not
> -	exist, but a glob that does not match any refs is silently
> -	ignored.
> -+
> -This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
> -environment variable, which must be a colon separated list of refs or
> -globs.
> -+
> -The effective value of "core.notesRef" (possibly overridden by
> -GIT_NOTES_REF) is also implicitly added to the list of refs to be
> -displayed.
> +	Which ref (or refs, if a glob or specified more than once), in
> +	addition to the default set by `core.notesRef` or
> +	`GIT_NOTES_REF`, to read notes from when showing commit
> +	messages with the 'git log' family of commands.
> +	This setting can be overridden on the command line or by the
> +	`GIT_NOTES_DISPLAY_REF` environment variable.
> +	See linkgit:git-log[1].

This is unrelated to the "unify description in git-foo.txt and
config/foo.txt in the documentation" topic, isn't it?

I haven't formed an opinion on the updated text, and it makes it
harder to review when the content change is mixed in the "unify
description in two places" topic, so I won't comment on the change
of the contents.  Please split them into two steps (a step with only
content change, and then another step to remove the duplicated one
by making one include the other).  Same comment applies to [2/3].

>  notes.rewrite.<command>::
>  	When rewriting commits with <command> (currently `amend` or
> -	`rebase`) and this variable is set to `true`, Git
> -	automatically copies your notes from the original to the
> -	rewritten commit.  Defaults to `true`, but see
> -	"notes.rewriteRef" below.
> +	`rebase`), if this variable is `false`, git will not copy
> +	notes from the original to the rewritten commit.  Defaults to
> +	`true`.  See also "`notes.rewriteRef`" below.
> ++
> +This setting can be overridden by the `GIT_NOTES_REWRITE_REF`
> +environment variable.

Ditto.

>  notes.rewriteMode::
> -	When copying notes during a rewrite (see the
> -	"notes.rewrite.<command>" option), determines what to do if
> -	the target commit already has a note.  Must be one of
> -	`overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.
> -	Defaults to `concatenate`.
> +	When copying notes during a rewrite, what to do if the target
> +	commit already has a note.  Must be one of `overwrite`,
> +	`concatenate`, `cat_sort_uniq`, or `ignore`.  Defaults to
> +	`concatenate`.
>  +
>  This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
>  environment variable.

We are losing the mention of "notes.rewrite.<command>", which is
outside the "unify" topic, isn't it?

>  notes.rewriteRef::
>  	When copying notes during a rewrite, specifies the (fully
> -	qualified) ref whose notes should be copied.  The ref may be a
> -	glob, in which case notes in all matching refs will be copied.
> -	You may also specify this configuration several times.
> +	qualified) ref whose notes should be copied.  May be a glob,
> +	in which case notes in all matching refs will be copied.  You
> +	may also specify this configuration several times.
>  +
>  Does not have a default value; you must configure this variable to
>  enable note rewriting.  Set it to `refs/notes/commits` to enable
>  rewriting for the default commit notes.
>  +
> -This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
> -environment variable, which must be a colon separated list of refs or
> -globs.
> +Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.

Ditto.

Thanks.
diff mbox series

Patch

diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt
index aeef56d49a..552b340987 100644
--- a/Documentation/config/notes.txt
+++ b/Documentation/config/notes.txt
@@ -2,58 +2,54 @@  notes.mergeStrategy::
 	Which merge strategy to choose by default when resolving notes
 	conflicts.  Must be one of `manual`, `ours`, `theirs`, `union`, or
 	`cat_sort_uniq`.  Defaults to `manual`.  See "NOTES MERGE STRATEGIES"
-	section of linkgit:git-notes[1] for more information on each strategy.
+	section
+ifdef::git-notes[above]
+ifndef::git-notes[of linkgit:git-notes[1]]
+	for more information on each strategy.
 
 notes.<name>.mergeStrategy::
 	Which merge strategy to choose when doing a notes merge into
 	refs/notes/<name>.  This overrides the more general
-	"notes.mergeStrategy".  See the "NOTES MERGE STRATEGIES" section in
-	linkgit:git-notes[1] for more information on the available strategies.
+	"notes.mergeStrategy".  See the "NOTES MERGE STRATEGIES" section
+ifdef::git-notes[above]
+ifndef::git-notes[in linkgit:git-notes[1]]
+	for more information on the available strategies.
 
 notes.displayRef::
-	The (fully qualified) refname from which to show notes when
-	showing commit messages.  The value of this variable can be set
-	to a glob, in which case notes from all matching refs will be
-	shown.  You may also specify this configuration variable
-	several times.  A warning will be issued for refs that do not
-	exist, but a glob that does not match any refs is silently
-	ignored.
-+
-This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
-environment variable, which must be a colon separated list of refs or
-globs.
-+
-The effective value of "core.notesRef" (possibly overridden by
-GIT_NOTES_REF) is also implicitly added to the list of refs to be
-displayed.
+	Which ref (or refs, if a glob or specified more than once), in
+	addition to the default set by `core.notesRef` or
+	`GIT_NOTES_REF`, to read notes from when showing commit
+	messages with the 'git log' family of commands.
+	This setting can be overridden on the command line or by the
+	`GIT_NOTES_DISPLAY_REF` environment variable.
+	See linkgit:git-log[1].
 
 notes.rewrite.<command>::
 	When rewriting commits with <command> (currently `amend` or
-	`rebase`) and this variable is set to `true`, Git
-	automatically copies your notes from the original to the
-	rewritten commit.  Defaults to `true`, but see
-	"notes.rewriteRef" below.
+	`rebase`), if this variable is `false`, git will not copy
+	notes from the original to the rewritten commit.  Defaults to
+	`true`.  See also "`notes.rewriteRef`" below.
++
+This setting can be overridden by the `GIT_NOTES_REWRITE_REF`
+environment variable.
 
 notes.rewriteMode::
-	When copying notes during a rewrite (see the
-	"notes.rewrite.<command>" option), determines what to do if
-	the target commit already has a note.  Must be one of
-	`overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.
-	Defaults to `concatenate`.
+	When copying notes during a rewrite, what to do if the target
+	commit already has a note.  Must be one of `overwrite`,
+	`concatenate`, `cat_sort_uniq`, or `ignore`.  Defaults to
+	`concatenate`.
 +
 This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
 environment variable.
 
 notes.rewriteRef::
 	When copying notes during a rewrite, specifies the (fully
-	qualified) ref whose notes should be copied.  The ref may be a
-	glob, in which case notes in all matching refs will be copied.
-	You may also specify this configuration several times.
+	qualified) ref whose notes should be copied.  May be a glob,
+	in which case notes in all matching refs will be copied.  You
+	may also specify this configuration several times.
 +
 Does not have a default value; you must configure this variable to
 enable note rewriting.  Set it to `refs/notes/commits` to enable
 rewriting for the default commit notes.
 +
-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
-environment variable, which must be a colon separated list of refs or
-globs.
+Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 0a4200674c..79b2c60646 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -316,58 +316,8 @@  core.notesRef::
 	This setting can be overridden through the environment and
 	command line.
 
-notes.mergeStrategy::
-	Which merge strategy to choose by default when resolving notes
-	conflicts.  Must be one of `manual`, `ours`, `theirs`, `union`, or
-	`cat_sort_uniq`.  Defaults to `manual`.  See "NOTES MERGE STRATEGIES"
-	section above for more information on each strategy.
-+
-This setting can be overridden by passing the `--strategy` option.
-
-notes.<name>.mergeStrategy::
-	Which merge strategy to choose when doing a notes merge into
-	refs/notes/<name>.  This overrides the more general
-	"notes.mergeStrategy".  See the "NOTES MERGE STRATEGIES" section above
-	for more information on each available strategy.
-
-notes.displayRef::
-	Which ref (or refs, if a glob or specified more than once), in
-	addition to the default set by `core.notesRef` or
-	`GIT_NOTES_REF`, to read notes from when showing commit
-	messages with the 'git log' family of commands.
-	This setting can be overridden on the command line or by the
-	`GIT_NOTES_DISPLAY_REF` environment variable.
-	See linkgit:git-log[1].
-
-notes.rewrite.<command>::
-	When rewriting commits with <command> (currently `amend` or
-	`rebase`), if this variable is `false`, git will not copy
-	notes from the original to the rewritten commit.  Defaults to
-	`true`.  See also "`notes.rewriteRef`" below.
-+
-This setting can be overridden by the `GIT_NOTES_REWRITE_REF`
-environment variable.
-
-notes.rewriteMode::
-	When copying notes during a rewrite, what to do if the target
-	commit already has a note.  Must be one of `overwrite`,
-	`concatenate`, `cat_sort_uniq`, or `ignore`.  Defaults to
-	`concatenate`.
-+
-This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
-environment variable.
-
-notes.rewriteRef::
-	When copying notes during a rewrite, specifies the (fully
-	qualified) ref whose notes should be copied.  May be a glob,
-	in which case notes in all matching refs will be copied.  You
-	may also specify this configuration several times.
-+
-Does not have a default value; you must configure this variable to
-enable note rewriting.
-+
-Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
-
+:git-notes: 1
+include::config/notes.txt[]
 
 ENVIRONMENT
 -----------