Eric Blake <ebl...@redhat.com> 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 <ebl...@redhat.com> > --- > 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 <aut...@example.com> 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 <gits...@pobox.com> 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. > 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. > +To change which notes are shown by default in 'git log', see the > +"notes.displayRef" configuration in linkgit:git-log. Also, > +many commands understand a `--notes` option to alter the set of > +notes displayed (see linkgit:git-rev-list). > > See the "notes.rewrite.<command>" configuration for a way to carry > notes across commands that rewrite commits. OK. > 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 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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html