{"thread":{"id":"44244","subject":"[PATCH] clean up confusing suggestion for commit references","startedAt":"2016-10-07T09:56:50Z","lastAt":"2016-10-11T16:47:54Z","messageCount":7,"participants":["Heiko Voigt","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"303551","messageId":"20161007095638.GA55445@book.hvoigt.net","threadId":"44244","inReplyTo":null,"subject":"[PATCH] clean up confusing suggestion for commit references","fromName":"Heiko Voigt","fromEmail":"hvoigt@hvoigt.net","sentAt":"2016-10-07T09:56:38Z","receivedAt":"2016-10-07T09:56:50Z","isPatch":true,"sender":{"key":"hvoigt@hvoigt.net","avatar":"https://avatars.githubusercontent.com/u/184958?v=4"},"body":"The description for referencing commits looks as if it is contradicting\nthe example, since it is itself enclosed in double quotes. Lets use\nsingle quotes around the description and include the double quotes in\nthe description so it matches the example.\n---\nSorry for opening this up again but I just looked up the format and was\nlike: \"Umm, which one is now the correct one...\"\n\nFor this makes more sense. What do others think?\n\nCheers Heiko\n\n Documentation/SubmittingPatches | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex 08352de..692f4ce 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -122,7 +122,7 @@ without external resources. Instead of giving a URL to a mailing list\n archive, summarize the relevant points of the discussion.\n \n If you want to reference a previous commit in the history of a stable\n-branch, use the format \"abbreviated sha1 (subject, date)\",\n+branch, use the format 'abbreviated sha1 (\"subject\", date)',\n with the subject enclosed in a pair of double-quotes, like this:\n \n Commit f86a374 (\"pack-bitmap.c: fix a memleak\", 2015-03-30)\n-- \n2.10.0.645.g54f1e86\n\n"},{"id":"303567","messageId":"20161007143200.qw77pdsymbdmjhbw@sigill.intra.peff.net","threadId":"44244","inReplyTo":"20161007095638.GA55445@book.hvoigt.net","subject":"Re: [PATCH] clean up confusing suggestion for commit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-10-07T14:32:01Z","receivedAt":"2016-10-07T14:33:19Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Oct 07, 2016 at 11:56:38AM +0200, Heiko Voigt wrote:\n\n> The description for referencing commits looks as if it is contradicting\n> the example, since it is itself enclosed in double quotes. Lets use\n> single quotes around the description and include the double quotes in\n> the description so it matches the example.\n> ---\n> Sorry for opening this up again but I just looked up the format and was\n> like: \"Umm, which one is now the correct one...\"\n> \n> For this makes more sense. What do others think?\n\nLooking over the threads, I wasn't sure there was consensus[1,2]. So it would\nbe equally correct to drop the quotes from the example.\n\nI dunno. I am in favor of no-quotes, myself, so maybe I am just\nmanufacturing dissent in my mind. :)\n\n-Peff\n\n[1] http://public-inbox.org/git/a9731f60-5c30-0bc6-f73a-f7ffb7bd4231@kdbg.org/\n[2] http://public-inbox.org/git/20160829183015.2uqnfezekjfa3ott@sigill.intra.peff.net/\n"},{"id":"303774","messageId":"xmqqlgxwf4us.fsf@gitster.mtv.corp.google.com","threadId":"44244","inReplyTo":"20161007095638.GA55445@book.hvoigt.net","subject":"Re: [PATCH] clean up confusing suggestion for commit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-10T18:15:07Z","receivedAt":"2016-10-10T18:15:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Heiko Voigt writes:\n\n> If you want to reference a previous commit in the history of a stable\n> -branch, use the format \"abbreviated sha1 (subject, date)\",\n> +branch, use the format 'abbreviated sha1 (\"subject\", date)',\n> with the subject enclosed in a pair of double-quotes, like this:\n> \n> Commit f86a374 (\"pack-bitmap.c: fix a memleak\", 2015-03-30)\n\nAs long as the \"like this\" example is there close to the sentence\n\"use the format ...\", I do not think it matters either way in\npractice, but I think this change is adding unnecessary confusion.\n\nBoth the 'subject' and 'date' on that line are meant to be\nplaceholders, so where you see subject, you replace it \"with the\nsubject enclosed in a pair of double-quotes\" as the next line says.\nBut then you would end up with:\n\n Commit f86a374 (\"\"pack-bitmap.c: fix a memleak\"\", 2015-03-30)\n\nwhich is not what we want to see.\n\n"},{"id":"303777","messageId":"xmqqh98kf4fy.fsf@gitster.mtv.corp.google.com","threadId":"44244","inReplyTo":"20161007143200.qw77pdsymbdmjhbw@sigill.intra.peff.net","subject":"Re: [PATCH] clean up confusing suggestion for commit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-10T18:24:01Z","receivedAt":"2016-10-10T18:24:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Fri, Oct 07, 2016 at 11:56:38AM +0200, Heiko Voigt wrote:\n>\n>> The description for referencing commits looks as if it is contradicting\n>> the example, since it is itself enclosed in double quotes. Lets use\n>> single quotes around the description and include the double quotes in\n>> the description so it matches the example.\n>> ---\n>> Sorry for opening this up again but I just looked up the format and was\n>> like: \"Umm, which one is now the correct one...\"\n>> \n>> For this makes more sense. What do others think?\n>\n> Looking over the threads, I wasn't sure there was consensus[1,2]. So it would\n> be equally correct to drop the quotes from the example.\n>\n> I dunno. I am in favor of no-quotes, myself, so maybe I am just\n> manufacturing dissent in my mind. :)\n\nI no longer have preference either way myself, even though I was in\nfavor of no-quotes simply because I had an alias to produce that\nformat and was used to it.\n\n"},{"id":"303778","messageId":"20161010182623.hsczlsfc6oaa2byj@sigill.intra.peff.net","threadId":"44244","inReplyTo":"xmqqh98kf4fy.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] clean up confusing suggestion for commit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-10-10T18:26:23Z","receivedAt":"2016-10-10T18:27:06Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Oct 10, 2016 at 11:24:01AM -0700, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> > On Fri, Oct 07, 2016 at 11:56:38AM +0200, Heiko Voigt wrote:\n> >\n> >> The description for referencing commits looks as if it is contradicting\n> >> the example, since it is itself enclosed in double quotes. Lets use\n> >> single quotes around the description and include the double quotes in\n> >> the description so it matches the example.\n> >> ---\n> >> Sorry for opening this up again but I just looked up the format and was\n> >> like: \"Umm, which one is now the correct one...\"\n> >> \n> >> For this makes more sense. What do others think?\n> >\n> > Looking over the threads, I wasn't sure there was consensus[1,2]. So it would\n> > be equally correct to drop the quotes from the example.\n> >\n> > I dunno. I am in favor of no-quotes, myself, so maybe I am just\n> > manufacturing dissent in my mind. :)\n> \n> I no longer have preference either way myself, even though I was in\n> favor of no-quotes simply because I had an alias to produce that\n> format and was used to it.\n\nI'll admit that I don't care _that_ much and am happy to leave it up to\nindividual authors, as long as nobody quotes SubmittingPatches at me as\nsome kind of gospel when I use the no-quotes form.\n\n-Peff\n"},{"id":"303790","messageId":"xmqqoa2sdnjt.fsf@gitster.mtv.corp.google.com","threadId":"44244","inReplyTo":"20161010182623.hsczlsfc6oaa2byj@sigill.intra.peff.net","subject":"Re: [PATCH] clean up confusing suggestion for commit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-10-10T19:14:14Z","receivedAt":"2016-10-10T19:19:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Mon, Oct 10, 2016 at 11:24:01AM -0700, Junio C Hamano wrote:\n>\n>> I no longer have preference either way myself, even though I was in\n>> favor of no-quotes simply because I had an alias to produce that\n>> format and was used to it.\n>\n> I'll admit that I don't care _that_ much and am happy to leave it up to\n> individual authors, as long as nobody quotes SubmittingPatches at me as\n> some kind of gospel when I use the no-quotes form.\n\n;-). \n\nI just do not want to hear \"gitk (or was it git-gui) produces quoted\nform, why are you recommending no-quoted form in SubmittingPatches?\"\n\nI'd say \"use common sense; sometimes it is less confusing to read\nwithout quotes and it is perfectly OK to do so if that is the case\".\n\n"},{"id":"303885","messageId":"20161011164743.GA78613@book.hvoigt.net","threadId":"44244","inReplyTo":"xmqqoa2sdnjt.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] clean up confusing suggestion for commit references","fromName":"Heiko Voigt","fromEmail":"hvoigt@hvoigt.net","sentAt":"2016-10-11T16:47:43Z","receivedAt":"2016-10-11T16:47:54Z","isPatch":true,"sender":{"key":"hvoigt@hvoigt.net","avatar":"https://avatars.githubusercontent.com/u/184958?v=4"},"body":"On Mon, Oct 10, 2016 at 12:14:14PM -0700, Junio C Hamano wrote:\n> Jeff King writes:\n> \n> > On Mon, Oct 10, 2016 at 11:24:01AM -0700, Junio C Hamano wrote:\n> >\n> >> I no longer have preference either way myself, even though I was in\n> >> favor of no-quotes simply because I had an alias to produce that\n> >> format and was used to it.\n> >\n> > I'll admit that I don't care _that_ much and am happy to leave it up to\n> > individual authors, as long as nobody quotes SubmittingPatches at me as\n> > some kind of gospel when I use the no-quotes form.\n> \n> ;-). \n> \n> I just do not want to hear \"gitk (or was it git-gui) produces quoted\n> form, why are you recommending no-quoted form in SubmittingPatches?\"\n> \n> I'd say \"use common sense; sometimes it is less confusing to read\n> without quotes and it is perfectly OK to do so if that is the case\".\n\nI do not care about which format it should be either. I just wanted to\nbe clear about whatever should be used. Since it seems we will allow\nboth, I am also fine with leaving the description as it is ;-)\n\nCheers Heiko\n"}]}