Crate filesnap 

Git-free file snapshots and rewind.

Content-addressed blobs, stat-cached manifests, per-session snapshot logs with mark-and-sweep collection, and a restore planner that captures a rescue point before it writes and deletes only against a tombstone.

The engine knows nothing about its host: it takes opaque string ids and absolute paths, and never reads or writes the user’s git state. Git appears only as one source of file names, and a directory that has never seen git init is a first-class workspace.

What is covered, and what is not

A file enters the tracked set three ways: the project’s git index lists it, a recency walk finds it, or an edit declares it. Each has a shape worth knowing:

• the index cannot see an untracked file;
• the recency walk skips hidden directories and a fixed list of build directories, drops files over ScanLimits::max_file_bytes, and keeps at most ScanLimits::max_files paths per root;
• a declared path stays watched for as long as DeclaredWindow says, which the host chooses per session and may set to DeclaredWindow::Unlimited.

So a file created by a shell command inside target/, inside a dotted directory, over the size limit, or beyond the recency budget on a busy turn is covered only if it also flowed through the host’s edit API. This is a real gap and it is stated rather than implied: total coverage is not promised, and scan_report answers “what in my project is not protected” for any particular workspace.

The rules this crate is built to keep, and the places it does not yet keep them, are in .specify/memory/constitution.md and .specify/memory/compliance.md.

Structs

ApplyStats

What an apply managed, and what it could not.

BlobStore

Checkpoint

CheckpointStats

DeclareOutcome

What a declare did.

DeleteOutcome

What a delete did, and what it declined to touch.

FileEntry

GcStats

Gitignore

Gitignore is a matcher for the globs in one or more gitignore files in the same directory.

GitignoreBuilder

Builds a matcher for a single set of globs from a .gitignore file.

Manifest

ManifestStore

Recent

What one root’s recency pass picked up, and what it passed over.

RefStore

RestoreOutcome

RestorePlan

RestoreTarget

The state a restore moves the workspace to.

Scan

What a scan picked up, and what it passed over.

ScanLimits

What bounds the recency partition.

SnapshotRef

SnapshotTracker

A session’s tracking decision plus the scope it captures at.

ThreadLog

TurnScope

Where a turn is happening, and how far a scan may reach.

WorkspaceKey

Identifies one workspace’s partition.

WorkspaceStore

One workspace’s records, plus the content store they share with every other workspace.

WriteAction

Enums

DeclaredWindow

How long a declared path keeps being watched after the turn that last declared it.

DropReason

Why a file the scan saw is not in the snapshot.

HiddenFiles

Whether a scan descends into dot-files and dot-directories.

PreEditImage

What a path held immediately before an edit changed it.

RestoreKind

Which direction a restore moves the workspace’s undo history, and whose undo stack it touches.

SessionStart

How this session’s tracking state is decided. Fixed at session start; it never changes while the session runs, so a session’s snapshot chain is always complete-from-the-first-turn or absent.

SnapshotError

Constants

DECLARED_WINDOW_TURNS

The default window, and a default rather than a rule — see DeclaredWindow.

DROP_SAMPLE_LIMIT

How many drops a per-turn report carries. Small: it is printed every turn, and the reader wants a hint, not an inventory.

FORMAT_VERSION

The format version this build reads and writes.

RESTORE_TMP_SUFFIX

Suffix of the sibling a restore writes before renaming into place.

SAFETY_TURN_PREFIX

Turn-id prefix for the safety checkpoint recorded before every restore.

SNAPSHOT_IGNORE_FILENAME

Name of the dedicated snapshot ignore file, in gitignore syntax.

Functions

apply_plan

Apply a plan: write blob contents (atomically, restoring permissions) and remove paths the target recorded as absent. Missing targets are fine.

canonical_key

One spelling of a path, so a manifest key does not depend on how the caller happened to write it.

capture

Capture the state of files into a new persisted manifest.

capture_turn

Capture the state of scope at the start of turn_id.

collect_garbage

Reclaim what nothing references, across every workspace in the store.

content_disk_usage

How many bytes the shared content store holds.

declare_edits

Record what pre_images held before an edit changes them, and register the paths so later captures keep watching them.

find_workspace_root

Git-style marker walk-up: return the nearest ancestor of start (inclusive) containing one of markers.

git_tracked_files

Files the project’s own index lists that lie under root.

is_ignored

Symmetric protection check: is path invisible to snapshot operations?

load_ignore

Compile the ignore matcher for root from its snapshot ignore file. A missing ignore file yields an empty matcher (nothing ignored).

mode_of

Permission bits to record for a file (mode & 0o7777), or None where the platform has none to report.

mtime_parts

Extract (secs, nanos) of the mtime relative to the unix epoch. Pre-epoch or unreadable mtimes collapse to (0, 0), which simply disables the stat-cache fast path for that file.

plan_restore

Plan the move from current to target.

recent_files

The most recently modified files under dir that covered does not already account for — the residue partition.

residue_in

Stray restore temporaries in dir that are old enough to be nobody’s.

residue_under

Every stray restore temporary under root, wherever a restore reached.

restore_scope

What a restore must be asked to look at.

scan_report

Everything in roots the scan would leave out of a snapshot, with reasons.

tracked_files

Everything a capture should look at: the three partitions over roots, plus already_known — paths this thread has observed before, whatever partition first brought them in.

Type Aliases

Drop

A file left out of the snapshot, and why.

Result