An alternative to the read-tree
sparse checkout is the command git sparse-checkout
in cone mode (presented here)
With Git 2.34 (Q4 2021), in cone mode, the sparse-index code path learned to remove ignored files (like build artifacts) outside the sparse cone, allowing the entire directory outside the sparse cone to be removed, which is especially useful when the sparse patterns change.
See commit 716f68e (10 Aug 2021) by Junio C Hamano (gitster
).
See commit 55dfcf9, commit ce7a9f0, commit 77efbb3, commit 02155c8, commit 8a96b9d, commit 5dc1675, commit 72d84ea, commit e27eab4, commit 522d3ce (08 Sep 2021) by Derrick Stolee (derrickstolee
).
(Merged by Junio C Hamano -- gitster
-- in commit dc89c34, 20 Sep 2021)
Signed-off-by: Derrick Stolee
Reviewed-by: Elijah Newren
When changing the scope of a sparse-checkout using cone mode, we might have some tracked directories go out of scope.
The current logic removes the tracked files from within those directories, but leaves the ignored files within those directories.
This is a bit unexpected to users who have given input to Git saying they don't need those directories anymore.
This is something that is new to the cone mode pattern type: the user has explicitly said "I want these directories and not those directories." The typical sparse-checkout patterns more generally apply to "I want files with with these patterns" so it is natural to leave ignored files as they are.
This focus on directories in cone mode provides us an opportunity to change the behavior.
Leaving these ignored files in the sparse directories makes it impossible to gain performance benefits in the sparse index.
When we track into these directories, we need to know if the files are ignored or not, which might depend on the tracked .gitignore
file(s) within the sparse directory.
This depends on the indexed version of the file, so the sparse directory must be expanded.
We must take special care to look for untracked, non-ignored files in these directories before deleting them.
We do not want to delete any meaningful work that the users were doing in those directories and perhaps forgot to add and commit before switching sparse-checkout definitions.
Since those untracked files might be code files that generated ignored build output, also do not delete any ignored files from these directories in that case.
The users can recover their state by resetting their sparse-checkout definition to include that directory and continue.
Alternatively, they can see the warning that is presented and delete the directory themselves to regain the performance they expect.
By deleting the sparse directories when changing scope (or running 'git sparse-checkout
'(man) reapply) we regain these performance benefits as if the repository was in a clean state.
Since these ignored files are frequently build output or helper files from IDEs, the users should not need the files now that the tracked files are removed.
If the tracked files reappear, then they will have newer timestamps than the build artifacts, so the artifacts will need to be regenerated anyway.
Use the sparse-index as a data structure in order to find the sparse directories that can be safely deleted.
Re-expand the index to a full one if it was full before.
git sparse-checkout
now includes in its man page:
When changing the sparse-checkout patterns in cone mode, Git will inspect each
tracked directory that is not within the sparse-checkout cone to see if it
contains any untracked files. If all of those files are ignored due to the
.gitignore
patterns, then the directory will be deleted.
If any of the
untracked files within that directory is not ignored, then no deletions will
occur within that directory and a warning message will appear. If these files
are important, then reset your sparse-checkout definition so they are included,
use git add
and git commit
to store them, then remove any remaining files
manually to ensure Git can behave optimally.