Eric Blake <> 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.

> Signed-off-by: Eric Blake <>
> ---
>  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:

    ... enclose everything that should not be used with format-patch

to the included file, and then define the token before the
inclusion, like this:

    :git-format-patch: 1

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

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 <>
        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 <>

                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.

> 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.


> 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.
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to
More majordomo info at

Reply via email to