From 9ab21adc742e3ce430c8f8a84f087e6a198c20dc Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Fri, 24 Oct 2025 15:48:00 +0200 Subject: [PATCH 1/2] remembering-renames/sparse-checkout: renumber lists starting at zero In 52751000bc9 (doc: add some missing technical documents, 2025-10-02), some documents were added to the default set of files to be rendered. Unfortunately, this led to CI failures since Oct 10 (see https://github.com/git/git/actions/runs/18418984731), the eight most recent pushes of Git's `master` as of time of writing. Due to the way Git's automation is set up, it is quite difficult to get to the actual problems, as some known-bogus warnings get suppressed in the check that fails the job, but those warnings are _not_ suppressed in the failed jobs' logs. The actual problems look like this: asciidoc: WARNING: remembering-renames.adoc: line 13: list item index: expected 1 got 0 asciidoc: WARNING: remembering-renames.adoc: line 15: list item index: expected 2 got 1 asciidoc: WARNING: remembering-renames.adoc: line 17: list item index: expected 3 got 2 asciidoc: WARNING: remembering-renames.adoc: line 20: list item index: expected 4 got 3 asciidoc: WARNING: remembering-renames.adoc: line 23: list item index: expected 5 got 4 asciidoc: WARNING: remembering-renames.adoc: line 25: list item index: expected 6 got 5 asciidoc: WARNING: remembering-renames.adoc: line 29: list item index: expected 7 got 6 asciidoc: WARNING: remembering-renames.adoc: line 31: list item index: expected 8 got 7 asciidoc: WARNING: remembering-renames.adoc: line 33: list item index: expected 9 got 8 asciidoc: WARNING: remembering-renames.adoc: line 38: section title out of sequence: expected level 1, got level 2 asciidoc: WARNING: sparse-checkout.adoc: line 17: section title out of sequence: expected level 1, got level 2 asciidoc: WARNING: sparse-checkout.adoc: line 928: list item index: expected 1 got 0 asciidoc: WARNING: sparse-checkout.adoc: line 931: list item index: expected 2 got 1 asciidoc: WARNING: sparse-checkout.adoc: line 951: list item index: expected 3 got 2 asciidoc: WARNING: sparse-checkout.adoc: line 974: list item index: expected 4 got 3 asciidoc: WARNING: sparse-checkout.adoc: line 980: list item index: expected 5 got 4 asciidoc: WARNING: sparse-checkout.adoc: line 1033: list item index: expected 6 got 5 asciidoc: WARNING: sparse-checkout.adoc: line 1049: list item index: expected 7 got 6 The problems fall into two categories. The first one is that there are two lists that start at zero instead of 1, which is unexpected for AsciiDoc. In the same spirit as fef11965da8 (Renumber list in api-command.txt, 2012-12-15), let's simply renumber those lists. The second category will be addressed in a separate commit. Signed-off-by: Johannes Schindelin --- .../technical/remembering-renames.adoc | 36 +++++++++---------- Documentation/technical/sparse-checkout.adoc | 14 ++++---- 2 files changed, 25 insertions(+), 25 deletions(-) diff --git a/Documentation/technical/remembering-renames.adoc b/Documentation/technical/remembering-renames.adoc index 73f41761e2090a..e78f0e37925157 100644 --- a/Documentation/technical/remembering-renames.adoc +++ b/Documentation/technical/remembering-renames.adoc @@ -10,32 +10,32 @@ history as an optimization, assuming all merges are automatic and clean Outline: - 0. Assumptions + 1. Assumptions - 1. How rebasing and cherry-picking work + 2. How rebasing and cherry-picking work - 2. Why the renames on MERGE_SIDE1 in any given pick are *always* a + 3. Why the renames on MERGE_SIDE1 in any given pick are *always* a superset of the renames on MERGE_SIDE1 for the next pick. - 3. Why any rename on MERGE_SIDE1 in any given pick is _almost_ always also + 4. Why any rename on MERGE_SIDE1 in any given pick is _almost_ always also a rename on MERGE_SIDE1 for the next pick - 4. A detailed description of the counter-examples to #3. + 5. A detailed description of the counter-examples to #3. - 5. Why the special cases in #4 are still fully reasonable to use to pair + 6. Why the special cases in #4 are still fully reasonable to use to pair up files for three-way content merging in the merge machinery, and why they do not affect the correctness of the merge. - 6. Interaction with skipping of "irrelevant" renames + 7. Interaction with skipping of "irrelevant" renames - 7. Additional items that need to be cached + 8. Additional items that need to be cached - 8. How directory rename detection interacts with the above and why this + 9. How directory rename detection interacts with the above and why this optimization is still safe even if merge.directoryRenames is set to "true". -=== 0. Assumptions === +=== 1. Assumptions === There are two assumptions that will hold throughout this document: @@ -91,7 +91,7 @@ this config setting, but we have to discuss a few more cases to show why; this discussion is deferred until section 8. -=== 1. How rebasing and cherry-picking work === +=== 2. How rebasing and cherry-picking work === Consider the following setup (from the git-rebase manpage): @@ -138,7 +138,7 @@ Conceptually the two statements above are the same as a three-way merge of B, B', and C, at least the parts before you decide to record a commit. -=== 2. Why the renames on MERGE_SIDE1 in any given pick are always a === +=== 3. Why the renames on MERGE_SIDE1 in any given pick are always a === === superset of the renames on MERGE_SIDE1 for the next pick. === The merge machinery uses the filenames it is fed from MERGE_BASE, @@ -181,7 +181,7 @@ are a subset of those between E and G. Equivalently, all renames between E and G are a superset of those between A and A'. -=== 3. Why any rename on MERGE_SIDE1 in any given pick is _almost_ === +=== 4. Why any rename on MERGE_SIDE1 in any given pick is _almost_ === === always also a rename on MERGE_SIDE1 for the next pick. === Let's again look at the first two picks: @@ -254,7 +254,7 @@ were detected as renames, A:oldfile and A':newfile should also be detectable as renames almost always. -=== 4. A detailed description of the counter-examples to #3. === +=== 5. A detailed description of the counter-examples to #3. === We already noted in section 3 that rename/rename(1to1) (i.e. both sides renaming a file the same way) was one counter-example. The more @@ -285,7 +285,7 @@ E:oldfile -> G:newfile would be detected as a rename, but A:oldfile and A':newfile would not be. -=== 5. Why the special cases in #4 are still fully reasonable to use to === +=== 6. Why the special cases in #4 are still fully reasonable to use to === === pair up files for three-way content merging in the merge machinery, === === and why they do not affect the correctness of the merge. === @@ -394,7 +394,7 @@ cases 1 and 3 seem to provide as good or better behavior with the optimization than without. -=== 6. Interaction with skipping of "irrelevant" renames === +=== 7. Interaction with skipping of "irrelevant" renames === Previous optimizations involved skipping rename detection for paths considered to be "irrelevant". See for example the following commits: @@ -421,7 +421,7 @@ detection -- though we can limit it to the paths for which we have not already detected renames. -=== 7. Additional items that need to be cached === +=== 8. Additional items that need to be cached === It turns out we have to cache more than just renames; we also cache: @@ -482,7 +482,7 @@ we store the trees to compare with what we are asked to merge next time. -=== 8. How directory rename detection interacts with the above and === +=== 9. How directory rename detection interacts with the above and === === why this optimization is still safe even if === === merge.directoryRenames is set to "true". === diff --git a/Documentation/technical/sparse-checkout.adoc b/Documentation/technical/sparse-checkout.adoc index 0f750ef3e36120..5c4030ad29cfc5 100644 --- a/Documentation/technical/sparse-checkout.adoc +++ b/Documentation/technical/sparse-checkout.adoc @@ -925,10 +925,10 @@ operate full-tree. This list used to be a lot longer (see e.g. [1,2,3,4,5,6,7,8,9]), but we've been working on it. -0. Behavior A is not well supported in Git. (Behavior B didn't used to +1. Behavior A is not well supported in Git. (Behavior B didn't used to be either, but was the easier of the two to implement.) -1. am and apply: +2. am and apply: apply, without `--index` or `--cached`, relies on files being present in the working copy, and also writes to them unconditionally. As @@ -948,7 +948,7 @@ been working on it. files and then complain that those vivified files would be overwritten by merge. -2. reset --hard: +3. reset --hard: reset --hard provides confusing error message (works correctly, but misleads the user into believing it didn't): @@ -971,13 +971,13 @@ been working on it. `git reset --hard` DID remove addme from the index and the working tree, contrary to the error message, but in line with how reset --hard should behave. -3. read-tree +4. read-tree `read-tree` doesn't apply the 'SKIP_WORKTREE' bit to *any* of the entries it reads into the index, resulting in all your files suddenly appearing to be "deleted". -4. Checkout, restore: +5. Checkout, restore: These command do not handle path & revision arguments appropriately: @@ -1030,7 +1030,7 @@ been working on it. S tracked H tracked-but-maybe-skipped -5. checkout and restore --staged, continued: +6. checkout and restore --staged, continued: These commands do not correctly scope operations to the sparse specification, and make it worse by not setting important SKIP_WORKTREE @@ -1046,7 +1046,7 @@ been working on it. the sparse specification, but then it will be important to set the SKIP_WORKTREE bits appropriately. -6. Performance issues; see: +7. Performance issues; see: https://lore.kernel.org/git/CABPp-BEkJQoKZsQGCYioyga_uoDQ6iBeW+FKr8JhyuuTMK1RDw@mail.gmail.com/ From a1868f6a8e74d50f6cd828cc25525dec98e646ba Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Fri, 24 Oct 2025 15:59:04 +0200 Subject: [PATCH 2/2] remembering-renames/sparse-checkout: fix section levels In 52751000bc9 (doc: add some missing technical documents, 2025-10-02), some documents were added to the default set of files to be rendered. Unfortunately, this led to CI failures since Oct 10 (see https://github.com/git/git/actions/runs/18418984731), the eight most recent pushes of Git's `master` as of time of writing. In the preceding commit, the numbered lists that started at zero (which AsciiDoc cannot handle) were changed, but there are still the following problems: asciidoctor: WARNING: remembering-renames.adoc: line 38: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 94: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 141: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 142: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 184: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 185: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 257: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 288: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 289: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 290: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 397: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 424: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 485: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 486: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 487: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 17: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 95: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 258: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 303: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 316: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 545: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 612: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 752: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 824: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 895: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 923: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 1053: section title out of sequence: expected level 1, got level 2 Let's change the level of the sections to fix those warnings, too. Signed-off-by: Johannes Schindelin --- .../technical/remembering-renames.adoc | 30 +++++++++---------- Documentation/technical/sparse-checkout.adoc | 24 +++++++-------- 2 files changed, 27 insertions(+), 27 deletions(-) diff --git a/Documentation/technical/remembering-renames.adoc b/Documentation/technical/remembering-renames.adoc index e78f0e37925157..8a2e49250cc43c 100644 --- a/Documentation/technical/remembering-renames.adoc +++ b/Documentation/technical/remembering-renames.adoc @@ -35,7 +35,7 @@ Outline: "true". -=== 1. Assumptions === +== 1. Assumptions == There are two assumptions that will hold throughout this document: @@ -91,7 +91,7 @@ this config setting, but we have to discuss a few more cases to show why; this discussion is deferred until section 8. -=== 2. How rebasing and cherry-picking work === +== 2. How rebasing and cherry-picking work == Consider the following setup (from the git-rebase manpage): @@ -138,8 +138,8 @@ Conceptually the two statements above are the same as a three-way merge of B, B', and C, at least the parts before you decide to record a commit. -=== 3. Why the renames on MERGE_SIDE1 in any given pick are always a === -=== superset of the renames on MERGE_SIDE1 for the next pick. === +== 3. Why the renames on MERGE_SIDE1 in any given pick are always a == +== superset of the renames on MERGE_SIDE1 for the next pick. == The merge machinery uses the filenames it is fed from MERGE_BASE, MERGE_SIDE1, and MERGE_SIDE2. It will only move content to a different @@ -181,8 +181,8 @@ are a subset of those between E and G. Equivalently, all renames between E and G are a superset of those between A and A'. -=== 4. Why any rename on MERGE_SIDE1 in any given pick is _almost_ === -=== always also a rename on MERGE_SIDE1 for the next pick. === +== 4. Why any rename on MERGE_SIDE1 in any given pick is _almost_ == +== always also a rename on MERGE_SIDE1 for the next pick. == Let's again look at the first two picks: @@ -254,7 +254,7 @@ were detected as renames, A:oldfile and A':newfile should also be detectable as renames almost always. -=== 5. A detailed description of the counter-examples to #3. === +== 5. A detailed description of the counter-examples to #3. == We already noted in section 3 that rename/rename(1to1) (i.e. both sides renaming a file the same way) was one counter-example. The more @@ -285,9 +285,9 @@ E:oldfile -> G:newfile would be detected as a rename, but A:oldfile and A':newfile would not be. -=== 6. Why the special cases in #4 are still fully reasonable to use to === -=== pair up files for three-way content merging in the merge machinery, === -=== and why they do not affect the correctness of the merge. === +== 6. Why the special cases in #4 are still fully reasonable to use to == +== pair up files for three-way content merging in the merge machinery, == +== and why they do not affect the correctness of the merge. == In the rename/rename(1to1) case, A:newfile and A':newfile are not renames since they use the *same* filename. However, files with the same filename @@ -394,7 +394,7 @@ cases 1 and 3 seem to provide as good or better behavior with the optimization than without. -=== 7. Interaction with skipping of "irrelevant" renames === +== 7. Interaction with skipping of "irrelevant" renames == Previous optimizations involved skipping rename detection for paths considered to be "irrelevant". See for example the following commits: @@ -421,7 +421,7 @@ detection -- though we can limit it to the paths for which we have not already detected renames. -=== 8. Additional items that need to be cached === +== 8. Additional items that need to be cached == It turns out we have to cache more than just renames; we also cache: @@ -482,9 +482,9 @@ we store the trees to compare with what we are asked to merge next time. -=== 9. How directory rename detection interacts with the above and === -=== why this optimization is still safe even if === -=== merge.directoryRenames is set to "true". === +== 9. How directory rename detection interacts with the above and == +== why this optimization is still safe even if == +== merge.directoryRenames is set to "true". == As noted in the assumptions section: diff --git a/Documentation/technical/sparse-checkout.adoc b/Documentation/technical/sparse-checkout.adoc index 5c4030ad29cfc5..0701c0f90d686f 100644 --- a/Documentation/technical/sparse-checkout.adoc +++ b/Documentation/technical/sparse-checkout.adoc @@ -14,7 +14,7 @@ Table of contents: * Reference Emails -=== Terminology === +== Terminology == cone mode: one of two modes for specifying the desired subset of files in a sparse-checkout. In cone-mode, the user specifies @@ -92,7 +92,7 @@ vivifying: When a command restores a tracked file to the working tree (and file), this is referred to as "vivifying" the file. -=== Purpose of sparse-checkouts === +== Purpose of sparse-checkouts == sparse-checkouts exist to allow users to work with a subset of their files. @@ -255,7 +255,7 @@ will perceive the checkout as dense, and commands should thus behave as if all files are present. -=== Usecases of primary concern === +== Usecases of primary concern == Most of the rest of this document will focus on Behavior A and Behavior B. Some notes about the other two cases and why we are not focusing on @@ -300,7 +300,7 @@ Behavior C do not assume they are part of the Behavior B camp and propose patches that break things for the real Behavior B folks. -=== Oversimplified mental models === +== Oversimplified mental models == An oversimplification of the differences in the above behaviors is: @@ -313,7 +313,7 @@ An oversimplification of the differences in the above behaviors is: they can later lazily be populated instead. -=== Desired behavior === +== Desired behavior == As noted previously, despite the simple idea of just working with a subset of files, there are a range of different behavioral changes that need to be @@ -542,7 +542,7 @@ understanding these differences can be beneficial. * gitk? -=== Behavior classes === +== Behavior classes == From the above there are a few classes of behavior: @@ -609,7 +609,7 @@ From the above there are a few classes of behavior: specification. -=== Subcommand-dependent defaults === +== Subcommand-dependent defaults == Note that we have different defaults depending on the command for the desired behavior : @@ -749,7 +749,7 @@ desired behavior : implemented. -=== Sparse specification vs. sparsity patterns === +== Sparse specification vs. sparsity patterns == In a well-behaved situation, the sparse specification is given directly by the $GIT_DIR/info/sparse-checkout file. However, it can transiently @@ -821,7 +821,7 @@ under behavior B index operations are lumped with history and tend to operate full-tree. -=== Implementation Questions === +== Implementation Questions == * Do the options --scope={sparse,all} sound good to others? Are there better options? @@ -892,7 +892,7 @@ operate full-tree. is seamless for them. -=== Implementation Goals/Plans === +== Implementation Goals/Plans == * Get buy-in on this document in general. @@ -920,7 +920,7 @@ operate full-tree. commands. IMPORTANT: make sure diff machinery changes don't mess with format-patch, fast-export, etc. -=== Known bugs === +== Known bugs == This list used to be a lot longer (see e.g. [1,2,3,4,5,6,7,8,9]), but we've been working on it. @@ -1050,7 +1050,7 @@ been working on it. https://lore.kernel.org/git/CABPp-BEkJQoKZsQGCYioyga_uoDQ6iBeW+FKr8JhyuuTMK1RDw@mail.gmail.com/ -=== Reference Emails === +== Reference Emails == Emails that detail various bugs we've had in sparse-checkout: