From: Junio C Hamano <gitster@pobox•com>
To: "Philip Oakley" <philipoakley@iee•org>
Cc: <git@vger•kernel.org>
Subject: Re: [PATCH 6/6] format-patch --notes: show notes after three-dashes
Date: Fri, 19 Oct 2012 13:06:30 -0700 [thread overview]
Message-ID: <7vzk3ii5vd.fsf@alter.siamese.dyndns.org> (raw)
In-Reply-To: <7vlif3l9fw.fsf@alter.siamese.dyndns.org> (Junio C. Hamano's message of "Thu, 18 Oct 2012 15:08:51 -0700")
Junio C Hamano <gitster@pobox•com> writes:
> As long as what it does is explained in format-patch, that is fine.
>
> I do not think this deserves to be in the SubmittingPatches. We do
> tell people to hide "here is the context of the change" additional
> explanation after three dashes, but how the submitters prepare that
> text is entirely up to them (and I personally do not think notes is
> not necessarily the right tool to do so).
Just in case, here is what I'll queue as a placeholder on 'pu'.
-- >8 --
Subject: [PATCH] Documentation: decribe format-patch --notes
Even though I coded this, I am not sure what use scenarios would benefit
from this option, so the description is unnecessarily negative at this
moment. People who do want to use this feature need to come up with a
more plausible use case and replace it.
Signed-off-by: Junio C Hamano <gitster@pobox•com>
---
Documentation/git-format-patch.txt | 15 ++++++++++++++-
1 file changed, 14 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 6d43f56..066dc8b 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -20,7 +20,7 @@ SYNOPSIS
[--ignore-if-in-upstream]
[--subject-prefix=Subject-Prefix]
[--to=<email>] [--cc=<email>]
- [--cover-letter] [--quiet]
+ [--cover-letter] [--quiet] [--notes[=<ref>]]
[<common diff options>]
[ <since> | <revision range> ]
@@ -191,6 +191,19 @@ will want to ensure that threading is disabled for `git send-email`.
containing the shortlog and the overall diffstat. You can
fill in a description in the file before sending it out.
+--notes[=<ref>]::
+ Append the notes (see linkgit:git-notes[1]) for the commit
+ after the three-dash line.
++
+The expected use case of this is to write supporting explanation for
+the commit that does not belong to the commit log message proper
+when (or after) you create the commit, and include it in your patch
+submission. But if you can plan ahead and write it down, there may
+not be a good reason not to write it in your commit message, and if
+you can't, you can always edit the output of format-patch before
+sending it out, so the practical value of this option is somewhat
+dubious, unless your workflow is broken.
+
--[no]-signature=<signature>::
Add a signature to each message produced. Per RFC 3676 the signature
is separated from the body by a line with '-- ' on it. If the
--
1.8.0.rc3.162.g1f53438
next prev parent reply other threads:[~2012-10-19 20:06 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-10-18 5:45 [PATCH 0/6] Bring "format-patch --notes" closer to a real feature Junio C Hamano
2012-10-18 5:45 ` [PATCH 1/6] pretty: remove reencode_commit_message() Junio C Hamano
2012-10-18 5:45 ` [PATCH 2/6] format_note(): simplify API Junio C Hamano
2012-10-18 5:45 ` [PATCH 3/6] pretty: prepare notes message at a centralized place Junio C Hamano
2012-10-18 7:49 ` Jeff King
2012-10-18 9:17 ` Junio C Hamano
2012-10-18 9:18 ` Jeff King
2012-10-18 10:00 ` [PATCH] strbuf: always return a non-NULL value from strbuf_detach Jeff King
2012-10-18 5:45 ` [PATCH 4/6] pretty_print_commit(): do not append notes message Junio C Hamano
2012-10-18 5:45 ` [PATCH 5/6] format-patch: append --signature after notes Junio C Hamano
2012-10-18 5:45 ` [PATCH 6/6] format-patch --notes: show notes after three-dashes Junio C Hamano
2012-10-18 21:35 ` Philip Oakley
2012-10-18 22:08 ` Junio C Hamano
2012-10-19 20:06 ` Junio C Hamano [this message]
2012-10-21 21:33 ` Philip Oakley
2012-10-18 10:02 ` [PATCH 0/6] Bring "format-patch --notes" closer to a real feature Jeff King
2012-10-18 11:06 ` Nguyen Thai Ngoc Duy
2012-10-18 12:24 ` Michael J Gruber
2012-10-18 17:04 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7vzk3ii5vd.fsf@alter.siamese.dyndns.org \
--to=gitster@pobox$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=philipoakley@iee$(echo .)org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox