Re: [PATCH] notes: mention --notes in more places
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:55:03
Eric Blake [off-list ref] writes:
* git-notes.txt: Mention that --notes option exists in many commands to override defaults. * git-format-patch.txt: Include pretty-options, for things like --notes. * git-send-email.txt: Mention that revision lists forwarded to format-patch can also include options.
Overall I feel fairly negative on this one, even though there are good bits.
quoted hunk
Signed-off-by: Eric Blake <redacted> --- Documentation/git-format-patch.txt | 2 ++ Documentation/git-notes.txt | 6 ++++-- Documentation/git-send-email.txt | 3 ++- 3 files changed, 8 insertions(+), 3 deletions(-)diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 6d43f56..a068f37 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt@@ -222,6 +222,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. range are always formatted as creation patches, independently of this flag. +include::pretty-options.txt[]
In the context of format-patch, the inclusion of pretty-options
probably causes more harm than being helpful, I am afraid. If you
use "--pretty=<format>", "--format=<format>", or "--oneline", the
output will no longer be a proper mbox and is not suitable for
asking somebody else to apply.
At the very least, you would need to add something like:
ifndef::git-format-patch[]
... enclose everything that should not be used with format-patch
endif::git-format-patch[]
to the included file, and then define the token before the
inclusion, like this:
:git-format-patch: 1
include::pretty-formats.txt[]
to limit the damage.
Even with such a change to include only --notes, I am not sure if
the result is something we would want to recommend/advertise to our
users.
The output from format-patch with --notes shows the notes, after
adding a blank line to the sign-off block, to look like this:
From: A U Thor [off-list ref]
Date: Tue, 16 Oct 2012 19:26:23 +0200
Subject: [PATCH] Gostak: distim the doshes correctly
With the current code, the Gostak cannot correctly distim
the doshes, because ...
Signed-off-by: Junio C Hamano [off-list ref]
Notes:
This patch was inspired by Eric Blake
---
diff --git a/gostak b/gostak
...
I am not sure if this is suiable for sending to somebody and asking
it to be applied.
quoted hunk
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index b95aafa..be9e60f 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt@@ -39,8 +39,10 @@ message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes (<refname>):" (or "Notes:" for `refs/notes/commits`). -To change which notes are shown by 'git log', see the -"notes.displayRef" configuration in linkgit:git-log[1]. +To change which notes are shown by default in 'git log', see the +"notes.displayRef" configuration in linkgit:git-log[1]. Also, +many commands understand a `--notes` option to alter the set of +notes displayed (see linkgit:git-rev-list[1]). See the "notes.rewrite.<command>" configuration for a way to carry notes across commands that rewrite commits.
OK.
quoted hunk
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index eeb561c..450d975 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt@@ -18,7 +18,8 @@ Takes the patches given on the command line and emails them out. Patches can be specified as files, directories (which will send all files in the directory), or directly as a revision list. In the last case, any format accepted by linkgit:git-format-patch[1] can -be passed to git send-email. +be passed to git send-email, including additional command line +options such as `--cover-letter` or `--notes`.
OK for --cover-letter, dubious on --notes.