# workspace-snapshot

# Workspace snapshot

Front ends that record an operation log need to undo more than a commit oid: conflict stages, worktree bytes (including conflict markers), named refs, `HEAD`, and merge/rebase sentinels must round-trip together.

[`Repository::workspace_snapshot`](https://docs.rs/grit-lib/latest/grit_lib/repo/struct.Repository.html#method.workspace_snapshot) exposes capture and restore. Stash [`create`](https://docs.rs/grit-lib/latest/grit_lib/repo_handles/struct.RepositoryStash.html#method.create) still refuses an unmerged index; use a workspace snapshot instead.

## Capture

[`WorkspaceCaptureOptions`](https://docs.rs/grit-lib/latest/grit_lib/porcelain/workspace_snapshot/struct.WorkspaceCaptureOptions.html) lists refs to store as [`RawRef`](https://docs.rs/grit-lib/latest/grit_lib/refs/store/enum.RawRef.html) values and whether untracked paths belong in the worktree tree. [`capture_workspace_snapshot`](https://docs.rs/grit-lib/latest/grit_lib/repo/struct.Repository.html#method.workspace_snapshot) writes:

- [`HeadState`](https://docs.rs/grit-lib/latest/grit_lib/state/enum.HeadState.html)
- index file bytes (all conflict stages preserved)
- a worktree tree built from on-disk file contents
- operation sentinel files under `.git` (`MERGE_*`, `sequencer/`, `rebase-merge/`, …)

## Restore

[`restore_workspace_snapshot`](https://docs.rs/grit-lib/latest/grit_lib/repo_handles/struct.RepositoryWorkspaceSnapshot.html#method.restore) updates refs and symbolic `HEAD` in one transaction, writes the index bytes, checks out the worktree tree, then restores sentinels.

Before refs move, restore builds a tree from paths in the pre-restore index (all stages) and the snapshot worktree tree, hashing only files that exist on disk. Checkout diffs that tree against the snapshot worktree tree so undoing a branch switch or uncommitted deletions restores or removes paths even when they matched `HEAD` at capture. Untracked files that appear after capture and are not in the index or snapshot tree are left alone when `include_untracked` was false at capture.

## Clearing operation state

[`Operations::clear`](https://docs.rs/grit-lib/latest/grit_lib/operation/struct.Operations.html#method.clear) (`repo.operation().clear()`) removes merge/rebase/cherry-pick sentinels without moving `HEAD` or the worktree (unlike [`abort_branch_merge`](https://docs.rs/grit-lib/latest/grit_lib/merge/struct.Merge.html#method.abort_sequence)).

## Stash apply helper

[`StashApplyOptions::overwrite_identical_untracked`](https://docs.rs/grit-lib/latest/grit_lib/stash/struct.StashApplyOptions.html#structfield.overwrite_identical_untracked) lets apply succeed when an untracked file on disk already matches the stashed untracked parent (for example after `reset --hard` left the file in place). The CLI default stays `false`.

[`StashPushOptions::new`](https://docs.rs/grit-lib/latest/grit_lib/stash/struct.StashPushOptions.html#method.new) builds push options with only a committer identity required.

## Persistence and object lifetime

Front ends that run one process per command must store a captured snapshot and reload it in a later process. With the `serde-models` feature, [`WorkspaceSnapshot`](https://docs.rs/grit-lib/latest/grit_lib/porcelain/workspace_snapshot/struct.WorkspaceSnapshot.html) implements `serde::Serialize` and `serde::Deserialize`. Serialize with a **binary** format (for example Postcard or Bincode): `index_bytes` and the values in `operation_state` are raw bytes, not JSON-friendly text. `index_mtime` is encoded as optional Unix seconds and nanoseconds.

[`capture_workspace_snapshot`](https://docs.rs/grit-lib/latest/grit_lib/repo/struct.Repository.html#method.workspace_snapshot) is non-mutating and does **not** keep objects alive. The worktree tree and any conflict-marker or untracked blobs it references are loose objects with no ref until you pin them. After `git gc --prune=now` or grit prune they become unreachable and restore will fail.

Call [`pin_workspace_snapshot`](https://docs.rs/grit-lib/latest/grit_lib/repo_handles/struct.RepositoryWorkspaceSnapshot.html#method.pin) (or [`RepositoryWorkspaceSnapshot::pin`](https://docs.rs/grit-lib/latest/grit_lib/repo_handles/struct.RepositoryWorkspaceSnapshot.html#method.pin)) with a caller-chosen id after capture. That writes `refs/grit/workspace-snapshots/<id>` pointing directly at [`WorkspaceSnapshot::worktree_tree`](https://docs.rs/grit-lib/latest/grit_lib/porcelain/workspace_snapshot/struct.WorkspaceSnapshot.html#structfield.worktree_tree). The ref is outside `refs/heads/`, so a tree oid is valid and both Git and grit garbage collection retain the tree and reachable blobs. Keep the pin until the undo entry is discarded, then [`unpin_workspace_snapshot`](https://docs.rs/grit-lib/latest/grit_lib/repo_handles/struct.RepositoryWorkspaceSnapshot.html#method.unpin) so gc can reclaim the objects.
