fabricatio_workspace.rust

Functions

commit(→ str)

Commits changes in a specific worktree with optional file selection.

fork(→ pathlib.Path)

Forks a new Git worktree with safety checks and automatic cleanup.

prune(→ int)

Prunes all stale worktrees from the repository and ensures branch availability.

Package Contents

fabricatio_workspace.rust.commit(worktree_path: str | os.PathLike | pathlib.Path, msg: str, files: Sequence[str] | None = None) → str

Commits changes in a specific worktree with optional file selection.

This function stages specified files (or all modified files if none are specified) and creates a new commit in the repository associated with the given worktree. It automatically configures the committer and author based on the Git configuration found in the worktree’s repository.

Parameters:

  • worktree_path (PathBuf) – The absolute or relative path to the root of the worktree where the commit should be made.

  • msg (str) – The commit message describing the changes.

  • files (Optional[List[str]]) – A list of file paths relative to the worktree root to stage for the commit. If None or an empty list, all currently modified and tracked files in the worktree will be staged automatically.

Returns:

The hexadecimal string representation of the new commit’s OID (Object ID).

Return type:

str

Raises:

  • RuntimeError – If the worktree path is invalid or not part of a valid Git repository.

  • RuntimeError – If there are no changes to commit (empty index).

  • RuntimeError – If staging the specified files fails (e.g., file not found).

  • RuntimeError – If the commit operation fails due to Git constraints (e.g., merge conflicts).

Note

  • The function uses the current HEAD of the worktree as the parent commit.

  • Author and Committer identities are derived from the Git config (user.name and user.email).

  • If files is provided, only those files are added to the index; other staged changes remain untouched unless explicitly overwritten by this operation’s logic (here we add to index).

fabricatio_workspace.rust.fork(repo_path: str | os.PathLike | pathlib.Path, to: str | os.PathLike | pathlib.Path, branch_name: str, base_branch: str | None = None, exist_ok: bool = False) → pathlib.Path

Forks a new Git worktree with safety checks and automatic cleanup.

This function creates a new worktree linked to a specific branch. It handles branch creation, conflict detection across existing worktrees, and ensures atomicity by cleaning up partial directories if the worktree addition fails.

Parameters:

  • repo_path (PathBuf) – The absolute or relative path to the main Git repository.

  • to (PathBuf) – The destination path where the new worktree will be created.

  • branch_name (str) – The name of the branch to associate with the new worktree.

  • base_branch (Optional[str]) – The name of the existing branch to use as the starting point for creating branch_name if it does not already exist. If None, the current HEAD of the main repository is used as the base.

  • exist_ok (bool) – If True, the function will return the path of an existing worktree if one is already checked out to branch_name, instead of raising an error. If False, a conflict raises a RuntimeError.

Returns:

The absolute path to the newly created (or existing) worktree directory.

Return type:

PathBuf

Raises:

  • RuntimeError – If branch_name is already checked out in another worktree and exist_ok is False.

  • RuntimeError – If branch_name already exists as a local branch but is not checked out in any worktree (preventing accidental overwriting or ambiguous state).

  • RuntimeError – If the destination path to already exists on the filesystem.

  • RuntimeError – If the underlying Git operation to add the worktree fails.

Note

  • If the branch branch_name does not exist, it will be created automatically.

  • If base_branch is provided but invalid, the function falls back to using the current HEAD.

  • Partial directories created at to during a failed operation are automatically removed.

fabricatio_workspace.rust.prune(repo_path: str | os.PathLike | pathlib.Path) → int

Prunes all stale worktrees from the repository and ensures branch availability.

This function scans the repository for worktrees that are no longer valid (e.g., the working directory has been manually deleted or corrupted) and removes their metadata. It effectively cleans up the repository state, ensuring that branches previously locked by these stale worktrees are released and can be used again.

This is analogous to running git worktree prune but with additional safety checks to ensure internal consistency within the application’s context.

Parameters:

repo_path (PathBuf) – The absolute or relative path to the main Git repository where stale worktrees should be pruned.

Returns:

The number of stale worktrees successfully pruned.

Return type:

int

Raises:

RuntimeError – If the repository cannot be opened or if there is an error accessing the worktree metadata directory.

Note

  • This operation only removes the metadata links in .git/worktrees.

  • It does not delete the actual working directory files if they still exist on disk; it only cleans up the repository’s reference to them.

  • After pruning, branches associated with these worktrees are considered free and can be checked out in new worktrees.