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 untracked files between worktrees using git status
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", BranchType::Normal, None)?;
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.

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

ConfigError

Configuration-related errors

CopyError

File copy errors

DefaultBranchError

Default branch detection errors

PrError

Pull request-related errors

RepoError

Repository-specific errors

WorkonError

Main error type for the workon library

WorktreeError

Worktree-specific errors

Functions

add_worktree

Create a new worktree for the given branch.

check_gh_available

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

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.

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.

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_worktree

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

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 git2::RemoteCallbacks that handle credential prompts via the system credential store (SSH keys, keychain, etc.).

get_repo

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

get_worktrees

Return all worktrees registered with the repository.

init

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

is_pr_reference

Check if a string looks like a PR reference

move_worktree

Move (rename) a worktree and its branch atomically.

parse_pr_reference

Parse a PR reference from user input

prepare_pr_worktree

Prepare everything needed to create a worktree for PR pr_number.

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