{"thread":{"id":"63321","subject":"[PATCH] doc: sparse-checkout: Fix list markers","startedAt":"2025-04-21T12:41:43Z","lastAt":"2025-05-30T13:38:10Z","messageCount":11,"participants":["oneee via GitGitGadget","Kristoffer Haugsbakk","Patrick Steinhardt","Eric Sunshine","oneee","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"516429","messageId":"pull.1948.git.git.1745239300668.gitgitgadget@gmail.com","threadId":"63321","inReplyTo":null,"subject":"[PATCH] doc: sparse-checkout: Fix list markers","fromName":"oneee via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-04-21T12:41:40Z","receivedAt":"2025-04-21T12:41:43Z","isPatch":true,"sender":{"key":"kimww0306@gmail.com","avatar":"https://avatars.githubusercontent.com/u/103808587?v=4"},"body":"From: onee-only \n\nChanged the list markers from a mix of \"(1)\" and \"(b)\" to a\nconsistent numeric format \"(1)\", \"(2)\" for clarity and consistency.\n\nSigned-off-by: onee-only \n---\n doc: sparse-checkout: Fix list markers\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1948%2Fonee-only%2Ffix-sparse-checkout-doc-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1948/onee-only/fix-sparse-checkout-doc-v1\nPull-Request: https://github.com/git/git/pull/1948\n\n Documentation/technical/sparse-checkout.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/sparse-checkout.adoc b/Documentation/technical/sparse-checkout.adoc\nindex dc2e763bbec..8202172b70b 100644\n--- a/Documentation/technical/sparse-checkout.adoc\n+++ b/Documentation/technical/sparse-checkout.adoc\n@@ -66,7 +66,7 @@ sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to\n \treasons: (1) users in cone mode specify directories rather than\n \tpatterns (their directories are transformed into patterns, but\n \tusers may think you are talking about non-cone mode if you use the\n-\tword \"patterns\"), and (b) the sparse specification might\n+\tword \"patterns\"), and (2) the sparse specification might\n \ttransiently differ in the working tree or index from the sparsity\n \tpatterns (see \"Sparse specification vs. sparsity patterns\").\n \n\nbase-commit: 4bbb303af69990ccd05fe3a2eb58a1ce036f8220\n-- \ngitgitgadget\n"},{"id":"519047","messageId":"d8d8c10d-4f4f-4fde-8b91-b979e2931fad@app.fastmail.com","threadId":"63321","inReplyTo":"pull.1948.git.git.1745239300668.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: sparse-checkout: Fix list markers","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-28T06:56:50Z","receivedAt":"2025-05-28T06:58:12Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"> doc: sparse-checkout: Fix list markers\n\ns/Fix/fix/. The initial word after the area should be lower-case. See\n`Documentation/SubmittingPatches` (SP), “describe-changes”.\n\nOn Mon, Apr 21, 2025, at 14:41, oneee via GitGitGadget wrote:\n> From: onee-only \n>\n> Changed the list markers from a mix of \"(1)\" and \"(b)\" to a\n> consistent numeric format \"(1)\", \"(2)\" for clarity and consistency.\n\nCommits are described in imperative mood (SB, “imperative-mood”).\n\nReading the message I thought it was about a larger change to\nconsistently use one style over the other. But you are fixing one\napplication of inline lists to use either numeric or alphabetic(?),\nspecifically falling on numeric.\n\nI would write it as:\n\n doc: sparse-checkout: use consistent inline list style\n\n Fix this inline list to use a single style, namely numeric, instead of\n `(1)` followed by `(b)`.\n\n(Numeric or numeral, I’m not sure)\n\n> Signed-off-by: onee-only \n\nI’m not saying the following is not the case. But FYI the project\ndemands that commit identification needs to be your real name.\n\nJust saying in case it is a pseudonym.\n\n> +\tword \"patterns\"), and (2) the sparse specification might\n\nI would also use a semicolon to separate `1` and `2`. I think this is\nthe correct style for any list introduced by a colon:\n\n see here: (1) ...; (2) ...; and (5) ...\n\nBecause then you can use commas freely inside each point.\n"},{"id":"519056","messageId":"aDa30OJmvcfp1_mM@pks.im","threadId":"63321","inReplyTo":"pull.1948.git.git.1745239300668.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: sparse-checkout: Fix list markers","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-05-28T07:14:24Z","receivedAt":"2025-05-28T07:14:27Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Mon, Apr 21, 2025 at 12:41:40PM +0000, oneee via GitGitGadget wrote:\n> From: onee-only \n> \n> Changed the list markers from a mix of \"(1)\" and \"(b)\" to a\n> consistent numeric format \"(1)\", \"(2)\" for clarity and consistency.\n\nIn Git we use imperative style for commit messages, as if requesting the\ncode to change. So something like this for example:\n\n We use a mix of \"(1)\" and \"(b)\" to refer to different cases when\n explaining sparsity patterns. Adapt these markers to use the numeric\n format for both clarity and consistency.\n\n> Signed-off-by: onee-only \n\nWe typically prefer your full name instead of using nicknames here. So\nif you want to provide your full name, please do so.\n\n> diff --git a/Documentation/technical/sparse-checkout.adoc b/Documentation/technical/sparse-checkout.adoc\n> index dc2e763bbec..8202172b70b 100644\n> --- a/Documentation/technical/sparse-checkout.adoc\n> +++ b/Documentation/technical/sparse-checkout.adoc\n> @@ -66,7 +66,7 @@ sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to\n> \treasons: (1) users in cone mode specify directories rather than\n> \tpatterns (their directories are transformed into patterns, but\n> \tusers may think you are talking about non-cone mode if you use the\n> -\tword \"patterns\"), and (b) the sparse specification might\n> +\tword \"patterns\"), and (2) the sparse specification might\n> \ttransiently differ in the working tree or index from the sparsity\n> \tpatterns (see \"Sparse specification vs. sparsity patterns\").\n\nThe change itself looks like an obvious improvement to me, thanks!\n\nPatrick\n"},{"id":"519057","messageId":"CAPig+cTdN=x2GXGW2p_g_k4jgC0eQmjW5zLsWhJm-PP7eMBTiQ@mail.gmail.com","threadId":"63321","inReplyTo":"d8d8c10d-4f4f-4fde-8b91-b979e2931fad@app.fastmail.com","subject":"Re: [PATCH] doc: sparse-checkout: Fix list markers","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-05-28T07:20:48Z","receivedAt":"2025-05-28T07:21:00Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, May 28, 2025 at 2:58 AM Kristoffer Haugsbakk\n wrote:\n> On Mon, Apr 21, 2025, at 14:41, oneee via GitGitGadget wrote:\n> > Changed the list markers from a mix of \"(1)\" and \"(b)\" to a\n> > consistent numeric format \"(1)\", \"(2)\" for clarity and consistency.\n>\n> Reading the message I thought it was about a larger change to\n> consistently use one style over the other. But you are fixing one\n> application of inline lists to use either numeric or alphabetic(?),\n> specifically falling on numeric.\n\nI seem to recall that I had a similar reaction when I originally read\nthe commit message.\n\n> I would write it as:\n>\n> doc: sparse-checkout: use consistent inline list style\n>\n> Fix this inline list to use a single style, namely numeric, instead of\n> `(1)` followed by `(b)`.\n\nThis does make it clearer.\n\n> > + word \"patterns\"), and (2) the sparse specification might\n>\n> I would also use a semicolon to separate `1` and `2`. I think this is\n> the correct style for any list introduced by a colon:\n>\n> see here: (1) ...; (2) ...; and (5) ...\n>\n> Because then you can use commas freely inside each point.\n\nI'd like to push back on this suggestion, at least in the context of\nthis particular patch, the purpose of which is to fix an actual\nproblem in the documentation. The sort of improvement you suggest\nprobably ought to be done as a separate patch, but let's not make it\nseem as if we are heaping extra work on the patch submitter; it's more\nimportant to get the fix itself landed.\n\nAs such, the patch itself looks obviously correct and is a definite\nimprovement as-is. It's not clear why it didn't get picked up; perhaps\nit just fell through the cracks.\n"},{"id":"519066","messageId":"4c1f645b-42fb-40b9-987e-08ce9e057e01@app.fastmail.com","threadId":"63321","inReplyTo":"CAPig+cTdN=x2GXGW2p_g_k4jgC0eQmjW5zLsWhJm-PP7eMBTiQ@mail.gmail.com","subject":"Re: [PATCH] doc: sparse-checkout: Fix list markers","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-28T08:01:17Z","receivedAt":"2025-05-28T08:01:38Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Wed, May 28, 2025, at 09:20, Eric Sunshine wrote:\n>> Because then you can use commas freely inside each point.\n>\n> I'd like to push back on this suggestion, at least in the context of\n> this particular patch, the purpose of which is to fix an actual\n> problem in the documentation. The sort of improvement you suggest\n> probably ought to be done as a separate patch, but let's not make it\n> seem as if we are heaping extra work on the patch submitter; it's more\n> important to get the fix itself landed.\n>\n> As such, the patch itself looks obviously correct and is a definite\n> improvement as-is. It's not clear why it didn't get picked up; perhaps\n> it just fell through the cracks.\n\nOkay, totally reasonable and makes sense IMO.\n"},{"id":"519192","messageId":"CABXyHXoCuwAUqiQPxE82mV4n0PQtY1zopD+rJDb+oyTkR8qwyg@mail.gmail.com","threadId":"63321","inReplyTo":"4c1f645b-42fb-40b9-987e-08ce9e057e01@app.fastmail.com","subject":"Re: [PATCH] doc: sparse-checkout: Fix list markers","fromName":"oneee","fromEmail":"kimww0306@gmail.com","sentAt":"2025-05-30T03:43:43Z","receivedAt":"2025-05-30T03:43:55Z","isPatch":true,"sender":{"key":"kimww0306@gmail.com","avatar":"https://avatars.githubusercontent.com/u/103808587?v=4"},"body":"(I'm resending this email since the previous message was blocked due\nto accidently containing HTML. Thanks for your understanding!)\n\nI'm sorry for the delay.\n\nOn Wed, May 28, 2025 at 3:58 PM Kristoffer Haugsbakk\n wrote:\n>\n> I would write it as:\n>\n> doc: sparse-checkout: use consistent inline list style\n>\n> Fix this inline list to use a single style, namely numeric, instead of\n> `(1)` followed by `(b)`.\n>\n> (Numeric or numeral, I’m not sure)\n\n\nThanks for the suggestion. I'll update the message as you wrote.\n\n>\n> > Signed-off-by: onee-only \n>\n> I’m not saying the following is not the case. But FYI the project\n> demands that commit identification needs to be your real name.\n>\n> Just saying in case it is a pseudonym.\n\n\nI wasn't aware of it. I'll change it into my real name. Thanks for\npointing it out.\n\nOn Wed, May 28, 2025 at 4:21 PM Eric Sunshine wrote:\n>\n> > > + word \"patterns\"), and (2) the sparse specification might\n> >\n> > I would also use a semicolon to separate `1` and `2`. I think this is\n> > the correct style for any list introduced by a colon:\n> >\n> > see here: (1) ...; (2) ...; and (5) ...\n> >\n> > Because then you can use commas freely inside each point.\n>\n> I'd like to push back on this suggestion, at least in the context of\n> this particular patch, the purpose of which is to fix an actual\n> problem in the documentation. The sort of improvement you suggest\n> probably ought to be done as a separate patch, but let's not make it\n> seem as if we are heaping extra work on the patch submitter; it's more\n> important to get the fix itself landed.\n\n\nI'd like to apply it to the same PR in GitHub, producing an additional\ncommit. (I don't fully understand how the system works, sorry).\n\nThank you all for the reviews!\n"},{"id":"519198","messageId":"CAPig+cQbchWLMH+pTVfLHwFshaex2vhC8Pk57EC4U-vch00ZDA@mail.gmail.com","threadId":"63321","inReplyTo":"CABXyHXoCuwAUqiQPxE82mV4n0PQtY1zopD+rJDb+oyTkR8qwyg@mail.gmail.com","subject":"Re: [PATCH] doc: sparse-checkout: Fix list markers","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-05-30T05:00:56Z","receivedAt":"2025-05-30T05:01:09Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, May 29, 2025 at 11:43 PM oneee wrote:\n> On Wed, May 28, 2025 at 4:21 PM Eric Sunshine wrote:\n> > > > + word \"patterns\"), and (2) the sparse specification might\n> > >\n> > > I would also use a semicolon to separate `1` and `2`. I think this is\n> > > the correct style for any list introduced by a colon:\n> > >\n> > > see here: (1) ...; (2) ...; and (5) ...\n> > >\n> > > Because then you can use commas freely inside each point.\n> >\n> > I'd like to push back on this suggestion, at least in the context of\n> > this particular patch, the purpose of which is to fix an actual\n> > problem in the documentation. The sort of improvement you suggest\n> > probably ought to be done as a separate patch, but let's not make it\n> > seem as if we are heaping extra work on the patch submitter; it's more\n> > important to get the fix itself landed.\n>\n> I'd like to apply it to the same PR in GitHub, producing an additional\n> commit. (I don't fully understand how the system works, sorry).\n\nYou're welcome to submit an additional patch implementing Kristoffer's\nsuggestion. Normally, it would make sense to send them both as a\ntwo-patch series, however, I'm not so sure that that would be a good\nidea in this case. The reason I question it is that the original patch\nis an obvious and uncontroversial fix, however, Kristoffer's\nsuggestion -- because it is a subjective change -- may get pushback\nfrom reviewers. If it does get pushback, then that pushback could hold\nup the entire series as discussion ensues, thus slowing or even\ncompletely derailing the original \"fix\" patch from being accepted.\n"},{"id":"519204","messageId":"CABXyHXpGZCDyR232P5Mir8q_ZsMFJwYkYtE172YZfKCDZuA1fw@mail.gmail.com","threadId":"63321","inReplyTo":"CAPig+cQbchWLMH+pTVfLHwFshaex2vhC8Pk57EC4U-vch00ZDA@mail.gmail.com","subject":"Re: [PATCH] doc: sparse-checkout: Fix list markers","fromName":"oneee","fromEmail":"kimww0306@gmail.com","sentAt":"2025-05-30T07:18:23Z","receivedAt":"2025-05-30T07:18:34Z","isPatch":true,"sender":{"key":"kimww0306@gmail.com","avatar":"https://avatars.githubusercontent.com/u/103808587?v=4"},"body":"On Fri, May 30, 2025 at 2:01 PM Eric Sunshine wrote:\n> You're welcome to submit an additional patch implementing Kristoffer's\n> suggestion. Normally, it would make sense to send them both as a\n> two-patch series, however, I'm not so sure that that would be a good\n> idea in this case. The reason I question it is that the original patch\n> is an obvious and uncontroversial fix, however, Kristoffer's\n> suggestion -- because it is a subjective change -- may get pushback\n> from reviewers. If it does get pushback, then that pushback could hold\n> up the entire series as discussion ensues, thus slowing or even\n> completely derailing the original \"fix\" patch from being accepted.\n\nThat makes sense. I'll submit an additional patch after this one is accepted.\n\nMuch appreciated!\n"},{"id":"519205","messageId":"pull.1948.v2.git.git.1748589756289.gitgitgadget@gmail.com","threadId":"63321","inReplyTo":"pull.1948.git.git.1745239300668.gitgitgadget@gmail.com","subject":"[PATCH v2] doc: sparse-checkout: use consistent inline list style","fromName":"oneee via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-05-30T07:22:36Z","receivedAt":"2025-05-30T07:22:39Z","isPatch":true,"sender":{"key":"kimww0306@gmail.com","avatar":"https://avatars.githubusercontent.com/u/103808587?v=4"},"body":"From: Wonuk Kim \n\nFix this inline list to use a single style, namely numeric, instead of\n`(1)` followed by `(b)`.\n\nSigned-off-by: Wonuk Kim \n---\n doc: sparse-checkout: Fix list markers\n \n cc: \"Kristoffer Haugsbakk\" kristofferhaugsbakk@fastmail.com cc: Patrick\n Steinhardt ps@pks.im cc: Eric Sunshine sunshine@sunshineco.com\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1948%2Fonee-only%2Ffix-sparse-checkout-doc-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1948/onee-only/fix-sparse-checkout-doc-v2\nPull-Request: https://github.com/git/git/pull/1948\n\nRange-diff vs v1:\n\n 1: c702bbc8782 ! 1: 6154158b98c doc: sparse-checkout: Fix list markers\n @@\n ## Metadata ##\n -Author: onee-only \n +Author: Wonuk Kim \n \n ## Commit message ##\n - doc: sparse-checkout: Fix list markers\n + doc: sparse-checkout: use consistent inline list style\n \n - Changed the list markers from a mix of \"(1)\" and \"(b)\" to a\n - consistent numeric format \"(1)\", \"(2)\" for clarity and consistency.\n + Fix this inline list to use a single style, namely numeric, instead of\n + `(1)` followed by `(b)`.\n \n - Signed-off-by: onee-only \n + Signed-off-by: Wonuk Kim \n \n ## Documentation/technical/sparse-checkout.adoc ##\n @@ Documentation/technical/sparse-checkout.adoc: sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to\n\n\n Documentation/technical/sparse-checkout.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/sparse-checkout.adoc b/Documentation/technical/sparse-checkout.adoc\nindex dc2e763bbec..8202172b70b 100644\n--- a/Documentation/technical/sparse-checkout.adoc\n+++ b/Documentation/technical/sparse-checkout.adoc\n@@ -66,7 +66,7 @@ sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to\n \treasons: (1) users in cone mode specify directories rather than\n \tpatterns (their directories are transformed into patterns, but\n \tusers may think you are talking about non-cone mode if you use the\n-\tword \"patterns\"), and (b) the sparse specification might\n+\tword \"patterns\"), and (2) the sparse specification might\n \ttransiently differ in the working tree or index from the sparsity\n \tpatterns (see \"Sparse specification vs. sparsity patterns\").\n \n\nbase-commit: 4bbb303af69990ccd05fe3a2eb58a1ce036f8220\n-- \ngitgitgadget\n"},{"id":"519206","messageId":"956069c2-d818-472d-9d84-0190432512a2@app.fastmail.com","threadId":"63321","inReplyTo":"pull.1948.v2.git.git.1748589756289.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: sparse-checkout: use consistent inline list style","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-05-30T07:41:19Z","receivedAt":"2025-05-30T07:41:52Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Fri, May 30, 2025, at 09:22, oneee via GitGitGadget wrote:\n> From: Wonuk Kim \n>\n> Fix this inline list to use a single style, namely numeric, instead of\n> `(1)` followed by `(b)`.\n>\n> Signed-off-by: Wonuk Kim \n> [snip]\n\nLooks great. Thanks.\n"},{"id":"519239","messageId":"871ps6b4n8.fsf@gitster.g","threadId":"63321","inReplyTo":"CAPig+cQbchWLMH+pTVfLHwFshaex2vhC8Pk57EC4U-vch00ZDA@mail.gmail.com","subject":"Re: [PATCH] doc: sparse-checkout: Fix list markers","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-30T13:38:03Z","receivedAt":"2025-05-30T13:38:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> You're welcome to submit an additional patch implementing Kristoffer's\n> suggestion. Normally, it would make sense to send them both as a\n> two-patch series, however, I'm not so sure that that would be a good\n> idea in this case. The reason I question it is that the original patch\n> is an obvious and uncontroversial fix, however, Kristoffer's\n> suggestion -- because it is a subjective change -- may get pushback\n> from reviewers.\n\nI had the same thought. If I were working on this topic, I'd send\nthe original as-is with the suggested name fix, let it graduate, and\nthen after all the dust settled, do enumeration-style changes as a\nnew and totally independent patch, which may cover enumerations\nother than this single instance.\n\nThanks.\n\n"}]}