Re: [PATCH] notes: mention --notes in more places

[Jeff King <peff@peff.net>]

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:

diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index 5e49942..a0f1d15 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -1,3 +1,4 @@
+ifndef::git-format-patch[]
 --pretty[=<format>]::
 --format=<format>::
 
@@ -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