From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: git@vger.kernel.org
Cc: "Junio C Hamano" <gitster@pobox.com>,
"Matheus Tavares" <matheus.bernardino@usp.br>,
"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Subject: [PATCH v3 5/9] notes docs: de-duplicate and combine configuration sections
Date: Wed, 31 Aug 2022 10:41:36 +0200 [thread overview]
Message-ID: <patch-v3-5.9-5b0ea00aa33-20220831T083759Z-avarab@gmail.com> (raw)
In-Reply-To: <cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com>
Combine the various "notes" configuration sections spread across
Documentation/config/notes.txt and Documentation/git-notes.txt to live
in the former, and to be included in the latter.
We'll now forward link from "git notes" to the "CONFIGURATION" section
below, rather than to "git-config(1)" when discussing configuration
variables that are (also) discussed in that section.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/notes.txt | 43 +++++++++++++++-----------
Documentation/git-log.txt | 16 ++--------
Documentation/git-notes.txt | 55 +++-------------------------------
3 files changed, 33 insertions(+), 81 deletions(-)
diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt
index aeef56d49ae..c7c4811734b 100644
--- a/Documentation/config/notes.txt
+++ b/Documentation/config/notes.txt
@@ -3,6 +3,9 @@ notes.mergeStrategy::
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.
++
+This setting can be overridden by passing the `--strategy` option to
+linkgit:git-notes[1].
notes.<name>.mergeStrategy::
Which merge strategy to choose when doing a notes merge into
@@ -11,28 +14,35 @@ notes.<name>.mergeStrategy::
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.
+ 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 with the `GIT_NOTES_DISPLAY_REF`
environment variable, which must be a colon separated list of refs or
globs.
+
+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 disabled by the `--no-notes` option to the 'git
+log' family of commands, or by the `--notes=<ref>` option accepted by
+those commands.
++
The effective value of "core.notesRef" (possibly overridden by
GIT_NOTES_REF) is also implicitly added to the list of refs to be
displayed.
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 with the `GIT_NOTES_REWRITE_REF`
+environment variable, which must be a colon separated list of refs or
+globs.
notes.rewriteMode::
When copying notes during a rewrite (see the
@@ -46,14 +56,13 @@ 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.
+See `notes.rewrite.<command>` above for a further description of its format.
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index b1285aee3c2..410095e9a4f 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -237,19 +237,9 @@ log.showSignature::
mailmap.*::
See linkgit:git-shortlog[1].
-notes.displayRef::
- Which refs, in addition to the default set by `core.notesRef`
- or `GIT_NOTES_REF`, to read notes from when showing commit
- messages with the `log` family of commands. See
- linkgit:git-notes[1].
-+
-May be an unabbreviated ref name or a glob and may be specified
-multiple 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 disabled by the `--no-notes` option,
-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,
-and overridden by the `--notes=<ref>` option.
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/notes.txt[]
GIT
---
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 0a4200674c4..efbc10f0f59 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary
after a three dash separator line.
To change which notes are shown by 'git log', see the
-"notes.displayRef" configuration in linkgit:git-log[1].
+"notes.displayRef" discussion in <<CONFIGURATION>>.
See the "notes.rewrite.<command>" configuration for a way to carry
notes across commands that rewrite commits.
@@ -307,6 +307,7 @@ with 'git log', so if you use such notes, you'll probably need to write
some special-purpose tools to do something useful with them.
+[[CONFIGURATION]]
CONFIGURATION
-------------
@@ -316,57 +317,9 @@ 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.
+include::includes/cmd-config-section-rest.txt[]
-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.
+include::config/notes.txt[]
ENVIRONMENT
--
2.37.3.1406.g184357183a6
next prev parent reply other threads:[~2022-08-31 8:42 UTC|newest]
Thread overview: 56+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-07-14 17:44 [PATCH 0/3] doc: unify config info on some cmds Matheus Tavares
2022-07-14 17:44 ` [PATCH 1/3] doc: grep: unify configuration variables definitions Matheus Tavares
2022-07-14 18:46 ` Junio C Hamano
2022-07-14 17:44 ` [PATCH 2/3] doc: apply: " Matheus Tavares
2022-07-14 18:48 ` Junio C Hamano
2022-07-14 17:44 ` [PATCH 3/3] doc: notes: " Matheus Tavares
2022-07-14 19:45 ` Junio C Hamano
2022-07-14 21:17 ` [PATCH 0/3] doc: unify config info on some cmds Ævar Arnfjörð Bjarmason
2022-07-15 19:58 ` Matheus Tavares
2022-07-16 7:53 ` Ævar Arnfjörð Bjarmason
2022-07-17 17:13 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
2022-07-29 8:25 ` [PATCH v2 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
2022-07-30 13:29 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 2/9] grep docs: de-duplicate configuration sections Ævar Arnfjörð Bjarmason
2022-07-30 13:31 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 3/9] send-email " Ævar Arnfjörð Bjarmason
2022-07-30 13:45 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 4/9] apply " Ævar Arnfjörð Bjarmason
2022-07-30 13:50 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 5/9] notes " Ævar Arnfjörð Bjarmason
2022-07-30 20:02 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 6/9] difftool " Ævar Arnfjörð Bjarmason
2022-07-30 14:09 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 7/9] log " Ævar Arnfjörð Bjarmason
2022-07-30 18:52 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 8/9] docs: add CONFIGURATION sections that map to a built-in Ævar Arnfjörð Bjarmason
2022-07-29 21:58 ` Junio C Hamano
2022-07-29 8:25 ` [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins Ævar Arnfjörð Bjarmason
2022-07-29 22:03 ` Junio C Hamano
2022-07-30 19:08 ` Matheus Tavares
2022-07-30 20:44 ` Junio C Hamano
2022-07-30 20:05 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Matheus Tavares
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 2/9] grep docs: de-duplicate configuration sections Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 3/9] send-email " Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 4/9] apply " Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` Ævar Arnfjörð Bjarmason [this message]
2022-08-31 8:41 ` [PATCH v3 6/9] difftool " Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 7/9] log " Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 8/9] docs: add CONFIGURATION sections that map to a built-in Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins Ævar Arnfjörð Bjarmason
2022-09-03 13:29 ` [PATCH v3 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Matheus Tavares
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
2022-09-07 8:26 ` [PATCH v4 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
2022-09-07 8:26 ` [PATCH v4 2/9] grep docs: de-duplicate configuration sections Ævar Arnfjörð Bjarmason
2022-09-07 8:26 ` [PATCH v4 3/9] send-email " Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 4/9] apply " Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 5/9] notes docs: de-duplicate and combine " Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 6/9] difftool docs: de-duplicate " Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 7/9] log " Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 8/9] docs: add CONFIGURATION sections that map to a built-in Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins Ævar Arnfjörð Bjarmason
2022-09-07 11:51 ` [PATCH v4 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Matheus Tavares
2022-09-07 16:45 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=patch-v3-5.9-5b0ea00aa33-20220831T083759Z-avarab@gmail.com \
--to=avarab@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=matheus.bernardino@usp.br \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).