{"thread":{"id":"64209","subject":"[RFC PATCH 3/4] doc: sparse-checkout.adoc: fix asciidoc warnings","startedAt":"2025-09-26T00:26:16Z","lastAt":"2025-09-26T15:46:10Z","messageCount":2,"participants":["Ramsay Jones","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"527384","messageId":"19964f5e-f553-4eda-8a62-7d0aa3017657@ramsayjones.plus.com","threadId":"64209","inReplyTo":null,"subject":"[RFC PATCH 3/4] doc: sparse-checkout.adoc: fix asciidoc warnings","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2025-09-26T00:26:14Z","receivedAt":"2025-09-26T00:26:16Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\nSigned-off-by: Ramsay Jones \n---\n Documentation/technical/sparse-checkout.adoc | 38 ++++++++++----------\n 1 file changed, 19 insertions(+), 19 deletions(-)\n\ndiff --git a/Documentation/technical/sparse-checkout.adoc b/Documentation/technical/sparse-checkout.adoc\nindex 0f750ef3e3..0701c0f90d 100644\n--- a/Documentation/technical/sparse-checkout.adoc\n+++ b/Documentation/technical/sparse-checkout.adoc\n@@ -14,7 +14,7 @@ Table of contents:\n * Reference Emails\n \n \n-=== Terminology ===\n+== Terminology ==\n \n cone mode: one of two modes for specifying the desired subset of files\n \tin a sparse-checkout. In cone-mode, the user specifies\n@@ -92,7 +92,7 @@ vivifying: When a command restores a tracked file to the working tree (and\n \tfile), this is referred to as \"vivifying\" the file.\n \n \n-=== Purpose of sparse-checkouts ===\n+== Purpose of sparse-checkouts ==\n \n sparse-checkouts exist to allow users to work with a subset of their\n files.\n@@ -255,7 +255,7 @@ will perceive the checkout as dense, and commands should thus behave as if\n all files are present.\n \n \n-=== Usecases of primary concern ===\n+== Usecases of primary concern ==\n \n Most of the rest of this document will focus on Behavior A and Behavior\n B. Some notes about the other two cases and why we are not focusing on\n@@ -300,7 +300,7 @@ Behavior C do not assume they are part of the Behavior B camp and propose\n patches that break things for the real Behavior B folks.\n \n \n-=== Oversimplified mental models ===\n+== Oversimplified mental models ==\n \n An oversimplification of the differences in the above behaviors is:\n \n@@ -313,7 +313,7 @@ An oversimplification of the differences in the above behaviors is:\n \t they can later lazily be populated instead.\n \n \n-=== Desired behavior ===\n+== Desired behavior ==\n \n As noted previously, despite the simple idea of just working with a subset\n of files, there are a range of different behavioral changes that need to be\n@@ -542,7 +542,7 @@ understanding these differences can be beneficial.\n * gitk?\n \n \n-=== Behavior classes ===\n+== Behavior classes ==\n \n From the above there are a few classes of behavior:\n \n@@ -609,7 +609,7 @@ From the above there are a few classes of behavior:\n specification.\n \n \n-=== Subcommand-dependent defaults ===\n+== Subcommand-dependent defaults ==\n \n Note that we have different defaults depending on the command for the\n desired behavior :\n@@ -749,7 +749,7 @@ desired behavior :\n implemented.\n \n \n-=== Sparse specification vs. sparsity patterns ===\n+== Sparse specification vs. sparsity patterns ==\n \n In a well-behaved situation, the sparse specification is given directly\n by the $GIT_DIR/info/sparse-checkout file. However, it can transiently\n@@ -821,7 +821,7 @@ under behavior B index operations are lumped with history and tend to\n operate full-tree.\n \n \n-=== Implementation Questions ===\n+== Implementation Questions ==\n \n * Do the options --scope={sparse,all} sound good to others? Are there better\n options?\n@@ -892,7 +892,7 @@ operate full-tree.\n is seamless for them.\n \n \n-=== Implementation Goals/Plans ===\n+== Implementation Goals/Plans ==\n \n * Get buy-in on this document in general.\n \n@@ -920,15 +920,15 @@ operate full-tree.\n commands. IMPORTANT: make sure diff machinery changes don't mess with\n format-patch, fast-export, etc.\n \n-=== Known bugs ===\n+== Known bugs ==\n \n This list used to be a lot longer (see e.g. [1,2,3,4,5,6,7,8,9]), but we've\n been working on it.\n \n-0. Behavior A is not well supported in Git. (Behavior B didn't used to\n+1. Behavior A is not well supported in Git. (Behavior B didn't used to\n be either, but was the easier of the two to implement.)\n \n-1. am and apply:\n+2. am and apply:\n \n apply, without `--index` or `--cached`, relies on files being present\n in the working copy, and also writes to them unconditionally. As\n@@ -948,7 +948,7 @@ been working on it.\n files and then complain that those vivified files would be\n overwritten by merge.\n \n-2. reset --hard:\n+3. reset --hard:\n \n reset --hard provides confusing error message (works correctly, but\n misleads the user into believing it didn't):\n@@ -971,13 +971,13 @@ been working on it.\n `git reset --hard` DID remove addme from the index and the working tree, contrary\n to the error message, but in line with how reset --hard should behave.\n \n-3. read-tree\n+4. read-tree\n \n `read-tree` doesn't apply the 'SKIP_WORKTREE' bit to *any* of the\n entries it reads into the index, resulting in all your files suddenly\n appearing to be \"deleted\".\n \n-4. Checkout, restore:\n+5. Checkout, restore:\n \n These command do not handle path & revision arguments appropriately:\n \n@@ -1030,7 +1030,7 @@ been working on it.\n S tracked\n H tracked-but-maybe-skipped\n \n-5. checkout and restore --staged, continued:\n+6. checkout and restore --staged, continued:\n \n These commands do not correctly scope operations to the sparse\n specification, and make it worse by not setting important SKIP_WORKTREE\n@@ -1046,11 +1046,11 @@ been working on it.\n the sparse specification, but then it will be important to set the\n SKIP_WORKTREE bits appropriately.\n \n-6. Performance issues; see:\n+7. Performance issues; see:\n https://lore.kernel.org/git/CABPp-BEkJQoKZsQGCYioyga_uoDQ6iBeW+FKr8JhyuuTMK1RDw@mail.gmail.com/\n \n \n-=== Reference Emails ===\n+== Reference Emails ==\n \n Emails that detail various bugs we've had in sparse-checkout:\n \n-- \n2.51.0\n"},{"id":"527429","messageId":"xmqqms6hcj3z.fsf@gitster.g","threadId":"64209","inReplyTo":"19964f5e-f553-4eda-8a62-7d0aa3017657@ramsayjones.plus.com","subject":"Re: [RFC PATCH 3/4] doc: sparse-checkout.adoc: fix asciidoc warnings","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-09-26T15:46:08Z","receivedAt":"2025-09-26T15:46:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramsay Jones writes:\n\n> Signed-off-by: Ramsay Jones \n> ---\n> Documentation/technical/sparse-checkout.adoc | 38 ++++++++++----------\n> 1 file changed, 19 insertions(+), 19 deletions(-)\n\nThe same comment about explaining your changes applies to this one.\n\n> -=== Terminology ===\n> +== Terminology ==\n\nWe've seen this in the previous step, too. No comment, no objection.\n\n> -=== Known bugs ===\n> +== Known bugs ==\n\nDitto.\n\n> This list used to be a lot longer (see e.g. [1,2,3,4,5,6,7,8,9]), but we've\n> been working on it.\n> \n> -0. Behavior A is not well supported in Git. (Behavior B didn't used to\n> +1. Behavior A is not well supported in Git. (Behavior B didn't used to\n> be either, but was the easier of the two to implement.)\n>\n> -1. am and apply:\n> +2. am and apply:\n> ... \n> -6. Performance issues; see:\n> +7. Performance issues; see:\n> https://lore.kernel.org/git/CABPp-BEkJQoKZsQGCYioyga_uoDQ6iBeW+FKr8JhyuuTMK1RDw@mail.gmail.com/\n\nOK. They want our numbered list to be base-1, first item being\nlabeled with \"1.\", not \"0.\". I think the majority of readers would\nprefer that way while reading the source text (I thought markdown\nformatters would renumber them anyway, but I probably am mistaken\nhere, like in many other things). Curious that we have \".\" after\nthese numbers, though.\n\n"}]}