{"thread":{"id":"61532","subject":"[PATCH] blame: do not mention obvious default configuration values","startedAt":"2024-05-22T18:44:42Z","lastAt":"2024-05-23T09:08:30Z","messageCount":4,"participants":["Junio C Hamano","Dragan Simic","Eric Sunshine","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"495312","messageId":"xmqqpltd4rfu.fsf@gitster.g","threadId":"61532","inReplyTo":null,"subject":"[PATCH] blame: do not mention obvious default configuration values","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-22T18:44:37Z","receivedAt":"2024-05-22T18:44:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"While it helps to mention what the default behaviour is when a\nvariable is unconfigured, when there are more than true or false\nchoices for the variable (e.g. \"defaults to never, among possible\nchoices never/local/remote/always\"), or if the default behaviour is\nas if the unconfigured variable were set to true the knob is purely\nto opt out of it (\"Porcelain 'git diff' refreshes the index, but\ndiff.autoRefreshIndex can be set to false to opt out of it\"), it\nfeels like it adds unnecesary noise to say \"defaults to off\" for a\nconfiguration variable that is clearly a Boolean.\n\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n\n * I am somewhat hesitant to use a phrase that implies that there is\n   some \"default value\" for any configuration variable.  Saying \"The\n   default value for the configuration variable X is Y\" misleads\n   readers to expect that \"git config -l\" would show X=Y when the\n   user hasn't configured X at all.\n\n   It is just the feature controlled by the configuration variable\n   works exactly as if the configuration variable is set to that\n   \"default value\", instead of left unconfigured.\n\n   But that is a separate issue, and is totally outside the scope of\n   this change.\n\n Documentation/config/blame.txt | 4 +---\n 1 file changed, 1 insertion(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/blame.txt b/Documentation/config/blame.txt\nindex 4d047c1790..36f965484c 100644\n--- a/Documentation/config/blame.txt\n+++ b/Documentation/config/blame.txt\n@@ -1,6 +1,6 @@\n blame.blankBoundary::\n \tShow blank commit object name for boundary commits in\n-\tlinkgit:git-blame[1]. This option defaults to false.\n+\tlinkgit:git-blame[1].\n \n blame.coloring::\n \tThis determines the coloring scheme to be applied to blame\n@@ -14,11 +14,9 @@ blame.date::\n \n blame.showEmail::\n \tShow the author email instead of author name in linkgit:git-blame[1].\n-\tThis option defaults to false.\n \n blame.showRoot::\n \tDo not treat root commits as boundaries in linkgit:git-blame[1].\n-\tThis option defaults to false.\n \n blame.ignoreRevsFile::\n \tIgnore revisions listed in the file, one unabbreviated object name per\n-- \n2.45.1-216-g4365c6fcf9\n\n"},{"id":"495319","messageId":"51e30846c62a1605dee8fd5b9d096222@manjaro.org","threadId":"61532","inReplyTo":"xmqqpltd4rfu.fsf@gitster.g","subject":"Re: [PATCH] blame: do not mention obvious default configuration values","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-05-22T19:13:36Z","receivedAt":"2024-05-22T19:13:37Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-05-22 20:44, Junio C Hamano wrote:\n> diff --git a/Documentation/config/blame.txt \n> b/Documentation/config/blame.txt\n> index 4d047c1790..36f965484c 100644\n> --- a/Documentation/config/blame.txt\n> +++ b/Documentation/config/blame.txt\n> @@ -1,6 +1,6 @@\n>  blame.blankBoundary::\n>  \tShow blank commit object name for boundary commits in\n> -\tlinkgit:git-blame[1]. This option defaults to false.\n> +\tlinkgit:git-blame[1].\n> \n>  blame.coloring::\n>  \tThis determines the coloring scheme to be applied to blame\n> @@ -14,11 +14,9 @@ blame.date::\n> \n>  blame.showEmail::\n>  \tShow the author email instead of author name in linkgit:git-blame[1].\n> -\tThis option defaults to false.\n> \n>  blame.showRoot::\n>  \tDo not treat root commits as boundaries in linkgit:git-blame[1].\n> -\tThis option defaults to false.\n> \n>  blame.ignoreRevsFile::\n>  \tIgnore revisions listed in the file, one unabbreviated object name \n> per\n\nFrankly, I'd much rather see the same \"If true, ...\" twist [1]\napplied here, rather than just deleting the descriptions of the\ndefaults.  To me, such an approach eliminates any doubts, while\nnot stressing out the actual default value.\n\n[1] \nhttps://lore.kernel.org/git/54c318f42ce63f0575ea48f3dc1e8361@manjaro.org/\n"},{"id":"495321","messageId":"CAPig+cQ7bq8LKxnmjY3FQ9MRpM0GMep1Nxyp7jasB8yJvTV-RQ@mail.gmail.com","threadId":"61532","inReplyTo":"51e30846c62a1605dee8fd5b9d096222@manjaro.org","subject":"Re: [PATCH] blame: do not mention obvious default configuration values","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2024-05-22T19:19:58Z","receivedAt":"2024-05-22T19:20:10Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, May 22, 2024 at 3:13 PM Dragan Simic <dsimic@manjaro.org> wrote:\n> On 2024-05-22 20:44, Junio C Hamano wrote:\n> > diff --git a/Documentation/config/blame.txt\n> > b/Documentation/config/blame.txt\n> > @@ -1,6 +1,6 @@\n> >  blame.blankBoundary::\n> >       Show blank commit object name for boundary commits in\n> > -     linkgit:git-blame[1]. This option defaults to false.\n> > +     linkgit:git-blame[1].\n> > @@ -14,11 +14,9 @@ blame.date::\n>\n> Frankly, I'd much rather see the same \"If true, ...\" twist [1]\n> applied here, rather than just deleting the descriptions of the\n> defaults.  To me, such an approach eliminates any doubts, while\n> not stressing out the actual default value.\n\nFor what it's worth, when reviewing patches on this list, I have\nmultiple times asked submitters to mention the default value when\nadding new documentation since it saves users the trouble of having to\ndiscover the default either by experimentation or by reading the\nsource code. So, I see removal of mention of default values as a step\nbackward.\n"},{"id":"495368","messageId":"20240523090829.GD1306938@coredump.intra.peff.net","threadId":"61532","inReplyTo":"CAPig+cQ7bq8LKxnmjY3FQ9MRpM0GMep1Nxyp7jasB8yJvTV-RQ@mail.gmail.com","subject":"Re: [PATCH] blame: do not mention obvious default configuration values","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2024-05-23T09:08:29Z","receivedAt":"2024-05-23T09:08:30Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 22, 2024 at 03:19:58PM -0400, Eric Sunshine wrote:\n\n> For what it's worth, when reviewing patches on this list, I have\n> multiple times asked submitters to mention the default value when\n> adding new documentation since it saves users the trouble of having to\n> discover the default either by experimentation or by reading the\n> source code. So, I see removal of mention of default values as a step\n> backward.\n\nFWIW, I came here to make the same comment. ;) I'd rather the\ndocumentation err on the side of being overly descriptive.\n\n-Peff\n"}]}