Crate workon 

Core library for git-workon, an opinionated git worktree workflow tool.

This crate (published as workon) provides the building blocks for cloning, initialising, and managing git repositories in a bare-repo-plus-worktrees layout.

Key types

• WorktreeDescriptor — wraps a git2 Worktree with rich metadata methods
• BranchType — controls how a branch is created for a new worktree
• WorkonConfig — reads workon.* settings from git config
• PullRequest / PrMetadata — PR reference parsing and gh CLI integration
• MoveOptions — options for move_worktree
• WorkonError and its sub-types — all error variants with miette diagnostics

Key functions

Function	Description
clone	Clone a remote repository into the worktrees layout
init	Initialise a new bare repository with an initial commit
get_repo	Discover and open a bare repository from a path
get_worktrees	List all worktrees in a repository
add_worktree	Create a new worktree (normal, orphan, or detached)
find_worktree	Locate a worktree by name or branch
current_worktree	Return the worktree containing the current directory
move_worktree	Atomically rename a worktree and its branch
copy_untracked	Copy local (git-unmanaged) files between worktrees
workon_root	Resolve the directory that holds all worktrees

Example

use workon::{get_repo, get_worktrees, add_worktree, BranchType};

let repo = get_repo(None)?;

for wt in get_worktrees(&repo)? {
    println!("{}: {}", wt.name().unwrap_or("?"), wt.path().display());
}

let wt = add_worktree(&repo, "my-feature", None, BranchType::Normal, None, false)?;
println!("Created: {}", wt.path().display());

Structs

CloneOptions

Options for clone.

CopyOptions

Options for copy_untracked.

DefaultBranch

Builder for resolving the default branch name of a repository or remote.

MoveOptions

Options for moving a worktree

PrMetadata

PR metadata fetched from the gh CLI.

PullRequest

A parsed pull request reference from user input.

RemoteAuth

Holds the credential authenticator and git config needed to build git2::RemoteCallbacks.

Stack

A stack of branches rooted at a trunk branch.

StackGroup

One group of worktrees that share a connected stack, identified by trunk + diff set.

StackGrouping

Result of partitioning a worktree slice by stacks via group_by_stack.

WorkonConfig

Configuration reader for workon settings stored in git config.

WorktreeDescriptor

A handle to a git worktree with rich metadata access.

Enums

BranchType

Type of branch to create for a new worktree

CheckoutError

In-place checkout errors

CheckoutOutcome

The outcome of a successful checkout_branch_in_worktree call.

ConfigError

Configuration-related errors

CopyError

File copy errors

DefaultBranchError

Default branch detection errors

Granularity

How worktrees map to stacks.

PrError

Pull request-related errors

RemoteResolution

Result of looking up which remote carries a branch.

RepoError

Repository-specific errors

Resolution

The resolved action for workon <T>.

StackError

Stacked diff workflow errors

StackModel

Which stacked-diff tool is managing stacks in this repository.

StashRestore

Outcome of apply_labeled_stash.

WorkonError

Main error type for the workon library

WorktreeError

Worktree-specific errors

Functions

add_worktree

Create a new worktree for the given branch.

apply_labeled_stash

Apply the stash labeled for (branch, worktree), dropping it on a clean apply.

branch_exists

Returns true if name matches a local branch or the short name of any remote tracking branch (the part after the first /).

check_gh_available

Return Ok(()) if the gh CLI is installed and reachable in PATH.

checkout_branch_in_worktree

Move HEAD in the worktree opened as wt_repo to branch.

clone

Clone a remote repository into the worktrees layout.

convert_to_bare

Convert a standard git repository into the worktrees layout.

copy_untracked

Copy only untracked (and optionally ignored) files from source to destination.

create_branch_from_remote

Create local branch branch from remote’s tracking ref and set its upstream.

create_labeled_stash

Create a labeled stash in wt_repo (a worktree-specific &mut Repository).

current_stack

Return the stack for the worktree whose HEAD is head_branch, or None if the branch is not part of a tracked stack under model.

current_worktree

Return the worktree that contains the current working directory.

detect_pr_remote

Select which remote to use for fetching PR refs.

empty_commit

Create an empty initial commit on HEAD with no parents.

enumerate_stacks

Return all stacks present in metadata, one per connected component.

fetch_branch

Fetch branch from remote_name, making it available as refs/remotes/{remote_name}/{branch}.

fetch_pr_metadata

Fetch PR metadata for pr_number using the gh CLI.

find_labeled_stash

Find the stash-list index for the (branch, worktree) entry.

find_worktree

Find a worktree by its name or by its branch name.

find_worktree_by_branch

Find the worktree whose checked-out branch is branch.

format_pr_name

Format a PR worktree name using the format string

format_pr_name_with_metadata

Expand all placeholders in format using metadata.

get_default_branch

Get the default branch name for a repository, validated to exist.

get_default_branch_name

Convenience wrapper around DefaultBranch.

get_remote_callbacks

Build a RemoteAuth using the given repo’s config to drive credential resolution. Mirrors git fetch/git push precedence: local .git/config > worktree config > global > XDG > system.

get_remote_callbacks_default

Build a RemoteAuth for operations that run before a repo exists (e.g. clone). Mirrors git clone precedence (global + XDG + system), tolerating a missing ~/.gitconfig.

get_repo

Discover and open a bare repository from path (or the current directory).

get_worktrees

Return all worktrees registered with the repository.

graphite_trunk

Return the first trunk branch name from .graphite_repo_config, or None if the file is missing, unparseable, or contains no trunk entries.

group_by_stack

Partition a slice of optional stack descriptors into groups sharing the same connected stack.

init

Initialise a new bare repository at path in the worktrees layout.

is_graphite_active

Returns true if gt is on PATH and this repository has been Graphite-initialized.

is_pr_reference

Check if a string looks like a PR reference

list_labeled_for_worktree

List all labeled stash entries belonging to worktree.

move_worktree

Move (rename) a worktree and its branch atomically.

parse_pr_reference

Parse a PR reference from user input

preferred_remote_order

Returns remotes in preferred order: upstream first, then origin, then all others in configuration order (the sort is stable).

prepare_pr_worktree

Prepare everything needed to create a worktree for PR pr_number.

prune_fetch

Prune-fetch from a single remote: remove stale remote-tracking refs, then fetch.

remote_priority

Priority tier for the shared upstream → origin → others remote precedence.

remotes_tracked_by_worktrees

Returns the deduplicated list of remote names tracked by the given worktrees.

resolve_action

Resolve the action for workon <name> under the given stack model.

resolve_remote_tracking

Find which remote(s) carry a branch, ranked by the shared remote_priority precedence (upstream → origin → others).

set_upstream_tracking

Set upstream tracking for a worktree branch

setup_fork_remote

Ensure a remote for a fork PR exists, then return its name.

validate_move

Validate that a move from source to target_name is safe to perform.

workon_root

Resolve the directory that contains all worktrees for the repository.

Type Aliases

Result

Result type alias using WorkonError