Module worktree 

Worktree → tree-object builder.

Walks a directory, applies .mkitignore, hashes each file as a Blob, recurses on subdirectories, validates symlink targets against path-traversal, and writes a single root Tree into the supplied ObjectStore.

Notes:

• Files at or below CHUNK_THRESHOLD are stored as a single Blob. Files above the threshold are chunked with crate::chunker::FastCdc::v1; each chunk is stored as a Blob and the file is represented by a ChunkedBlob manifest whose hash is what lands in the parent tree.
• We never follow symlinks while walking. Linux/macOS read_link reports the target verbatim and we hash it as a blob.

Structs

StatObservation

A hash-time stat observation: while building a tree we re-hashed path (its cache was absent or racy-smudged) and the result equals the staging index’s hash — so the stat captured from the OPENED file descriptor before its content was read proves the entry clean. status consumes these to heal the stat cache without ever pairing a post-verification stat with a pre-verification hash (the unsound verify-then-stat order).

Enums

LoadedBlob

A blob’s top-level object, read from the store exactly once and held so a caller needing several views of the same blob — byte length, bounded prefix, full content — pays a single top-level read_object instead of one per view. diff --stat is the motivating caller: its text-vs-binary sniff needs a prefix, then either the length (binary row) or the full content (text row), and taking each view through a separate store-level read re-read (and re-hash-verified) the same object two times per changed file, a per-entry cost that dominates a many-small-files diffstat (#624).

WorktreeError

Errors returned by this module.

Constants

CHUNK_THRESHOLD

Files larger than this go through the chunker (1 MiB).

MAX_FILE_BYTES

Hard cap on a single file (1 GiB).

Functions

build_tree

Build a tree object for dir and its subdirectories. Honours the .gitignore + .mkitignore ignore files loaded from dir.

build_tree_filtered

Like build_tree, but the caller supplies the authoritative tracked set (index). Callers that seed their index from HEAD when no index file exists yet (status, restore safety) MUST pass it here so a tracked file that matches an ignore rule is not dropped right after a checkout. None falls back to the on-disk <dir>/.mkit/index (empty if absent).

build_tree_filtered_observed

build_tree_filtered that additionally reports every StatObservation (file re-hashed to a hash matching its index entry) into observations, so callers can heal the stat cache from hash-time stats.

build_tree_from_index

Build a tree object from an Index (the staging area).

build_tree_from_index_with

build_tree_from_index writing tree objects through sink — pass a WriteBatch to amortise the flush cost of all materialised trees into the batch’s single commit. store is still needed read-only to validate that staged hashes point at blob-shaped objects (a sink cannot read).

chunked_blob_from_bytes

Build the canonical ChunkedBlob manifest for data: split with FastCdc::v1, address each chunk by its Blob object id — the hash of the chunk’s canonical Blob bytes (blob_prologue ‖ chunk), i.e. the id the chunk Blob is stored under — and set chunk_size = 0 (content-defined).

hash_file

Read a file from disk, hash it, store it, and return the content-address of the resulting object.

hash_file_object

Content-address data exactly as store_file_object would, without storing anything. Backs change detection (status, rm, restore safety checks) where only the answer “would this file hash to X?” is needed — writing objects there would turn a read-only query into store mutation. Equivalence with store_file_object is pinned by test.

hash_file_with_metadata

Hash and store a regular file, returning its content-address and the fs::Metadata observed when it was opened (for stat-cache use by callers like mkit add).

mtime_nanos

A file’s mtime as nanoseconds since the Unix epoch, saturating; 0 (the “no cache” sentinel) when the mtime is unavailable or predates the epoch.

read_blob

Reassemble the full byte content of a Blob or ChunkedBlob object addressed by hash.

read_regular_file_bounded

Read a regular file without following the final path component on Unix, enforcing MAX_FILE_BYTES against both the opened handle’s metadata and the actual bytes read.

stat_cache_fields

The full stat-cache observation for meta, in index-entry field order: (mtime_ns, size, ino, ctime_ns). The single producer-side dual of stat_matches — every site that records the cache uses this so the recorded and compared field sets can never drift. ino/ctime_ns are 0 (= don’t check) on platforms without them.

stat_matches

True iff meta proves the worktree file behind entry is byte-identical to entry.object_hash without reading it: the cached mtime is nonzero (cache present, not racy-smudged) and equal, the size is equal, the inode and ctime match when recorded (catching replace-by-rename and touch -r-style timestamp restoration — ctime cannot be set from userspace), and the live mode’s exec class matches the staged status. Symlink entries never stat-match — the target re-read is cheap and meta semantics differ.

store_file_object

Store a regular file’s bytes as the canonical object and return its content-address.

validate_symlink_target

Validate a symlink target: must be relative and contain no .. segments.

Type Aliases

WorktreeResult

Result alias used throughout this module.