Skip to content

Fix CI failures on Git's master branch #1994

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
+43 −43
Closed

Fix CI failures on Git's master branch #1994

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9ab21ad
remembering-renames/sparse-checkout: renumber lists starting at zero
dscho Oct 24, 2025
a1868f6
remembering-renames/sparse-checkout: fix section levels
dscho Oct 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 24 additions & 24 deletions Documentation/technical/remembering-renames.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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):

Expand Down Expand Up @@ -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.


=== 2. 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
Expand Down Expand Up @@ -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'.


=== 3. 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:

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -285,9 +285,9 @@ 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 ===
=== 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
Expand Down Expand Up @@ -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:
Expand All @@ -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:

Expand Down Expand Up @@ -482,9 +482,9 @@ 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 ===
=== 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:

Expand Down
38 changes: 19 additions & 19 deletions Documentation/technical/sparse-checkout.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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 :
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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?
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -920,15 +920,15 @@ 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.

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
Expand All @@ -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):
Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -1046,11 +1046,11 @@ 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/


=== Reference Emails ===
== Reference Emails ==

Emails that detail various bugs we've had in sparse-checkout:

Expand Down
Loading