Module index 

In-process reading and writing of the Git index file and its extensions. What: In-process reading and writing of the Git index file and its extensions. Why: The index format is one specification with many parts.

In TS you’d write (pseudocode):

// index/index.ts: one `export * from './file'` per module below.

Modules

index_cache_tree

In-process index update: the cache-tree extension. What: The TREE (cache-tree) index extension: read, written back byte for byte, and invalidated along a path (cache-tree.c: read_one, write_one, do_invalidate_path). Why: Git marks every directory above a changed path as not valid and drops a subtree that the path names; an in-process index update must leave the extension exactly as that does, or the next write-tree would trust a stale tree name.

index_ewah

In-process index update: Git’s EWAH bitmap, for the untracked-cache and fsmonitor extensions. What: Git’s EWAH compressed bitmap (ewah/ewah_bitmap.c, ewah/ewah_io.c): read from bytes, listed as bit positions, built by setting bits in increasing order, written back. Why: The untracked-cache and fsmonitor index extensions store bitmaps indexed by directory or entry position. Rewriting an index changes those positions, so each bitmap is decoded to its set bits and encoded again by the same algorithm Git uses, which gives the same bytes for the same bits (ewah_set is ported step for step, including its run-length corner cases).

index_flags

A read of the assume-unchanged and skip-worktree marks of an index file. What: A read of the per-entry flags of an index file that decide whether the index may seed an explicit-path commit: whether any entry is marked assume-unchanged, skip-worktree or intent-to-add. Why: A private index copied from the real index and reset to the base keeps those marks, and git add --all -- <path> then skips a marked file the commit named (assume-unchanged) or refuses it (skip-worktree), where Git’s own partial commit and the previous flow staged it; an intent-to-add entry of a tracked empty file survives the reset and is then left out of the tree, so the commit loses that file. Finding a mark needs the whole file, and a Git start for it would add a process to every commit, so the entries are read here; anything this reader does not fully understand answers “unreadable”, and the caller then builds the index the slower, always-correct way. The layout is the one in Git’s gitformat-index documentation: a 12-byte header, entries (versions 2 to 4), then extensions and a trailing checksum.

index_fsmonitor

In-process index update: the fsmonitor extension. What: The FSMN (fsmonitor) index extension: the last-update token and the bitmap of entries not known to be unchanged (fsmonitor.c: read_fsmonitor_extension, write_fsmonitor_extension, fill_fsmonitor_bitmap). Why: When fsmonitor is on, Git keeps the extension across an index write and rebuilds its bitmap from the entries: an entry it just made is not marked valid, so it is listed as dirty, and the positions follow the entries that remain. The token is kept as read; nothing here asks the monitor anything.

index_full

In-process index update: a whole index file read into entries and kept extensions. What: The whole content of an index file the in-process index update changes: every entry with its stat data and flags, and the extensions Git keeps (TREE, REUC, UNTR, FSMN), read from bytes (read-cache.c: do_read_index). Why: repo_read_index.rs keeps only path, mode, object name and stage, which is enough to list an index but not to write one back. The reader here returns None for a split index, a sparse index, a required extension it does not know, a reserved flag bit or a size that does not add up, so Git answers those. index_full_write.rs writes it.

index_full_write

In-process index update: a whole index file written as Git writes it. What: Writes a FullIndex as Git’s do_write_index does for the plain case: the version Git picks, the entries, the kept extensions in Git’s order, and the trailing checksum (read-cache.c: do_write_index, ce_write_entry). Why: The in-process index update must produce the bytes Git’s own write produces. A version 3 file with no extended flag is written as version 2; a version 4 file prefix-compresses names; the cache-tree, resolve-undo, untracked-cache and fsmonitor extensions follow in that order; the offset-table extensions are not written because the configuration that asks for them is declined before this runs.

index_reset

In-process index update: a path-limited mixed reset of an index held in memory. What: git reset <tree> -- <paths> on an index held in memory: for every path the literal pathspecs name, the entries of the index become the entries of the tree, as update_index_from_diff in builtin/reset.c leaves them. Why: A mixed reset with paths compares the tree with the index (diff_cache in diff-lib.c) and, for each difference, removes the index entry (remove_file_from_index) or adds an entry made from the tree’s mode and object name with all-zero stat data (make_cache_entry, add_index_entry in read-cache.c), so the next git status hashes the file. Every extension a change touches follows Git: the cache-tree is invalidated, the untracked cache is cleared for the path, removed unmerged entries go to resolve-undo, and the fsmonitor bitmap lists the new entries as dirty. A form whose result depends on more than that (a file-directory conflict between the tree and the index, a name Git refuses, a racily clean entry that Git would hash from the worktree) returns None, so Git answers.

index_reset_file

In-process index update: the landing’s follow-up on an index file. What: The landing’s index update without a Git process: read the private index file, reset the commit’s paths to the commit as index_reset.rs does, write the file back, and say whether it did. Why: The follow-up git reset <commit> --pathspec-from-file=- --pathspec-file-nul took a minute under the landing’s index lock on a large checkout. Everything it needed is in the repository files the wrapper already reads in process: the index, the commit’s trees and the configuration. Any index form, configuration or hook the port does not reproduce returns None and the caller runs Git’s own command (doc/planning/cli-git-main-commit-within-native-plus-five.md).

index_reset_publish

In-process index update: the lock proof, the temporary file and the file mode of the landing’s private index. What: How the in-process index update gets its result onto the landing’s private index: the name of that index, a temporary file no other run can share, Git’s file mode for an index, and the rename. Why: The update replaces index.cli-git-<batch>, the copy of the live index the landing made under its index.lock; the lock’s release then renames that copy over the live index (service_index_hold.rs, IndexLock::release_with). The update takes a borrow of the held IndexLock, so only the holder can call it, and it works on the one name private_index_path gives for that lock’s index and batch. Two runs on one target must not share a temporary name: each creates its own file exclusively and removes only that one. Git creates an index through a lock file whose mode adjust_shared_perm widens by core.sharedRepository (tempfile.c, path.c), so the file gets the same mode before it is published.

index_reset_tree

In-process index update: the trees a path-limited reset reads. What: The tree questions an in-process path reset asks: a commit’s root tree, the entries of that tree at or below given paths, and the paths that differ between two commits’ trees. Why: reset <commit> -- <paths> reads only those paths of the commit, and the landing’s follow-up lists what changed between the branch before and after; walking down the named paths reads a few small trees instead of listing a whole checkout, and equal subtrees end the comparison of two trees at once.

index_resolve_undo

In-process index update: the resolve-undo extension. What: The REUC (resolve-undo) index extension: read, recorded into when an unmerged entry leaves the index, written back (resolve-undo.c). Why: Git remembers the three sides of a path whose conflict entries it removes so git checkout -m can restore them; an in-process index update that removes or replaces unmerged entries must record them the way record_resolve_undo does.

index_settings

In-process index update: the configuration that decides the extensions and the decline cases. What: The configuration that decides what Git does to the extensions of an index it reads and writes, and whether the in-process index update may stand in for Git at all (repo-settings.c, fsmonitor-settings.c, read-cache.c). Why: core.untrackedCache makes Git keep, add or remove the untracked cache; core.fsmonitor makes it keep the fsmonitor extension and clear the untracked cache of replaced entries, and drop the extension when it is off; split and sparse indexes, the offset-table extensions, skipped hashes and a case-insensitive worktree change the file layout or the checks. Any key this module cannot reproduce makes the update decline, so Git answers it.

index_stat

In-process index update: stat fields and Git’s varint. What: The nine 32-bit stat fields an index entry and the untracked-cache extension store, and the Git varint. Why: Both file layouts write the same fields (the entry puts the mode between inode and owner), and both use Git’s offset varint for lengths; one definition keeps the readers and writers of the in-process index update in step.

index_untracked

In-process index update: the untracked-cache extension as directories, and its invalidation. What: The UNTR (untracked cache) index extension as a tree of directories, and its invalidation along a path (dir.c: invalidate_one_component, lookup_untracked, invalidate_one_directory). Why: Git clears the cached listing of the directory of every path it adds or removes in the index, and past it up to the top when the cache lists whole untracked directories; an in-process index update must clear exactly those, creating the directories along the path that the cache did not know, as lookup_untracked does. Reading and writing the extension are in index_untracked_io.rs.

index_untracked_io

In-process index update: reading and writing the untracked-cache extension. What: Reading and writing the UNTR index extension (dir.c: read_untracked_extension, write_untracked_extension). Why: The extension is kept across an in-process index update, so it is decoded to directories and encoded again with the same layout: directories in preorder, then three bitmaps (valid, check-only, has-exclude-object) indexed by that order, then the stat records and object names of the flagged directories.