Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Branch-related operations for Repository.
//!
//! For single-branch operations, see [`super::Branch`].
//! This module contains multi-branch operations (listing, filtering, etc.).
//!
//! # Branch inventory
//!
//! Every multi-branch operation in this file reads from one of two
//! inventories — [`Repository::local_branches`] and
//! [`Repository::remote_branches`]. Each is populated by a single
//! `git for-each-ref` scan that's cached on `RepoCache` for the lifetime of
//! this `Repository` instance (shared across clones via `Arc`):
//!
//! - `refs/heads/` scan fetches name, SHA, committer timestamp, and upstream
//! tracking info — enough to satisfy every local-branch accessor (name
//! listing, SHA priming, upstream resolution, completion ordering). The
//! inventory also carries a name → index map so single-branch lookups
//! (e.g. [`super::Branch::upstream`]) are O(1) without a separate scan.
//! - `refs/remotes/` scan fetches the same fields for remote-tracking refs.
//!
//! Repeated accessors within a single command share the cached data. This
//! consolidation replaces what used to be five overlapping `for-each-ref`
//! calls (one per accessor) with at most two.
//!
//! Both scans are idempotent: their results depend only on the repository's
//! ref state at the moment of the first call. Branches created mid-command
//! by wt itself (e.g., after `git worktree add -b ...`) will not appear —
//! but no caller needs to observe its own mutations through these accessors.
use std::collections::{HashMap, HashSet};
use super::{BranchCategory, CompletionBranch, LocalBranch, RemoteBranch, Repository};
/// Local-branch inventory: an ordered `Vec<LocalBranch>` plus a `HashMap`
/// for O(1) single-branch lookups.
///
/// Built from [`Repository::scan_local_branch_records`] and stored on
/// `RepoCache` (first scan wins). Iteration order is the scan's own sort —
/// committer timestamp, most recent first.
#[derive(Debug, Default)]
pub(in crate::git) struct LocalBranchInventory {
entries: Vec<LocalBranch>,
by_name: HashMap<String, usize>,
}
impl LocalBranchInventory {
pub(super) fn new(entries: Vec<LocalBranch>) -> Self {
let by_name = entries
.iter()
.enumerate()
.map(|(i, b)| (b.name.clone(), i))
.collect();
Self { entries, by_name }
}
pub(super) fn entries(&self) -> &[LocalBranch] {
&self.entries
}
fn get(&self, name: &str) -> Option<&LocalBranch> {
self.by_name.get(name).map(|&i| &self.entries[i])
}
}
/// Field separator emitted by our `for-each-ref` format strings.
///
/// Use `%00` (git's format escape for a NUL byte) rather than a literal NUL
/// in the Rust string: Rust's `Command::arg` rejects arguments containing
/// interior NUL bytes (they can't survive the `CString` conversion to
/// `execve`), so passing `\0` through `args()` would error before git runs.
const FIELD_SEP: char = '\0';
/// Format string for the local-branch scan.
///
/// Fields, in order: short name, object SHA, committer Unix timestamp,
/// upstream short name (empty if none), upstream track (`[gone]` if the
/// configured upstream no longer exists on the remote), push remote (a remote
/// name or URL; empty if none), upstream remote (empty if none).
const LOCAL_BRANCH_FORMAT: &str = "--format=%(refname:lstrip=2)%00%(objectname)%00%(committerdate:unix)%00%(upstream:short)%00%(upstream:track)%00%(push:remotename)%00%(upstream:remotename)";
/// Format string for the remote-branch scan.
///
/// Fields, in order: remote-qualified short name (e.g. `origin/feature`),
/// object SHA, committer Unix timestamp.
const REMOTE_BRANCH_FORMAT: &str =
"--format=%(refname:lstrip=2)%00%(objectname)%00%(committerdate:unix)";
impl Repository {
/// Check if a git reference exists (branch, tag, commit SHA, HEAD, etc.).
///
/// Accepts any valid commit-ish: branch names, tags, HEAD, commit SHAs,
/// and relative refs like HEAD~2.
pub fn ref_exists(&self, reference: &str) -> anyhow::Result<bool> {
// Quiet verification uses status 1 for a missing commit-ish. Other
// failures, including native interruption, are not evidence of absence.
self.run_command_check(&[
"rev-parse",
"--verify",
"--quiet",
"--end-of-options",
&format!("{reference}^{{commit}}"),
])
}
/// Access the local-branch inventory, scanning on first call.
///
/// Returns every local branch (under `refs/heads/`) sorted by committer
/// timestamp, most recent first. Result is cached for the lifetime of
/// this `Repository` instance (shared across clones via `Arc`).
///
/// `commit_sha` on each entry is a snapshot at scan time. Code that
/// needs a current SHA for a ref must resolve through
/// [`Repository::capture_refs`] at the moment of read, not through this
/// inventory or a snapshot built from it. The
/// inventory itself is used for branch listing and upstream-tracking
/// metadata, stable for the duration of a command that runs no hook.
/// A hook runs inside the command, so one that touches refs leaves the
/// rest of the inventory stale too — which branches are in it, and where
/// each one's upstream points.
pub fn local_branches(&self) -> anyhow::Result<&[LocalBranch]> {
Ok(self.local_branch_inventory()?.entries())
}
/// O(1) lookup of a single local branch by name.
///
/// Returns `None` if no branch with that exact name exists. First call
/// triggers the `refs/heads/` scan the same way
/// [`local_branches`](Self::local_branches) would.
pub(super) fn local_branch(&self, name: &str) -> anyhow::Result<Option<&LocalBranch>> {
Ok(self.local_branch_inventory()?.get(name))
}
/// Commit SHA the default branch points at, sourced from the local-branch
/// inventory.
///
/// Returns `None` when the default branch can't be determined (see
/// [`default_branch`](Self::default_branch)) or when the configured
/// default branch isn't a local branch (e.g. stale
/// `worktrunk.default-branch` config pointing at a deleted branch). On
/// first call, populates the inventory cache via the same single
/// `for-each-ref refs/heads/` scan that [`local_branches`] would —
/// no extra subprocess.
///
/// **Snapshot at first scan; do not use in ref-mutating commands.**
/// Same staleness contract as [`local_branches`]: the SHA is captured
/// when the inventory is first scanned and never refreshed. Code that
/// runs after wt itself has updated `refs/heads/<default>` (e.g.
/// `wt merge`'s `git update-ref`) must capture a fresh
/// [`crate::git::RefSnapshot`] instead — this accessor will keep
/// returning the pre-update SHA. Safe in read-only contexts (the
/// interactive picker, list rendering) where wt itself doesn't move
/// refs.
///
/// Intended for cache keying: when many parallel tasks all need to
/// answer "what SHA is the default branch at *right now, for this
/// command's worth of work*", this lets them share one inventory scan
/// instead of each forking `git rev-parse <name>` independently.
///
/// [`local_branches`]: Self::local_branches
pub fn default_branch_sha(&self) -> Option<String> {
let name = self.default_branch()?;
self.local_branch(&name)
.ok()
.flatten()
.map(|b| b.commit_sha.clone())
}
/// Access the local-branch inventory (entries + name index).
fn local_branch_inventory(&self) -> anyhow::Result<&LocalBranchInventory> {
self.cache
.local_branches
.get_or_try_init(|| Ok(LocalBranchInventory::new(self.scan_local_branch_records()?)))
}
/// Access the remote-tracking branch inventory, scanning on first call.
///
/// Returns every remote-tracking branch (under `refs/remotes/`) sorted
/// by committer timestamp, most recent first. `<remote>/HEAD` symrefs
/// are excluded. Result is cached for the lifetime of this `Repository`
/// instance.
pub fn remote_branches(&self) -> anyhow::Result<&[RemoteBranch]> {
self.cache
.remote_branches
.get_or_try_init(|| self.scan_remote_branch_records())
.map(Vec::as_slice)
}
/// One `for-each-ref refs/heads/` scan, parsed and sorted by committer
/// timestamp (most recent first). The shared scan primitive behind both
/// the cache accessor ([`local_branches`](Self::local_branches), via
/// [`local_branch_inventory`](Self::local_branch_inventory)) and the
/// snapshot path ([`crate::git::RefSnapshot`] capture). No cache
/// side-effect — each caller decides how to store the result
/// (first-scan-wins cell vs. fresh snapshot).
///
/// `commit_sha` is a snapshot at scan time — callers that need a
/// current SHA must resolve through [`Repository::capture_refs`] at the
/// moment of the read, not through this list.
pub(super) fn scan_local_branch_records(&self) -> anyhow::Result<Vec<LocalBranch>> {
let output = self.run_command(&["for-each-ref", LOCAL_BRANCH_FORMAT, "refs/heads/"])?;
let mut branches: Vec<LocalBranch> =
output.lines().filter_map(parse_local_branch_line).collect();
branches.sort_by_key(|b| std::cmp::Reverse(b.committer_ts));
Ok(branches)
}
/// One `for-each-ref refs/remotes/` scan, parsed (excluding
/// `<remote>/HEAD` symrefs) and sorted by committer timestamp. The
/// shared scan primitive behind both [`remote_branches`](Self::remote_branches)
/// and the snapshot path. Does not populate the remote-branch cache.
pub(super) fn scan_remote_branch_records(&self) -> anyhow::Result<Vec<RemoteBranch>> {
let output = self.run_command(&["for-each-ref", REMOTE_BRANCH_FORMAT, "refs/remotes/"])?;
let remotes = self.all_remote_urls();
let mut branches: Vec<RemoteBranch> = output
.lines()
.filter_map(|line| parse_remote_branch_line(line, &remotes))
.collect();
branches.sort_by_key(|b| std::cmp::Reverse(b.committer_ts));
Ok(branches)
}
/// List all local branch names, sorted by most recent commit first.
pub fn all_branches(&self) -> anyhow::Result<Vec<String>> {
Ok(self
.local_branches()?
.iter()
.map(|b| b.name.clone())
.collect())
}
/// Get branches with metadata for shell completions.
///
/// Returns branches in completion order: worktrees first, then local branches,
/// then remote-only branches. Each category is sorted by recency.
///
/// Searches all remotes (matching git's checkout behavior). If the same branch
/// exists on multiple remotes, all remote names are included in the result so
/// completions can show that the branch is ambiguous.
///
/// For remote branches, returns the local name (e.g., "fix" not "origin/fix")
/// since `git worktree add path fix` auto-creates a tracking branch.
///
/// `include_remote_only` is the caller's answer to "could a remote-only
/// branch reach the user from here?". A completer that can never offer one
/// (`wt remove`, worktree-only arguments) passes `false` and the
/// `refs/remotes/` scan — the most expensive of the three, since it reads a
/// commit object per ref and a fetched-into clone has far more of those
/// than local branches — never runs. Filtering the results afterwards
/// instead would pay for the scan and then throw it away.
pub fn branches_for_completion(
&self,
include_remote_only: bool,
) -> anyhow::Result<Vec<CompletionBranch>> {
// The three scans are independent git calls that this function only
// joins in memory, and completion is a process that does nothing else
// — run in sequence the user waits for their sum, run concurrently for
// their max. Best-effort, on the same contract as
// `Repository::prewarm`: a thread that fails leaves its cache slot
// empty, and the accessor below re-runs the call and surfaces the
// error. `RepoCache`'s slots are separate thread-safe `OnceCell`s, so
// the three fill independently.
std::thread::scope(|scope| {
scope.spawn(|| {
let _ = self.list_worktrees();
});
scope.spawn(|| {
let _ = self.local_branches();
});
if include_remote_only {
scope.spawn(|| {
let _ = self.remote_branches();
});
}
});
let worktrees = self.list_worktrees()?;
let worktree_branches: HashSet<String> = worktrees
.iter()
.filter_map(|wt| wt.branch.clone())
.collect();
let locals = self.local_branches()?;
let local_names: HashSet<&str> = locals.iter().map(|b| b.name.as_str()).collect();
// Group remote branches by local name, collecting all remotes that
// have each branch. Skip remotes that have a same-named local branch
// (users should use the local one). Keeps the most recent timestamp
// across remotes to preserve recency ordering.
let mut branch_remotes: HashMap<String, (Vec<String>, i64)> = HashMap::new();
let remotes: &[RemoteBranch] = if include_remote_only {
self.remote_branches()?
} else {
&[]
};
for remote in remotes {
if local_names.contains(remote.local_name.as_str()) {
continue;
}
branch_remotes
.entry(remote.local_name.clone())
.and_modify(|(remotes, ts)| {
remotes.push(remote.remote_name.clone());
*ts = (*ts).max(remote.committer_ts);
})
.or_insert_with(|| (vec![remote.remote_name.clone()], remote.committer_ts));
}
let mut remote_only: Vec<(String, Vec<String>, i64)> = branch_remotes
.into_iter()
.map(|(name, (mut remotes, ts))| {
remotes.sort(); // Deterministic remote ordering within each branch
(name, remotes, ts)
})
.collect();
// Recency first, then name. The name is not a cosmetic tiebreak: these
// entries come out of a `HashMap`, whose iteration order varies per
// process, and `sort_by_key` is stable — so on the timestamps that tie
// (branches cut from one commit, a bulk import) sorting on recency
// alone leaves the surviving order randomized, and the completion list
// reshuffles between one Tab press and the next.
remote_only.sort_by(|a, b| b.2.cmp(&a.2).then_with(|| a.0.cmp(&b.0)));
let mut result = Vec::with_capacity(locals.len() + remote_only.len() + worktrees.len());
// Unborn worktree branches first: a worktree whose branch isn't in
// `refs/heads/` yet (a fresh `git init`'d repo whose default branch
// exists only as a `symbolic-ref` target, or a `wt switch --create`
// off such a repo). Pinned to `i64::MAX` so they sort to the top of
// the Worktree category — there's no commit to pull a real timestamp
// from, and the user typically just created them.
for wt in worktrees {
if let Some(branch) = &wt.branch
&& !local_names.contains(branch.as_str())
{
result.push(CompletionBranch {
name: branch.clone(),
timestamp: i64::MAX,
category: BranchCategory::Worktree,
});
}
}
// Worktree branches (already sorted by recency via locals order).
for branch in locals {
if worktree_branches.contains(&branch.name) {
result.push(CompletionBranch {
name: branch.name.clone(),
timestamp: branch.committer_ts,
category: BranchCategory::Worktree,
});
}
}
// Local branches without worktrees.
for branch in locals {
if !worktree_branches.contains(&branch.name) {
result.push(CompletionBranch {
name: branch.name.clone(),
timestamp: branch.committer_ts,
category: BranchCategory::Local,
});
}
}
// Remote-only branches.
for (name, remotes, timestamp) in remote_only {
result.push(CompletionBranch {
name,
timestamp,
category: BranchCategory::Remote(remotes),
});
}
Ok(result)
}
}
/// Parse one record from the local-branch scan.
///
/// Returns `None` for malformed lines — e.g. a future git format change or
/// a control character snuck through. Callers skip those entries rather
/// than fail the whole scan.
fn parse_local_branch_line(line: &str) -> Option<LocalBranch> {
let mut parts = line.split(FIELD_SEP);
let name = parts.next()?.to_string();
let commit_sha = parts.next()?.to_string();
let committer_ts: i64 = parts.next()?.parse().ok()?;
let upstream_short_raw = parts.next()?;
let upstream_track = parts.next()?;
let upstream_short = if upstream_short_raw.is_empty() || upstream_track == "[gone]" {
None
} else {
Some(upstream_short_raw.to_string())
};
let push_remote = Some(parts.next()?)
.filter(|s| !s.is_empty())
.map(str::to_string);
let upstream_remote = Some(parts.next()?)
.filter(|s| !s.is_empty() && *s != ".")
.map(str::to_string);
Some(LocalBranch {
name,
commit_sha,
committer_ts,
upstream_short,
upstream_remote,
push_remote,
})
}
/// Parse one record from the remote-branch scan.
///
/// Skips `<remote>/HEAD` symrefs, which duplicate another ref and would
/// confuse callers that key by local name.
fn parse_remote_branch_line(line: &str, remotes: &[(String, String)]) -> Option<RemoteBranch> {
let mut parts = line.split(FIELD_SEP);
let short_name = parts.next()?;
let commit_sha = parts.next()?.to_string();
let committer_ts: i64 = parts.next()?.parse().ok()?;
let (remote_name, local_name) = super::remotes::split_remote_branch_name(short_name, remotes)?;
if local_name == "HEAD" {
return None;
}
Some(RemoteBranch {
short_name: short_name.to_string(),
commit_sha,
committer_ts,
remote_name: remote_name.to_string(),
local_name: local_name.to_string(),
})
}
#[cfg(test)]
mod tests {
use super::*;
use crate::testing::TestRepo;
#[test]
fn default_branch_sha_returns_inventory_sha() {
// The accessor must return the same SHA `git rev-parse <default>`
// would, sourced from the local-branch inventory rather than its
// own subprocess.
let test = TestRepo::with_initial_commit();
let repo = Repository::at(test.root_path()).unwrap();
let expected = test.git_output(&["rev-parse", "main"]);
assert_eq!(repo.default_branch_sha(), Some(expected));
}
#[test]
fn default_branch_sha_none_when_branch_missing_from_inventory() {
// Stale `worktrunk.default-branch` config points at a branch that
// doesn't exist locally — `default_branch()` returns the configured
// name, but `local_branch(name)` finds nothing, so the accessor
// returns None. Callers (e.g. the picker's BranchDiff preview)
// treat None as "fall through to the uncached path."
let test = TestRepo::with_initial_commit();
test.run_git(&["config", "worktrunk.default-branch", "ghost"]);
let repo = Repository::at(test.root_path()).unwrap();
assert_eq!(repo.default_branch().as_deref(), Some("ghost"));
assert_eq!(repo.default_branch_sha(), None);
}
/// Build `refs/remotes/origin/<name>` for each name, all at HEAD — so
/// every one carries the same committer timestamp and the recency sort
/// between them is a tie.
fn add_remote_refs_at_head(test: &TestRepo, names: &[&str]) {
let head = test.git_output(&["rev-parse", "HEAD"]);
for name in names {
test.run_git(&["update-ref", &format!("refs/remotes/origin/{name}"), &head]);
}
}
#[test]
fn branches_for_completion_omits_remote_only_when_not_requested() {
// `include_remote_only` is what keeps a completer that can never
// offer a remote-only branch (`wt remove`, worktree-only arguments)
// from running the `refs/remotes/` scan at all. Filtering afterwards
// would look the same from here but pay for the scan first, which on
// a long-lived clone is the most expensive call on the path.
let test = TestRepo::with_initial_commit();
add_remote_refs_at_head(&test, &["only-on-remote"]);
let repo = Repository::at(test.root_path()).unwrap();
let with = repo.branches_for_completion(true).unwrap();
assert!(
with.iter()
.any(|b| b.name == "only-on-remote"
&& matches!(b.category, BranchCategory::Remote(_))),
"requested but absent: {with:?}",
);
// A separate Repository, so the first call's cached scan can't stand
// in for the second's.
let repo = Repository::at(test.root_path()).unwrap();
let without = repo.branches_for_completion(false).unwrap();
assert!(
!without
.iter()
.any(|b| matches!(b.category, BranchCategory::Remote(_))),
"not requested but present: {without:?}",
);
}
#[test]
fn branches_for_completion_orders_tied_remote_only_branches_by_name() {
// Remote-only entries are collected through a `HashMap`, whose
// iteration order differs per process, and the recency sort is
// stable — so branches sharing a timestamp keep whatever random order
// they were iterated in unless the sort breaks the tie itself. Left
// unbroken, a user's completion list reshuffles between Tab presses.
let test = TestRepo::with_initial_commit();
add_remote_refs_at_head(&test, &["cherry", "apple", "banana"]);
let repo = Repository::at(test.root_path()).unwrap();
let remote_only: Vec<String> = repo
.branches_for_completion(true)
.unwrap()
.into_iter()
.filter(|b| matches!(b.category, BranchCategory::Remote(_)))
.map(|b| b.name)
.collect();
assert_eq!(remote_only, vec!["apple", "banana", "cherry"]);
}
#[test]
fn branches_for_completion_includes_unborn_default_branch() {
// Regression for #3094: on a fresh `git init -b main` with no
// commits, `refs/heads/` is empty (main exists only as a
// `symbolic-ref` target), so the local-branch scan returns nothing.
// The worktree fallback keeps tab-completion responsive by emitting
// a Worktree-category candidate for each worktree whose branch
// isn't yet a ref.
let test = TestRepo::new();
let repo = Repository::at(test.root_path()).unwrap();
let branches = repo.branches_for_completion(true).unwrap();
let names: Vec<&str> = branches.iter().map(|b| b.name.as_str()).collect();
assert_eq!(names, vec!["main"], "completion candidates: {:?}", branches);
assert!(
matches!(branches[0].category, BranchCategory::Worktree),
"category: {:?}",
branches[0].category,
);
}
#[test]
fn branches_for_completion_includes_unborn_linked_worktree() {
// After `git worktree add -b feature ../path` on a still-unborn
// repo, both `main` and `feature` exist only in `worktree list
// --porcelain`, not under `refs/heads/`. Both must surface in
// completion.
let test = TestRepo::new();
let feature_path = test.root_path().parent().unwrap().join("feature");
test.run_git(&[
"worktree",
"add",
"-b",
"feature",
feature_path.to_str().unwrap(),
]);
let repo = Repository::at(test.root_path()).unwrap();
let branches = repo.branches_for_completion(true).unwrap();
let names: Vec<&str> = branches.iter().map(|b| b.name.as_str()).collect();
assert!(
names.contains(&"main") && names.contains(&"feature"),
"completion candidates: {:?}",
branches,
);
for b in &branches {
assert!(
matches!(b.category, BranchCategory::Worktree),
"non-worktree category for {:?}",
b,
);
}
}
#[test]
fn default_branch_sha_is_snapshot_at_first_scan() {
// Documenting the staleness contract: the inventory is scanned once
// per `Repository` instance, so a SHA captured before a ref-mutating
// operation stays put. Callers in mutating commands must capture a
// fresh `RefSnapshot` instead of trusting this accessor across the
// mutation.
let test = TestRepo::with_initial_commit();
let repo = Repository::at(test.root_path()).unwrap();
let before = repo.default_branch_sha().expect("main resolves");
let cloned_repo = repo.clone();
assert!(std::sync::Arc::ptr_eq(&repo.cache, &cloned_repo.cache));
// Move main forward outside `repo`'s knowledge.
std::fs::write(test.root_path().join("after.txt"), "after\n").unwrap();
test.run_git(&["add", "after.txt"]);
test.run_git(&["commit", "-m", "advance main"]);
let real_after = test.git_output(&["rev-parse", "main"]);
assert_ne!(before, real_after, "test setup: main should have moved");
// A clone shares the cached inventory and still serves the pre-move SHA.
assert_eq!(cloned_repo.default_branch_sha(), Some(before));
// A fresh `Repository::at` scans again and sees the new SHA.
let repo2 = Repository::at(test.root_path()).unwrap();
assert_eq!(repo2.default_branch_sha(), Some(real_after));
}
}