Struct Repository 

pub struct Repository { /* private fields */ }

The Suture Repository.

Implementations

impl Repository

pub fn init(path: &Path, author: &str) -> Result<Self, RepoError>

Initialize a new Suture repository at the given path.

pub fn open(path: &Path) -> Result<Self, RepoError>

Reconstructs the full DAG from the metadata database by loading all stored patches and their edges.

pub fn open_in_memory() -> Result<Self, RepoError>

Open an in-memory repository for testing or embedded use.

Creates a repository backed entirely by in-memory storage. No filesystem I/O occurs except for the initial tempdir creation. The CAS uses a temporary directory that is cleaned up on drop.

pub fn create_branch( &mut self, name: &str, target: Option<&str>, ) -> Result<(), RepoError>

Create a new branch.

pub fn head(&self) -> Result<(String, PatchId), RepoError>

Get the current branch and its target.

Reads the head_branch config key to determine which branch is currently checked out. Falls back to “main” if not set.

pub fn list_branches(&self) -> Vec<(String, PatchId)>

List all branches.

pub fn delete_branch(&mut self, name: &str) -> Result<(), RepoError>

Delete a branch. Cannot delete the currently checked-out branch.

pub fn get_config(&self, key: &str) -> Result<Option<String>, RepoError>

Get a configuration value.

Lookup order:

1. .suture/config file (repo-level TOML config)
2. SQLite config table (set via suture config key=value)
3. Global config ~/.config/suture/config.toml

pub fn set_config(&mut self, key: &str, value: &str) -> Result<(), RepoError>

Set a configuration value.

pub fn list_config(&self) -> Result<Vec<(String, String)>, RepoError>

List all configuration key-value pairs.

pub fn create_tag( &mut self, name: &str, target: Option<&str>, ) -> Result<(), RepoError>

Create a tag pointing to a patch ID (or HEAD).

Tags are stored as config entries tag.<name> pointing to a patch hash.

pub fn delete_tag(&mut self, name: &str) -> Result<(), RepoError>

Delete a tag. Returns an error if the tag does not exist.

pub fn list_tags(&self) -> Result<Vec<(String, PatchId)>, RepoError>

List all tags as (name, target_patch_id).

pub fn resolve_tag(&self, name: &str) -> Result<Option<PatchId>, RepoError>

Resolve a tag name to a patch ID.

pub fn add_note(&self, patch_id: &PatchId, note: &str) -> Result<(), RepoError>

Add a note to a commit.

pub fn list_notes(&self, patch_id: &PatchId) -> Result<Vec<String>, RepoError>

List notes for a commit.

pub fn remove_note( &self, patch_id: &PatchId, index: usize, ) -> Result<(), RepoError>

Remove a note from a commit. Returns an error if the index is out of range.

pub fn patches_since(&self, since_id: &PatchId) -> Vec<Patch>

Get patches created after a given patch ID (ancestry walk).

Returns patches reachable from branch tips but NOT ancestors of since_id.

pub fn status(&self) -> Result<RepoStatus, RepoError>

Get repository status.

pub fn add(&self, path: &str) -> Result<(), RepoError>

Add a file to the staging area (working set).

pub fn add_all(&self) -> Result<usize, RepoError>

Add all files (respecting .sutureignore).

pub fn commit(&mut self, message: &str) -> Result<PatchId, RepoError>

Create a commit from the working set.

pub fn has_uncommitted_changes(&self) -> Result<bool, RepoError>

pub fn stash_push(&mut self, message: Option<&str>) -> Result<usize, RepoError>

pub fn stash_pop(&mut self) -> Result<(), RepoError>

pub fn stash_apply(&mut self, index: usize) -> Result<(), RepoError>

pub fn stash_list(&self) -> Result<Vec<StashEntry>, RepoError>

pub fn stash_drop(&mut self, index: usize) -> Result<(), RepoError>

pub fn snapshot_head(&self) -> Result<FileTree, RepoError>

Build a FileTree snapshot for the HEAD commit.

Returns a cached snapshot if the HEAD has not changed since the last call, making this O(1) instead of O(n) where n = total patches.

pub fn invalidate_head_cache(&self)

Invalidate the cached HEAD snapshot and branch name.

Must be called after any operation that changes the HEAD pointer, including branch updates from external sources (e.g., fetch/pull).

pub fn snapshot(&self, patch_id: &PatchId) -> Result<FileTree, RepoError>

Build a FileTree snapshot for a specific patch.

Tries loading from SQLite first (O(1)), falls back to patch replay (O(n)).

pub fn sync_working_tree(&self, old_tree: &FileTree) -> Result<(), RepoError>

Sync the working tree to match the current HEAD snapshot.

Compares old_tree (the state before the operation) against the current HEAD snapshot and applies file additions, modifications, deletions, and renames to disk. Update the working tree to match the current HEAD snapshot.

Compares old_tree (the state before the operation) against the current HEAD snapshot and applies file additions, modifications, deletions, and renames to disk.

pub fn checkout(&mut self, branch_name: &str) -> Result<FileTree, RepoError>

Checkout a branch, updating the working tree to match its tip state.

This operation:

1. Builds the target FileTree from the branch’s patch chain
2. Compares against the current working tree
3. Updates files (add/modify/delete) to match the target
4. Updates the HEAD reference

Refuses to checkout if there are uncommitted staged changes.

pub fn diff( &self, from: Option<&str>, to: Option<&str>, ) -> Result<Vec<DiffEntry>, RepoError>

Compute the diff between two commits or branches.

If from is None, compares the empty tree to to.

pub fn diff_staged(&self) -> Result<Vec<DiffEntry>, RepoError>

Show staged changes (diff of staged files vs HEAD).

pub fn reset( &mut self, target: &str, mode: ResetMode, ) -> Result<PatchId, RepoError>

Reset HEAD to a specific commit.

Resolves target (hex hash or branch name), moves the current branch pointer, and optionally clears staging and/or restores the working tree depending on mode.

Returns the resolved target patch ID.

pub fn revert( &mut self, patch_id: &PatchId, message: Option<&str>, ) -> Result<PatchId, RepoError>

Revert a commit by creating a new patch that undoes its changes.

The revert creates inverse patches (Delete for Create, etc.) and commits them on top of HEAD, then syncs the working tree.

pub fn squash( &mut self, count: usize, message: &str, ) -> Result<PatchId, RepoError>

Squash the last N patches on the current branch into a single patch.

Returns the new tip patch ID.

pub fn merge_plan( &self, branch_a: &str, branch_b: &str, ) -> Result<MergeResult, RepoError>

Compute a merge plan between two branches.

pub fn preview_merge( &self, source_branch: &str, ) -> Result<MergeExecutionResult, RepoError>

Execute a merge of source_branch into the current HEAD branch.

For clean merges (no conflicts):

1. Collect unique patches from both branches (after LCA)
2. Apply the source branch’s tree onto HEAD’s working tree
3. Create a merge commit (patch with two parents)
4. Update the working tree to reflect the merge result

For merges with conflicts:

1. Apply all non-conflicting patches from source
2. Return a MergeExecutionResult with conflict details
3. The caller can then resolve conflicts and commit

Preview a merge without modifying the repository.

Returns the same MergeExecutionResult that execute_merge would produce, but without creating any patches, moving branches, or writing files. The merge_patch_id and unresolved_conflicts fields are computed heuristically (the patch ID is a placeholder since no patch is actually created).

pub fn execute_merge( &mut self, source_branch: &str, ) -> Result<MergeExecutionResult, RepoError>

Execute a merge: applies patches from source_branch into the current branch.

pub fn cherry_pick(&mut self, patch_id: &PatchId) -> Result<PatchId, RepoError>

Cherry-pick a patch onto the current HEAD branch.

Creates a new patch with the same changes (operation_type, touch_set, target_path, payload) but with the current HEAD as its parent.

pub fn rebase(&mut self, target_branch: &str) -> Result<RebaseResult, RepoError>

Rebase the current branch onto a target branch.

Finds commits unique to the current branch (after the LCA with target), then replays them onto the target branch tip. Updates the current branch pointer to the new tip.

pub fn commit_groups(&self, patches: &[Patch]) -> Vec<Vec<Patch>>

Group a patch chain into logical commits.

A “logical commit” is a contiguous chain of per-file patches that share the same message. Returns groups in oldest-first order (root to tip).

pub fn patches_since_base(&self, base: &PatchId) -> Vec<Patch>

Get patches between a base commit and HEAD (exclusive of base).

Walks the first-parent chain from HEAD back to base, collecting all patches that are NOT ancestors of base.

pub fn generate_rebase_todo(&self, base: &PatchId) -> Result<String, RepoError>

Generate a TODO file for interactive rebase.

Returns the TODO file content as a string.

pub fn parse_rebase_todo( &self, todo_content: &str, base: &PatchId, ) -> Result<RebasePlan, RepoError>

Parse a TODO file into a rebase plan.

pub fn rebase_interactive( &mut self, plan: &RebasePlan, onto: &PatchId, ) -> Result<PatchId, RepoError>

Execute an interactive rebase plan.

Replays commits according to the plan, handling pick/reword/edit/squash/drop. Returns the new tip patch ID.

pub fn load_rebase_state(&self) -> Result<Option<RebaseState>, RepoError>

Load interactive rebase state.

pub fn rebase_abort(&mut self) -> Result<(), RepoError>

Abort an in-progress interactive rebase.

Restores the branch to its original position before rebase started.

pub fn blame(&self, path: &str) -> Result<Vec<BlameEntry>, RepoError>

Show per-line commit attribution for a file.

Returns a vector of BlameEntry tuples, one per line in the file at HEAD.

pub fn log(&self, branch: Option<&str>) -> Result<Vec<Patch>, RepoError>

Get the patch history (log) for a branch (first-parent chain only).

pub fn log_all(&self, branch: Option<&str>) -> Result<Vec<Patch>, RepoError>

Get the full patch history for a branch, including all reachable commits (not just the first-parent chain). Merged branch commits are included.

pub fn root(&self) -> &Path

Get the repository root path.

pub fn dag(&self) -> &PatchDag

Get a reference to the DAG.

pub fn dag_mut(&mut self) -> &mut PatchDag

Get a mutable reference to the DAG.

pub fn meta(&self) -> &MetadataStore

Get a reference to the metadata store.

pub fn cas(&self) -> &BlobStore

Get a reference to the CAS.

pub fn add_remote(&self, name: &str, url: &str) -> Result<(), RepoError>

Add a remote Hub. Stores the remote URL in metadata config as “remote..url”.

pub fn list_remotes(&self) -> Result<Vec<(String, String)>, RepoError>

List configured remotes.

pub fn remove_remote(&self, name: &str) -> Result<(), RepoError>

Remove a configured remote.

pub fn is_worktree(&self) -> bool

Check whether this repository is a linked worktree.

pub fn add_worktree( &mut self, name: &str, path: &Path, branch: Option<&str>, ) -> Result<(), RepoError>

Add a worktree. Creates a new directory linked to this repo’s data.

pub fn list_worktrees(&self) -> Result<Vec<WorktreeEntry>, RepoError>

List all worktrees. Returns the main worktree plus any linked worktrees.

pub fn remove_worktree(&mut self, name: &str) -> Result<(), RepoError>

Remove a worktree by name. Deletes the worktree directory and cleans up the main repo’s config entries.

pub fn rename_file( &self, old_path: &str, new_path: &str, ) -> Result<(), RepoError>

Rename a tracked file. Stages both the deletion of the old path and the addition of the new path.

pub fn get_remote_url(&self, name: &str) -> Result<String, RepoError>

Get the URL for a remote.

pub fn all_patches(&self) -> Vec<Patch>

Get all patches in the DAG as a Vec.

pub fn gc(&self) -> Result<GcResult, RepoError>

Remove unreachable patches from the repository.

Patches not reachable from any branch tip are deleted from the metadata store (patches, edges, signatures tables). The in-memory DAG is not updated; reopen the repository after GC to get a clean DAG.

pub fn fsck(&self) -> Result<FsckResult, RepoError>

Verify repository integrity.

Checks DAG consistency (parent references), branch integrity (branch targets exist), blob references (CAS has blobs referenced by patches), and HEAD consistency.

pub fn reflog_entries(&self) -> Result<Vec<(String, String)>, RepoError>

Get reflog entries as (head_hash, entry_string) pairs.