Re: [PATCH] Documentation/SubmittingPatches: add quotes to advised commit reference

[Michael J Gruber <git@drmicha.warpmail.net>]

Junio C Hamano venit, vidit, dixit 27.08.2016 00:42:
> Stefan Beller <sbeller@google.com> writes:
> 
>> Junio finds it is easier to read text when the commit subject is quoted.
>>
>> Signed-off-by: Stefan Beller <sbeller@google.com>
>> ---
>>  Documentation/SubmittingPatches | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>> index 500230c..a591229 100644
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -123,7 +123,7 @@ archive, summarize the relevant points of the discussion.
>>  
>>  If you want to reference a previous commit in the history of a stable
>>  branch use the format "abbreviated sha1 (subject, date)". So for example
>> -like this: "Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
>> +like this: "Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
>>  noticed [...]".
> 
> Thanks, but it is not sufficient as you would not see the need for
> quoting without the example.
> 
> My preference is not a main deciding factor in this case anyway.  A
> more important reason why it makes sense to quote (aside from the
> fact that it makes more sense when reading) is because we already
> have a tool support for that.
> 
> Perhaps something like this instead?
> 
> -- >8 --
> From: Beat Bolli <dev+git@drbeat.li>
> Subject: SubmittingPatches: use gitk's "Copy commit summary" format
> Date: Fri, 26 Aug 2016 18:59:01 +0200
> 
> Update the suggestion in 175d38ca ("SubmittingPatches: document how
> to reference previous commits", 2016-07-28) on the format to refer
> to a commit to match what gitk has been giving since last year with
> its "Copy commit summary" command; also mention this as one of the
> ways to obtain a commit reference in this format.
> 
> Signed-off-by: Beat Bolli <dev+git@drbeat.li>
> ---
>  Documentation/SubmittingPatches | 11 ++++++++---
>  1 file changed, 8 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 500230c..15adb86 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -122,9 +122,14 @@ without external resources. Instead of giving a URL to a mailing list
>  archive, summarize the relevant points of the discussion.
>  
>  If you want to reference a previous commit in the history of a stable
> -branch use the format "abbreviated sha1 (subject, date)". So for example
> -like this: "Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
> -noticed [...]".
> +branch, use the format "abbreviated sha1 (subject, date)",
> +with the subject enclosed in a pair of double-quotes, like this:
> +
> +    Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
> +    noticed that ...
> +
> +The "Copy commit summary" command of gitk can be used to obtain this
> +format.

or (an alias for) the command

git show -s --date=format:%F --pretty='tformat:%h ("%s", %ad)'

>  
>  (3) Generate your patch using Git tools out of your commits.
>