# [PATCH] doc: sparse-checkout: Fix list markers 11 messages from 2025-04-21 to 2025-05-30. Participants: oneee via GitGitGadget, Kristoffer Haugsbakk, Patrick Steinhardt, Eric Sunshine, oneee, Junio C Hamano. Thread: https://gitlist.dev/t/63321 ## oneee via GitGitGadget, 2025-04-21 12:41 Subject: [PATCH] doc: sparse-checkout: Fix list markers Message-ID: URL: https://gitlist.dev/e/pull.1948.git.git.1745239300668.gitgitgadget%40gmail.com ``` From: onee-only Changed the list markers from a mix of "(1)" and "(b)" to a consistent numeric format "(1)", "(2)" for clarity and consistency. Signed-off-by: onee-only --- doc: sparse-checkout: Fix list markers Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1948%2Fonee-only%2Ffix-sparse-checkout-doc-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1948/onee-only/fix-sparse-checkout-doc-v1 Pull-Request: https://github.com/git/git/pull/1948 Documentation/technical/sparse-checkout.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/technical/sparse-checkout.adoc b/Documentation/technical/sparse-checkout.adoc index dc2e763bbec..8202172b70b 100644 --- a/Documentation/technical/sparse-checkout.adoc +++ b/Documentation/technical/sparse-checkout.adoc @@ -66,7 +66,7 @@ sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to reasons: (1) users in cone mode specify directories rather than patterns (their directories are transformed into patterns, but users may think you are talking about non-cone mode if you use the - word "patterns"), and (b) the sparse specification might + word "patterns"), and (2) the sparse specification might transiently differ in the working tree or index from the sparsity patterns (see "Sparse specification vs. sparsity patterns"). base-commit: 4bbb303af69990ccd05fe3a2eb58a1ce036f8220 -- gitgitgadget ``` ## Kristoffer Haugsbakk, 2025-05-28 06:56 Subject: Re: [PATCH] doc: sparse-checkout: Fix list markers Message-ID: URL: https://gitlist.dev/e/d8d8c10d-4f4f-4fde-8b91-b979e2931fad%40app.fastmail.com In-Reply-To: ``` > doc: sparse-checkout: Fix list markers s/Fix/fix/. The initial word after the area should be lower-case. See `Documentation/SubmittingPatches` (SP), “describe-changes”. On Mon, Apr 21, 2025, at 14:41, oneee via GitGitGadget wrote: > From: onee-only > > Changed the list markers from a mix of "(1)" and "(b)" to a > consistent numeric format "(1)", "(2)" for clarity and consistency. Commits are described in imperative mood (SB, “imperative-mood”). Reading the message I thought it was about a larger change to consistently use one style over the other. But you are fixing one application of inline lists to use either numeric or alphabetic(?), specifically falling on numeric. I would write it as: doc: sparse-checkout: use consistent inline list style Fix this inline list to use a single style, namely numeric, instead of `(1)` followed by `(b)`. (Numeric or numeral, I’m not sure) > Signed-off-by: onee-only I’m not saying the following is not the case. But FYI the project demands that commit identification needs to be your real name. Just saying in case it is a pseudonym. > + word "patterns"), and (2) the sparse specification might I would also use a semicolon to separate `1` and `2`. I think this is the correct style for any list introduced by a colon: see here: (1) ...; (2) ...; and (5) ... Because then you can use commas freely inside each point. ``` ## Patrick Steinhardt, 2025-05-28 07:14 Subject: Re: [PATCH] doc: sparse-checkout: Fix list markers Message-ID: URL: https://gitlist.dev/e/aDa30OJmvcfp1_mM%40pks.im In-Reply-To: ``` On Mon, Apr 21, 2025 at 12:41:40PM +0000, oneee via GitGitGadget wrote: > From: onee-only > > Changed the list markers from a mix of "(1)" and "(b)" to a > consistent numeric format "(1)", "(2)" for clarity and consistency. In Git we use imperative style for commit messages, as if requesting the code to change. So something like this for example: We use a mix of "(1)" and "(b)" to refer to different cases when explaining sparsity patterns. Adapt these markers to use the numeric format for both clarity and consistency. > Signed-off-by: onee-only We typically prefer your full name instead of using nicknames here. So if you want to provide your full name, please do so. > diff --git a/Documentation/technical/sparse-checkout.adoc b/Documentation/technical/sparse-checkout.adoc > index dc2e763bbec..8202172b70b 100644 > --- a/Documentation/technical/sparse-checkout.adoc > +++ b/Documentation/technical/sparse-checkout.adoc > @@ -66,7 +66,7 @@ sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to > reasons: (1) users in cone mode specify directories rather than > patterns (their directories are transformed into patterns, but > users may think you are talking about non-cone mode if you use the > - word "patterns"), and (b) the sparse specification might > + word "patterns"), and (2) the sparse specification might > transiently differ in the working tree or index from the sparsity > patterns (see "Sparse specification vs. sparsity patterns"). The change itself looks like an obvious improvement to me, thanks! Patrick ``` ## Eric Sunshine, 2025-05-28 07:20 Subject: Re: [PATCH] doc: sparse-checkout: Fix list markers Message-ID: URL: https://gitlist.dev/e/CAPig%2BcTdN%3Dx2GXGW2p_g_k4jgC0eQmjW5zLsWhJm-PP7eMBTiQ%40mail.gmail.com In-Reply-To: ``` On Wed, May 28, 2025 at 2:58 AM Kristoffer Haugsbakk wrote: > On Mon, Apr 21, 2025, at 14:41, oneee via GitGitGadget wrote: > > Changed the list markers from a mix of "(1)" and "(b)" to a > > consistent numeric format "(1)", "(2)" for clarity and consistency. > > Reading the message I thought it was about a larger change to > consistently use one style over the other. But you are fixing one > application of inline lists to use either numeric or alphabetic(?), > specifically falling on numeric. I seem to recall that I had a similar reaction when I originally read the commit message. > I would write it as: > > doc: sparse-checkout: use consistent inline list style > > Fix this inline list to use a single style, namely numeric, instead of > `(1)` followed by `(b)`. This does make it clearer. > > + word "patterns"), and (2) the sparse specification might > > I would also use a semicolon to separate `1` and `2`. I think this is > the correct style for any list introduced by a colon: > > see here: (1) ...; (2) ...; and (5) ... > > Because then you can use commas freely inside each point. I'd like to push back on this suggestion, at least in the context of this particular patch, the purpose of which is to fix an actual problem in the documentation. The sort of improvement you suggest probably ought to be done as a separate patch, but let's not make it seem as if we are heaping extra work on the patch submitter; it's more important to get the fix itself landed. As such, the patch itself looks obviously correct and is a definite improvement as-is. It's not clear why it didn't get picked up; perhaps it just fell through the cracks. ``` ## Kristoffer Haugsbakk, 2025-05-28 08:01 Subject: Re: [PATCH] doc: sparse-checkout: Fix list markers Message-ID: <4c1f645b-42fb-40b9-987e-08ce9e057e01@app.fastmail.com> URL: https://gitlist.dev/e/4c1f645b-42fb-40b9-987e-08ce9e057e01%40app.fastmail.com In-Reply-To: ``` On Wed, May 28, 2025, at 09:20, Eric Sunshine wrote: >> Because then you can use commas freely inside each point. > > I'd like to push back on this suggestion, at least in the context of > this particular patch, the purpose of which is to fix an actual > problem in the documentation. The sort of improvement you suggest > probably ought to be done as a separate patch, but let's not make it > seem as if we are heaping extra work on the patch submitter; it's more > important to get the fix itself landed. > > As such, the patch itself looks obviously correct and is a definite > improvement as-is. It's not clear why it didn't get picked up; perhaps > it just fell through the cracks. Okay, totally reasonable and makes sense IMO. ``` ## oneee, 2025-05-30 03:43 Subject: Re: [PATCH] doc: sparse-checkout: Fix list markers Message-ID: URL: https://gitlist.dev/e/CABXyHXoCuwAUqiQPxE82mV4n0PQtY1zopD%2BrJDb%2BoyTkR8qwyg%40mail.gmail.com In-Reply-To: <4c1f645b-42fb-40b9-987e-08ce9e057e01@app.fastmail.com> ``` (I'm resending this email since the previous message was blocked due to accidently containing HTML. Thanks for your understanding!) I'm sorry for the delay. On Wed, May 28, 2025 at 3:58 PM Kristoffer Haugsbakk wrote: > > I would write it as: > > doc: sparse-checkout: use consistent inline list style > > Fix this inline list to use a single style, namely numeric, instead of > `(1)` followed by `(b)`. > > (Numeric or numeral, I’m not sure) Thanks for the suggestion. I'll update the message as you wrote. > > > Signed-off-by: onee-only > > I’m not saying the following is not the case. But FYI the project > demands that commit identification needs to be your real name. > > Just saying in case it is a pseudonym. I wasn't aware of it. I'll change it into my real name. Thanks for pointing it out. On Wed, May 28, 2025 at 4:21 PM Eric Sunshine wrote: > > > > + word "patterns"), and (2) the sparse specification might > > > > I would also use a semicolon to separate `1` and `2`. I think this is > > the correct style for any list introduced by a colon: > > > > see here: (1) ...; (2) ...; and (5) ... > > > > Because then you can use commas freely inside each point. > > I'd like to push back on this suggestion, at least in the context of > this particular patch, the purpose of which is to fix an actual > problem in the documentation. The sort of improvement you suggest > probably ought to be done as a separate patch, but let's not make it > seem as if we are heaping extra work on the patch submitter; it's more > important to get the fix itself landed. I'd like to apply it to the same PR in GitHub, producing an additional commit. (I don't fully understand how the system works, sorry). Thank you all for the reviews! ``` ## Eric Sunshine, 2025-05-30 05:00 Subject: Re: [PATCH] doc: sparse-checkout: Fix list markers Message-ID: URL: https://gitlist.dev/e/CAPig%2BcQbchWLMH%2BpTVfLHwFshaex2vhC8Pk57EC4U-vch00ZDA%40mail.gmail.com In-Reply-To: ``` On Thu, May 29, 2025 at 11:43 PM oneee wrote: > On Wed, May 28, 2025 at 4:21 PM Eric Sunshine wrote: > > > > + word "patterns"), and (2) the sparse specification might > > > > > > I would also use a semicolon to separate `1` and `2`. I think this is > > > the correct style for any list introduced by a colon: > > > > > > see here: (1) ...; (2) ...; and (5) ... > > > > > > Because then you can use commas freely inside each point. > > > > I'd like to push back on this suggestion, at least in the context of > > this particular patch, the purpose of which is to fix an actual > > problem in the documentation. The sort of improvement you suggest > > probably ought to be done as a separate patch, but let's not make it > > seem as if we are heaping extra work on the patch submitter; it's more > > important to get the fix itself landed. > > I'd like to apply it to the same PR in GitHub, producing an additional > commit. (I don't fully understand how the system works, sorry). You're welcome to submit an additional patch implementing Kristoffer's suggestion. Normally, it would make sense to send them both as a two-patch series, however, I'm not so sure that that would be a good idea in this case. The reason I question it is that the original patch is an obvious and uncontroversial fix, however, Kristoffer's suggestion -- because it is a subjective change -- may get pushback from reviewers. If it does get pushback, then that pushback could hold up the entire series as discussion ensues, thus slowing or even completely derailing the original "fix" patch from being accepted. ``` ## oneee, 2025-05-30 07:18 Subject: Re: [PATCH] doc: sparse-checkout: Fix list markers Message-ID: URL: https://gitlist.dev/e/CABXyHXpGZCDyR232P5Mir8q_ZsMFJwYkYtE172YZfKCDZuA1fw%40mail.gmail.com In-Reply-To: ``` On Fri, May 30, 2025 at 2:01 PM Eric Sunshine wrote: > You're welcome to submit an additional patch implementing Kristoffer's > suggestion. Normally, it would make sense to send them both as a > two-patch series, however, I'm not so sure that that would be a good > idea in this case. The reason I question it is that the original patch > is an obvious and uncontroversial fix, however, Kristoffer's > suggestion -- because it is a subjective change -- may get pushback > from reviewers. If it does get pushback, then that pushback could hold > up the entire series as discussion ensues, thus slowing or even > completely derailing the original "fix" patch from being accepted. That makes sense. I'll submit an additional patch after this one is accepted. Much appreciated! ``` ## oneee via GitGitGadget, 2025-05-30 07:22 Subject: [PATCH v2] doc: sparse-checkout: use consistent inline list style Message-ID: URL: https://gitlist.dev/e/pull.1948.v2.git.git.1748589756289.gitgitgadget%40gmail.com In-Reply-To: ``` From: Wonuk Kim Fix this inline list to use a single style, namely numeric, instead of `(1)` followed by `(b)`. Signed-off-by: Wonuk Kim --- doc: sparse-checkout: Fix list markers cc: "Kristoffer Haugsbakk" kristofferhaugsbakk@fastmail.com cc: Patrick Steinhardt ps@pks.im cc: Eric Sunshine sunshine@sunshineco.com Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1948%2Fonee-only%2Ffix-sparse-checkout-doc-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1948/onee-only/fix-sparse-checkout-doc-v2 Pull-Request: https://github.com/git/git/pull/1948 Range-diff vs v1: 1: c702bbc8782 ! 1: 6154158b98c doc: sparse-checkout: Fix list markers @@ ## Metadata ## -Author: onee-only +Author: Wonuk Kim ## Commit message ## - doc: sparse-checkout: Fix list markers + doc: sparse-checkout: use consistent inline list style - Changed the list markers from a mix of "(1)" and "(b)" to a - consistent numeric format "(1)", "(2)" for clarity and consistency. + Fix this inline list to use a single style, namely numeric, instead of + `(1)` followed by `(b)`. - Signed-off-by: onee-only + Signed-off-by: Wonuk Kim ## Documentation/technical/sparse-checkout.adoc ## @@ Documentation/technical/sparse-checkout.adoc: sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to Documentation/technical/sparse-checkout.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/technical/sparse-checkout.adoc b/Documentation/technical/sparse-checkout.adoc index dc2e763bbec..8202172b70b 100644 --- a/Documentation/technical/sparse-checkout.adoc +++ b/Documentation/technical/sparse-checkout.adoc @@ -66,7 +66,7 @@ sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to reasons: (1) users in cone mode specify directories rather than patterns (their directories are transformed into patterns, but users may think you are talking about non-cone mode if you use the - word "patterns"), and (b) the sparse specification might + word "patterns"), and (2) the sparse specification might transiently differ in the working tree or index from the sparsity patterns (see "Sparse specification vs. sparsity patterns"). base-commit: 4bbb303af69990ccd05fe3a2eb58a1ce036f8220 -- gitgitgadget ``` ## Kristoffer Haugsbakk, 2025-05-30 07:41 Subject: Re: [PATCH v2] doc: sparse-checkout: use consistent inline list style Message-ID: <956069c2-d818-472d-9d84-0190432512a2@app.fastmail.com> URL: https://gitlist.dev/e/956069c2-d818-472d-9d84-0190432512a2%40app.fastmail.com In-Reply-To: ``` On Fri, May 30, 2025, at 09:22, oneee via GitGitGadget wrote: > From: Wonuk Kim > > Fix this inline list to use a single style, namely numeric, instead of > `(1)` followed by `(b)`. > > Signed-off-by: Wonuk Kim > [snip] Looks great. Thanks. ``` ## Junio C Hamano, 2025-05-30 13:38 Subject: Re: [PATCH] doc: sparse-checkout: Fix list markers Message-ID: <871ps6b4n8.fsf@gitster.g> URL: https://gitlist.dev/e/871ps6b4n8.fsf%40gitster.g In-Reply-To: ``` Eric Sunshine writes: > You're welcome to submit an additional patch implementing Kristoffer's > suggestion. Normally, it would make sense to send them both as a > two-patch series, however, I'm not so sure that that would be a good > idea in this case. The reason I question it is that the original patch > is an obvious and uncontroversial fix, however, Kristoffer's > suggestion -- because it is a subjective change -- may get pushback > from reviewers. I had the same thought. If I were working on this topic, I'd send the original as-is with the suggested name fix, let it graduate, and then after all the dust settled, do enumeration-style changes as a new and totally independent patch, which may cover enumerations other than this single instance. Thanks. ```