From: Eric Blake <hidden> Date: 2016-06-15 22:55:03
Every so often, I search 'git send-email --help' to remember some
option I've used in the past, only to discover that the option is
documented instead in 'git format-patch --help'. Worse, even that
command didn't document the option I was looking for today, which
was how to include 'git notes' in the body of the commits I was
mailing. Reading 'git notes --help' didn't mention this either,
and I had to resort to searching the source code. It can't hurt
to add some documentation to make this option less obscure.
* 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.
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(-)
@@ -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[]+ CONFIGURATION ------------- You can specify extra mail header lines to be added to each message,
@@ -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.
@@ -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`. The header of the email is configurable by command line options. If not specified on the command line, the user will be prompted with a ReadLine
From: Jeff King <hidden> Date: 2016-06-15 22:55:03
On Tue, Oct 16, 2012 at 09:19:35PM -0600, Eric Blake wrote:
Every so often, I search 'git send-email --help' to remember some
option I've used in the past, only to discover that the option is
documented instead in 'git format-patch --help'. Worse, even that
command didn't document the option I was looking for today, which
was how to include 'git notes' in the body of the commits I was
mailing. Reading 'git notes --help' didn't mention this either,
and I had to resort to searching the source code. It can't hurt
to add some documentation to make this option less obscure.
I think this is a good direction, but...
* 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.
There are many things in pretty-options that would not be appropriate
for format-patch. We should probably wrap them like this:
@@ -27,6 +28,7 @@ people using 80-column terminals. --oneline:: This is a shorthand for "--pretty=oneline --abbrev-commit" used together.+endif::git-format-patch[] --encoding[=<encoding>]:: The commit objects record the encoding used for the log message
It may also make sense to show notes differently when outputting the
"email" format as format-patch does. E.g., using a triple-dash would
keep them separate from the commit message when using "git am". Like:
your commit message
Signed-off-by: You
---
your notes go here
We've talked about it several times, but it's never happened (probably
because most people don't actually use notes).
-Peff
From: Junio C Hamano <hidden> Date: 2016-06-15 22:55:03
Jeff King [off-list ref] wrote:
It may also make sense to show notes differently when outputting the
"email" format as format-patch does. E.g., using a triple-dash would
keep them separate from the commit message when using "git am". Like:
your commit message
Signed-off-by: You
---
your notes go here
We've talked about it several times, but it's never happened (probably
because most people don't actually use notes).
It is sometimes scary how we end up saying identical things independently :-)
From: Eric Blake <hidden> Date: 2016-06-15 22:55:03
On 10/16/2012 11:51 PM, Jeff King wrote:
It may also make sense to show notes differently when outputting the
"email" format as format-patch does. E.g., using a triple-dash would
keep them separate from the commit message when using "git am". Like:
your commit message
Signed-off-by: You
---
your notes go here
That's _precisely_ what I want! I want to use notes as a way of
tracking my edits for what I did in v2 of a patch, at the time I commit
my v2, so that I can send a revised series including the notes in a
manner most efficient for someone else using 'git am' on the series to
see why I sent a v2 but without polluting the upstream repository with
useless versioning information from the email.
We've talked about it several times, but it's never happened (probably
because most people don't actually use notes).
And people (like me) don't use notes because they aren't documented.
Catch-22, so we have to start somewhere.
I'll submit a v2 with the non-controversial edits, and spend some time
trying to figure out how to isolate the portion of pretty-options.txt
that is relevant to format-patch. If it's easy enough, I can also
consider using --- instead of Notes: as the separator when using
format-patch.
--
Eric Blake eblake@redhat.com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
From: Jeff King <hidden> Date: 2016-06-15 22:55:03
On Wed, Oct 17, 2012 at 07:30:56AM -0600, Eric Blake wrote:
quoted
We've talked about it several times, but it's never happened (probably
because most people don't actually use notes).
And people (like me) don't use notes because they aren't documented.
Catch-22, so we have to start somewhere.
Oh, I definitely agree your patch is the right direction. I was just
explaining why it hasn't happened, even though people think it's a good
idea.
I'll submit a v2 with the non-controversial edits, and spend some time
trying to figure out how to isolate the portion of pretty-options.txt
that is relevant to format-patch. If it's easy enough, I can also
consider using --- instead of Notes: as the separator when using
format-patch.
From: Michael J Gruber <hidden> Date: 2016-06-15 22:55:04
Jeff King venit, vidit, dixit 17.10.2012 21:05:
On Wed, Oct 17, 2012 at 07:30:56AM -0600, Eric Blake wrote:
quoted
quoted
We've talked about it several times, but it's never happened (probably
because most people don't actually use notes).
And people (like me) don't use notes because they aren't documented.
Catch-22, so we have to start somewhere.
Oh, I definitely agree your patch is the right direction. I was just
explaining why it hasn't happened, even though people think it's a good
idea.
quoted
I'll submit a v2 with the non-controversial edits, and spend some time
trying to figure out how to isolate the portion of pretty-options.txt
that is relevant to format-patch. If it's easy enough, I can also
consider using --- instead of Notes: as the separator when using
format-patch.
That one used to work for about one more year or so (it went through a
few rebases) but stopped working during some rework involving the
signature (signed-off-by), i.e. it puts the notes before the signed-off
now. I didn't update it because nobody seemed interested anyway (and
because branch-notes got implemented in a different, non-note way, so I
dumped that part of my workflow also).
Michael