Document that writing the index does not refresh the tree-cache extension#2664
Merged
Sebastian Thiel (Byron) merged 2 commits intoJun 21, 2026
Conversation
`File::write` and `File::write_to` serialize the `tree` (tree-cache) extension from its in-memory state without recomputing it from the current entries. If entries were modified, the stale tree-cache is written out, which other Git implementations misread -- e.g. `git status` showing no changes, or a commit including unexpected content. Document this on both methods and point to `State::remove_tree()` as the workaround until the tree-cache is updated on write. For GitoxideLabs#2421
- Lead with the verifiable consequence (a commit capturing stale subtree content via `git write-tree`) rather than asserting `git status` consults the tree-cache; keep the maintainer's "status and later commits can disagree about what is staged" framing as the general statement. - Make the mechanism precise: the tree-cache is written back still marked valid without being invalidated, hence stale. - Add the same caveat to the public `State::write_to`, the serializer both `File::write`/`write_to` delegate to.
Sebastian Thiel (Byron)
approved these changes
Jun 21, 2026
Sebastian Thiel (Byron)
left a comment
Sebastian Thiel (Byron)
left a comment
Member
There was a problem hiding this comment.
Thanks a lot, that's a great catch!
Let's start with that and see if eventually this shortcoming can be removed.
For now, the index is very much plumbing and as such can have such foot guns, just to accelerate certain cases that don't actually need the tree cache to be recomputed or removed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Documents a footgun on the index write methods, per #2421.
File::write,File::write_to, andState::write_toserialize thetree(tree-cache) extension from its current in-memory state — it is not recomputed or invalidated to match the entries. So if entries were modified since the index was read, the tree-cache is written back still marked valid even though it is now stale.Git uses the tree-cache to skip unchanged directories when building a tree (on
git commit/git write-tree), so a stale-but-valid tree-cache can make a later commit capture outdated subtree content; more generally,git statusand later commits can disagree about what is staged.The note points to
State::remove_tree()as the workaround until the tree-cache is updated on write:This is the documentation route (option 1) you preferred in the issue, rather than a behavior change.
Notes
File::write,File::write_to,State::write_to), with the full explanation onFile::writeand cross-references on the other two.cargo doc -p gix-index --features sha1(withRUSTDOCFLAGS=-D warnings) andcargo fmt --checkare clean.Addresses #2421.