Re: [PATCH] clean up confusing suggestion for commit references

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 10, 2016, 18:15 UTC
Message-ID: <xmqqlgxwf4us.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20161007095638.GA55445@book.hvoigt.net>

Heiko Voigt <hvoigt@hvoigt.net> writes:

Show 6 quoted lines

>  If you want to reference a previous commit in the history of a stable
> -branch, use the format "abbreviated sha1 (subject, date)",
> +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)

As long as the "like this" example is there close to the sentence "use the format ...", I do not think it matters either way in practice, but I think this change is adding unnecessary confusion.

Both the 'subject' and 'date' on that line are meant to be placeholders, so where you see subject, you replace it "with the subject enclosed in a pair of double-quotes" as the next line says. But then you would end up with:

     Commit f86a374 (""pack-bitmap.c: fix a memleak"", 2015-03-30)

which is not what we want to see.