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

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