Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

107 KB
Raw Blame
//! Repository - git repository operations.
//!
//! This module provides the [`Repository`] type for interacting with git repositories,
//! [`WorkingTree`] for worktree-specific operations, and [`Branch`] for branch-specific
//! operations.
//!
//! # Module organization
//!
//! - `mod.rs` - Core types and construction
//! - `working_tree.rs` - WorkingTree struct and worktree-specific operations
//! - `branch.rs` - Branch struct and single-branch operations (exists, upstream, remotes)
//! - `branches.rs` - Multi-branch operations (listing, filtering, completions)
//! - `worktrees.rs` - Worktree management (list, resolve, remove)
//! - `remotes.rs` - Remote and URL operations
//! - `diff.rs` - Diff, history, and commit operations
//! - `config.rs` - Git config, hints, markers, and default branch detection
//! - `integration.rs` - Integration detection (same commit, ancestor, trees match)
//!
//! # Caching
//!
//! Most repository data — remote URLs, config, default branch, merge-bases — is stable
//! for the duration of a single CLI command. [`RepoCache`] exploits this by caching
//! read-only values so repeated queries hit memory instead of spawning git processes.
//!
//! **Two layers, two scopes.** Cached state lives in either of:
//! - `RepoCache` — per-`Repository::at()` instance. Most repo-wide values
//!   (config, branches, worktree inventory) live here.
//! - Process-wide statics that survive across `RepoCache` instances:
//!   - `WORKTREE_ROOTS`, `GIT_DIRS`, `CURRENT_BRANCHES` (`LazyLock<DashMap>`),
//!     keyed by canonicalized worktree path, so two `Repository` instances
//!     pointed at the same path see the same answer.
//!   - `GIT_COMMON_DIR_CACHE` and `GIT_CONFIG_PRELOAD` (`LazyLock<DashMap>`),
//!     keyed by the *raw* discovery path passed to [`Repository::at`] /
//!     [`Repository::prewarm`] — not canonicalized, since both the prewarm
//!     producer and the `at()` consumer go through `base_path()` and share the
//!     same `PathBuf`.
//!   - `WORKTRUNK_USER_CONFIG_PRELOAD` (`OnceLock<UserConfig>`), process-scoped
//!     rather than path-keyed (the config-path rule is process-invariant).
//!
//!   This lets [`Repository::prewarm`] populate the maps once at the start
//!   of `main` and have every later `Repository::current()` (each builds a
//!   fresh `RepoCache`) reuse the result.
//!
//! **Persistence: in-memory vs on-disk.** Both layers above are in-memory and
//! die with the process. A third store — the persistent on-disk [`sha_cache`]
//! (SHA-keyed JSON under `.git/wt/cache/`) — survives across invocations.
//! Which store a git result belongs in turns on recompute cost and parallelism:
//! - *Cheap per call, but primeable in bulk* (commit→tree) → in-memory
//!   `RepoCache` `DashMap`, get-or-create. The `Entry` match holds the shard
//!   lock across check-and-insert, so parallel `wt list` rows sharing a key
//!   spawn one git process, not one each. On the `wt list` path the per-row
//!   lookups never fork at all: the pre-skeleton commit-details `git log`
//!   batch reads `%T` and primes this map in one round trip
//!   ([`Repository::commit_details_many`]), so cross-run disk persistence
//!   would save only the rare off-batch miss. Exemplar:
//!   [`Repository::commit_to_tree_sha`].
//! - *Expensive, worth persisting across invocations* (merge-tree, patch-id,
//!   diff stats, ahead/behind) → the disk [`sha_cache`]; content-addressed by
//!   SHA. An entry is stable while its producer's semantics are unchanged;
//!   changing the producer can leave old answers in place across upgrades.
//!   Assess that effect when changing a cache kind and describe it in the PR.
//! - *Both expensive and hot-in-parallel* → an in-memory `DashMap` front over
//!   the disk back, so parallel tasks don't race through the file cache for the
//!   same key (the in-memory layer pays the first miss once; the disk layer
//!   persists it). Exemplars: the `diff_stats` field below, and
//!   [`Repository::merge_base_by_sha`] — `wt list`'s orphan check forks
//!   `merge-base` once per row even when the ahead/behind counts are already
//!   cache-warm, so without the disk back every re-run re-pays N forks; per-row
//!   recompute also runs 10–25 ms on macOS, not the ~1 ms a fast Linux box
//!   sees.
//!
//! **Lifetime.** Neither in-memory layer is ever invalidated. `RepoCache` lives as
//! long as the `Repository` it's attached to (typically the command).
//! Process-wide statics live for the process. For the CLI that's the same
//! thing — one command per process — but tests run many commands in one
//! process, so they may observe state from prior test cases (in practice
//! safe: tests use unique tempdir paths, and the maps are filesystem-keyed).
//!
//! **Sharing.** `Repository` holds an `Arc<RepoCache>`, so cloning a `Repository`
//! (e.g., to pass into parallel worktree operations in `wt list`) shares the same
//! cache. Callers that need a *separate* cache must call `Repository::at()` again
//! — but the process-wide maps are still shared in either case.
//!
//! **What is NOT cached.** Values that change during command execution are intentionally
//! excluded:
//! - `WorkingTree::is_dirty()` — changes as we stage and commit
//! - `WorkingTree::head_sha()` — HEAD moves on commit, rebase, or merge; a stale SHA
//!   would surface in template variables (`{{ commit }}`) for hooks that fire after the move
//!
//! [`Repository::list_worktrees`] is cached despite mutating commands adding or
//! removing worktrees. The cache is safe because no caller reads the list
//! through the same `Repository` after its own mutation — mutating paths
//! either read once up front and thread the slice through, or rebuild a
//! fresh `Repository::at(...)` before any post-mutation probe. This mirrors
//! the invariant the branch inventories already rely on.
//!
//! **Access patterns.** See the [`RepoCache`] doc comment for the two storage patterns
//! (repo-wide `OnceCell` vs per-key `DashMap`) and their infallible/fallible variants.
//!
//! **Invariants:**
//! - A cached value, once written, is never updated within the same command —
//!   with one exception: the `all_config` map is an `OnceCell<RwLock<..>>` whose
//!   *contents* stay coherent with in-process writes via
//!   [`Repository::set_config_value`]. The `OnceCell` slot is still written
//!   once; only the config values it holds can change.
//! - Cache access is lock-free at the call site for the `OnceCell`/`DashMap`
//!   caches, which handle synchronization internally. The one exception is
//!   `all_config`, whose `RwLock` callers lock explicitly (e.g. `config_last`)
//!   so config writes stay visible to later reads.
//! - Code that mutates repository state (committing, creating worktrees) must not read
//!   its own mutations through the cache. Use direct git commands for post-mutation
//!   state.
//!
//! **Other process-level singletons.** Outside `RepoCache` and the
//! git-discovery caches above, several modules use `OnceLock`/`LazyLock` for
//! process-global singletons that are *lazy initialization, not caches* —
//! the container is initialized once and never replaced, with no underlying
//! external state that could go stale:
//! - Resource limiters: `CMD_SEMAPHORE` (shell_exec), `HEAVY_OPS_SEMAPHORE` (git),
//!   `LLM_SEMAPHORE` (summary), `COPY_POOL` (copy)
//! - Global state: `OUTPUT_STATE` (output), `TRACE` and `SUBPROCESS` (log_files), `COMMAND_LOG`
//! - Config: `CONFIG_PATH` (config/user/path), `SHELL_CONFIG`, `GIT_ENV_OVERRIDES` (shell_exec)
//! - Serialization: `REPOSITORY_LOCKS` (this module) — one lock set per canonical
//!   git common dir, handed to each `Repository` at construction. Its registry
//!   lock prevents `list_worktrees` reads and `git worktree remove` teardowns
//!   from overlapping; its deletion coordinator serializes safe ref mutations.
//!   Keyed like a cache but holding no git data, so nothing in it goes stale;
//!   see the static's own doc comment for the ordering rules.
//!
//! The picker also maintains a `PreviewCache` (`Arc<DashMap>` in `commands/picker/items.rs`)
//! for rendered preview output, scoped to a single picker session.

use std::ffi::{OsStr, OsString};
use std::path::{Path, PathBuf};
use std::process::Stdio;
use std::sync::{Arc, LazyLock, OnceLock, RwLock, RwLockReadGuard, RwLockWriteGuard};

use crate::shell_exec::Cmd;

use dashmap::DashMap;
use once_cell::sync::OnceCell;

use anyhow::Context;
use dunce::canonicalize;

use crate::config::{LoadError, ProjectConfig, ProjectId, ResolvedConfig, UserConfig};

// Import types from parent module
use super::{
    CommandError, DefaultBranchName, ErrorExt, ForgeKind, GitError, GitItemId, LineDiff,
    WorktreeInfo, git_path_from_bytes,
};

// Re-export types needed by submodules
pub(super) use super::{
    BranchCategory, CompletionBranch, DiffStats, GitRemoteUrl, GitRepoInfo, LocalBranch,
    RemoteBranch,
};

// Submodules with impl blocks
mod branch;
mod branches;
mod config;
mod diff;
mod integration;
mod ref_snapshot;
mod remotes;
pub mod sha_cache;
mod working_tree;
mod worktrees;

// Re-export WorkingTree, Branch, IntegrationTargets, and RefSnapshot
pub use branch::Branch;
pub use branch::is_valid_branch_name;
pub use diff::{CommitMessageDetail, PreparedDiff};
pub use integration::{BranchDiffSpec, IntegrationTargets, select_comparison_base};
pub use ref_snapshot::RefSnapshot;
pub(super) use working_tree::path_to_logging_context;
use working_tree::registration_worktree_path;
pub use working_tree::{InProgressOperation, SafetyBackup, TempIndex, WorkingTree};
pub use worktrees::{StaleWorktreeWork, duplicated_branches};

// ============================================================================
// Repository Cache
// ============================================================================

/// Cached data for a single repository.
///
/// Contains:
/// - Repo-wide values (same for all worktrees): is_bare, default_branch, etc.
/// - Per-worktree values keyed by path: status_porcelain
///
/// Per-worktree git-discovery values that used to live here
/// (`worktree_roots`, `git_dirs`, `current_branches`) are now process-wide
/// statics ([`WORKTREE_ROOTS`], [`GIT_DIRS`], [`CURRENT_BRANCHES`]) next to
/// [`GIT_COMMON_DIR_CACHE`]. Same staleness contract — populated once, never
/// invalidated — but they survive across `Repository::current()` calls so a
/// single eager [`Repository::prewarm`] in `main` warms every later instance.
///
/// Wrapped in Arc to allow releasing the outer HashMap lock before accessing
/// cached values, avoiding deadlocks when cached methods call each other.
///
/// # Cache access patterns
///
/// Repo-wide values use `OnceCell::get_or_init` / `get_or_try_init` — single
/// initialization, no key.
///
/// Keyed values use `DashMap`. Both patterns hold the shard lock across
/// check-and-insert (no TOCTOU gap). Choose based on whether computation
/// is fallible:
///
/// **Infallible** — use `entry().or_insert_with()`:
///
/// ```rust,ignore
/// self.cache.some_map
///     .entry(key)
///     .or_insert_with(|| compute())
///     .clone()
/// ```
///
/// **Fallible** — use explicit `Entry` matching to propagate errors:
///
/// ```rust,ignore
/// match self.cache.some_map.entry(key) {
///     Entry::Occupied(e) => Ok(e.get().clone()),
///     Entry::Vacant(e) => {
///         let value = compute()?;
///         Ok(e.insert(value).clone())
///     }
/// }
/// ```
#[derive(Debug, Default)]
pub(super) struct RepoCache {
    // ========== Repo-wide values (same for all worktrees) ==========
    /// Every git config key in the merged config (system + global + repo),
    /// populated by one `git config --list -z` read on first access.
    ///
    /// All the single-key config accessors (`is_bare`, `primary_remote`,
    /// `remote_url`, `default_branch` fast path, hint/marker readers)
    /// consult this map instead of spawning their own subprocess. Multivars
    /// (e.g., multiple `remote.origin.url` entries) accumulate in the Vec.
    /// `RwLock` rather than `OnceCell` so in-process writes via
    /// [`Repository::set_config_value`] stay coherent after population.
    ///
    /// `IndexMap` preserves insertion order, matching git's own `--list -z`
    /// output order — so accessors that iterate the map (e.g.,
    /// `primary_remote` picking "first remote with a URL") follow config
    /// file order the same way the old `--get-regexp` calls did.
    pub(super) all_config: OnceCell<std::sync::RwLock<indexmap::IndexMap<String, Vec<String>>>>,
    /// Repository root path (main worktree for normal repos, bare directory for bare repos)
    pub(super) repo_path: OnceCell<PathBuf>,
    /// Default branch (main, master, etc.)
    pub(super) default_branch: OnceCell<Option<String>>,
    /// Upstream-aware comparison base for the diff/summary preview panes —
    /// [`integration::IntegrationTargets::primary`], resolved once. Repo-wide
    /// like `default_branch`; builds a [`RefSnapshot`] from the branch
    /// inventories on first access via
    /// [`Repository::branch_diff_spec`]. `None` when no default branch resolves.
    pub(super) comparison_base: OnceCell<Option<integration::ComparisonBase>>,
    /// Project identifier derived from remote URL
    pub(super) project_identifier: OnceCell<ProjectId>,
    /// Project config (loaded from .config/wt.toml in main worktree)
    pub(super) project_config: OnceCell<Option<ProjectConfig>>,
    /// CI platform from project config (`forge.platform` / `ci.platform`).
    /// `None` when unset or unrecognized; an unrecognized value warns once,
    /// deduplicating the warning across the many branches `wt list` probes.
    /// Resolved via [`Repository::ci_platform`].
    pub(super) configured_ci_platform: OnceCell<Option<ForgeKind>>,
    /// User config (raw, as loaded from disk).
    /// Populated by [`Repository::at`] from the
    /// [`WORKTRUNK_USER_CONFIG_PRELOAD`] preload when prewarm ran; otherwise
    /// loaded on first access via [`Repository::user_config`].
    pub(super) user_config: OnceCell<UserConfig>,
    /// Resolved user config (global merged with per-project overrides, defaults applied).
    /// Lazily loaded on first access via `Repository::config()`.
    pub(super) resolved_config: OnceCell<ResolvedConfig>,
    /// Sparse checkout paths (empty if not a sparse checkout)
    pub(super) sparse_checkout_paths: OnceCell<Vec<String>>,
    /// Width git abbreviates a SHA to here, resolved once via
    /// [`Repository::abbrev_len`]. Repo-wide and settled for the process:
    /// `core.abbrev` doesn't change mid-run, and the auto-scaled default only
    /// moves as the object count crosses a power of two.
    pub(super) abbrev_len: OnceCell<usize>,
    /// Merge-base cache: (sha1, sha2) -> merge_base_sha (None = no common ancestor).
    /// Keys are commit SHAs by contract — callers must resolve refs through
    /// a [`RefSnapshot`] before consulting. The key order is normalized
    /// (`(min, max)`) since merge-base is symmetric. This is the in-memory
    /// front over the persistent `merge-base/` [`sha_cache`] back; see
    /// [`Repository::merge_base_by_sha`].
    pub(super) merge_base: DashMap<(String, String), Option<String>>,
    /// Ahead/behind counts keyed by the ordered (base, head) SHA pair. The
    /// entry lock coalesces concurrent misses from list's parallel tasks.
    /// The persistent `ahead-behind/` cache serves later processes.
    pub(super) ahead_behind: DashMap<(String, String), (usize, usize)>,
    /// Commit→tree cache: commit_sha -> tree_sha. Keys are commit SHAs by
    /// contract; a commit's tree is immutable, so the mapping is never stale
    /// within a process. Dedups the `wt list` integration probe, where every
    /// branch row peels the same default-branch tip to its tree. Resolved via
    /// [`Repository::commit_to_tree_sha`].
    pub(super) commit_tree: DashMap<String, String>,
    /// In-memory merge-tree outcome cache: (a_sha, b_sha) -> outcome.
    /// `git merge-tree --write-tree` is the costliest op in `wt list`, and the
    /// conflict probe (`has_merge_conflicts_by_sha`) and the integration probe
    /// (`merge_integration_probe_by_sha` via `would_merge_add_to_target`) run
    /// the identical `(target, branch)` merge per row for two different
    /// answers. Their persistent caches (`merge-tree-conflicts` vs
    /// `merge-add-probe`) are keyed separately, so a cold run would spawn the
    /// subprocess twice; this front collapses both to one via the entry-lock
    /// pattern (same as [`Self::merge_base`]). Keys are commit SHAs in call
    /// order — see `Repository::merge_tree_outcome`.
    pub(super) merge_tree: DashMap<(String, String), integration::MergeTreeOutcome>,
    /// Effective remote URLs: remote_name -> effective URL (with `url.insteadOf` applied).
    /// Separate from `all_config` because `git remote get-url` applies
    /// `url.insteadOf` rewrites that aren't visible in raw config.
    pub(super) effective_remote_urls: DashMap<String, Option<String>>,

    /// Local branch inventory: one `git for-each-ref refs/heads/` scan, cached
    /// for the lifetime of the repository. Entries are sorted by most recent
    /// commit first; the inventory also holds a name → index map for O(1)
    /// single-branch lookups. Populated lazily via
    /// [`Repository::local_branches`].
    ///
    /// **The `commit_sha` field on each entry is a snapshot at scan time.**
    /// Code that needs a current SHA must resolve through
    /// [`Repository::capture_refs`] at the moment the read happens — not
    /// through this inventory or a snapshot built from it.
    /// Everything else the inventory holds goes stale the same way once the
    /// command runs a hook; [`Repository::local_branches`] owns that contract.
    pub(super) local_branches: OnceCell<branches::LocalBranchInventory>,
    /// Remote-tracking branch inventory: one `git for-each-ref refs/remotes/`
    /// scan, cached for the lifetime of the repository. Sorted by most recent
    /// commit first. Populated lazily via [`Repository::remote_branches`].
    /// Excludes `<remote>/HEAD` symrefs. Same snapshot-at-scan-time contract
    /// as [`Self::local_branches`] applies to `commit_sha`.
    pub(super) remote_branches: OnceCell<Vec<RemoteBranch>>,
    /// Worktree inventory: one `git worktree list --porcelain` scan, cached
    /// for the lifetime of the repository. Populated lazily via
    /// [`Repository::list_worktrees`]. The picker warms this on the main
    /// thread (for its preview-window sizing estimate) so the background
    /// `collect::collect` pass hits memory instead of respawning the
    /// subprocess on the critical path to skeleton.
    pub(super) worktrees: OnceCell<Vec<WorktreeInfo>>,
    /// In-memory branch diff stats cache: (base_sha, head_sha) -> LineDiff.
    /// Sits in front of the persistent `sha_cache` to prevent parallel tasks
    /// from racing through the file-based cache for the same SHA pair.
    pub(super) diff_stats: DashMap<(String, String), LineDiff>,

    // ========== Per-worktree values (keyed by path) ==========
    //
    // Earlier per-worktree git-discovery maps (`worktree_roots`, `git_dirs`,
    // `current_branches`) lived here too. They moved out to the process-wide
    // statics next to [`GIT_COMMON_DIR_CACHE`] so [`Repository::prewarm`] can
    // populate them once for the cold path and have every later
    // `Repository::current()` (which builds a fresh `RepoCache`) reuse the
    // result. The data is filesystem-keyed and process-invariant, so per-Repo
    // scoping never bought anything.
    //
    /// Cached `git status --porcelain` output per worktree: worktree_path -> raw porcelain.
    /// Populated by `WorkingTree::status_porcelain_cached()` so parallel tasks
    /// (working-tree diff + conflict detection) share one subprocess per worktree
    /// instead of spawning `git status` twice.
    pub(super) status_porcelain: DashMap<PathBuf, String>,
    /// Process-scoped object databases created by observational repository
    /// clones. Original clones consult this shared set so Worktrunk's own
    /// temporary directories never appear as untracked worktree content.
    pub(super) observation_object_directories: DashMap<PathBuf, ()>,
}

/// Result of resolving a worktree name.
///
/// Used by `resolve_worktree` to handle different resolution outcomes:
/// - A worktree exists (with optional branch for detached HEAD)
/// - Only a branch exists (no worktree)
/// - The selector named a directory that holds no worktree
#[derive(Debug, Clone)]
pub enum ResolvedWorktree {
    /// A worktree was found
    Worktree {
        /// The filesystem path to the worktree
        path: PathBuf,
        /// The branch name, if known (None for detached HEAD)
        branch: Option<String>,
        /// Canonical identity captured when the selector resolves.
        id: GitItemId,
    },
    /// Only a branch exists (no worktree)
    BranchOnly {
        /// The branch name
        branch: String,
        /// Canonical local-ref identity captured when the selector resolves.
        id: GitItemId,
    },
    /// The selector named a directory holding no worktree — the skeleton an
    /// interrupted create or remove leaves behind.
    ///
    /// A verdict rather than a caller's job: every place that reports "no such
    /// thing" has to say whether it was looking for a branch or a path, and
    /// [`Repository::path_selector_directory`] owns the four tests that make the
    /// claim safe. Returning it here is what keeps those tests from being
    /// re-invoked, or forgotten, at each reporting site.
    NoWorktreeAtPath {
        /// The directory, resolved against `-C` but spelled as the selector did
        path: PathBuf,
    },
}

impl ResolvedWorktree {
    fn worktree(path: PathBuf, branch: Option<String>) -> Self {
        let id = GitItemId::worktree(&path);
        Self::Worktree { path, branch, id }
    }

    fn branch_only(branch: String) -> Self {
        let id = GitItemId::local_branch(&branch);
        Self::BranchOnly { branch, id }
    }

    /// Canonical identity selected by this resolution, when it names a Git
    /// item rather than an unregistered directory.
    pub fn id(&self) -> Option<&GitItemId> {
        match self {
            Self::Worktree { id, .. } | Self::BranchOnly { id, .. } => Some(id),
            Self::NoWorktreeAtPath { .. } => None,
        }
    }
}

/// A worktree selector after normalization and expansion — the token to look
/// up, plus whether it may still be tried as a *path*.
///
/// Every assembly of the resolution ladder needs that second fact, and each
/// used to re-derive it by comparing an expansion's output against its input —
/// `branch == name` in `resolve_worktree`, `target.branch == branch` in
/// `plan_switch`, `target.filter(|t| *t == resolved)` in
/// `target_worktree_at_path`, `resolved == base` in `resolve_base_ref`. Four
/// copies of one string heuristic standing in for something the producing step
/// knows outright, and a trap for any normalization applied underneath them:
/// stripping `docs/` to `docs` reads as a rewrite and silently disables the
/// path arm.
///
/// So the producers state it. A token nobody touched may name a path
/// ([`Selector::literal`]). One an earlier step produced may not
/// ([`Selector::rewritten_to`]) — a shortcut expansion, a `pr:`/`mr:` lookup, a
/// stripped remote prefix, a default branch read from cache.
#[derive(Debug, Clone)]
pub struct Selector {
    token: String,
    may_name_path: bool,
}

impl Selector {
    /// A token the user typed and nothing rewrote — the path arm applies.
    pub fn literal(token: impl Into<String>) -> Self {
        Self {
            token: token.into(),
            may_name_path: true,
        }
    }

    /// A token some earlier step produced, so the literal argument is not what
    /// this names and a path lookup would be a nonsense one.
    pub fn rewritten_to(token: impl Into<String>) -> Self {
        Self {
            token: token.into(),
            may_name_path: false,
        }
    }

    /// The name to look up.
    pub fn token(&self) -> &str {
        &self.token
    }

    /// Whether this token may still be tried as a worktree path.
    pub fn names_a_path(&self) -> bool {
        self.may_name_path
    }
}

/// Global base path for repository operations, set by -C flag.
static BASE_PATH: OnceLock<PathBuf> = OnceLock::new();

/// Default base path when -C flag is not provided.
static DEFAULT_BASE_PATH: LazyLock<PathBuf> = LazyLock::new(|| PathBuf::from("."));

/// Process-wide cache for `git rev-parse --git-common-dir` resolution,
/// keyed by the discovery path passed to [`Repository::at`].
///
/// Unlike per-Repository caches, this lives for the whole process so that
/// multiple Repository instances pointed at the same path (e.g.
/// `init_command_log` early in `main`, then a command handler later) skip
/// the duplicate `git rev-parse` subprocess. The value (a canonicalized
/// `.git` directory) is invariant for the lifetime of the process.
///
/// Keys are stored as-is (not canonicalized) — the goal is only to dedupe
/// repeated calls with the same path. The duplicate case we care about (both
/// callers go through `base_path()`) always passes the same `PathBuf`, so
/// equality on the raw path is sufficient.
static GIT_COMMON_DIR_CACHE: LazyLock<DashMap<PathBuf, PathBuf>> = LazyLock::new(DashMap::new);

/// Process-local coordination for repository mutations, keyed by the canonical
/// Git common directory. Every [`Repository`] for the same common directory
/// shares these locks. The registry lock's dedicated
/// [`Repository::list_worktrees`] accessor takes its read side, while
/// [`Repository::prune_worktree_entry`] and [`Repository::remove_worktree`]
/// take its write side. The branch deletion coordinator serializes safe ref
/// mutations, which contend on Git's packed-refs lock even for different branches.
/// Its interruption state lasts for this process's CLI invocation.
///
/// Registry guards are non-reentrant: a guarded operation must not call another
/// registry accessor. In `wt step prune`, the command's `output_lock` precedes
/// either repository lock; code holding a repository guard must never acquire
/// `output_lock`. Safe branch deletion releases the registry read guard before
/// acquiring the deletion mutex; registry guards never span deletion waits.
///
/// External Git processes and raw worktree commands issued through
/// [`Repository::run_command`] do not honor these locks.
static REPOSITORY_LOCKS: LazyLock<DashMap<PathBuf, Arc<RepositoryLocks>>> =
    LazyLock::new(DashMap::new);

#[derive(Debug, Default)]
struct RepositoryLocks {
    worktree_registry: RwLock<()>,
    branch_deletion: super::ref_deletion::RefDeletionCoordinator,
}

/// Process-wide map of `worktree_path -> canonicalized worktree root`,
/// keyed by the canonicalized path used as the cache key (same convention as
/// [`Repository::worktree_at`] / [`WorkingTree`]).
///
/// Cached values are confirmed worktree roots. Ambiguous batch output leaves
/// discovery to the exact single-selector accessor. The fallback path returned
/// by `WorkingTree::root` when `rev-parse --show-toplevel` fails (deleted CWD,
/// bare repo root, non-repo dir) is
/// **not** persisted, which keeps the membership check usable as a
/// "is-inside-worktree" signal — see [`WorkingTree::prewarm_info`]'s fast path.
///
/// Populated by [`Repository::prewarm`] (eager, one fork on the cold path),
/// [`WorkingTree::prewarm_info`] (lazy via the `rev-parse` batch), and
/// [`WorkingTree::root`] (per-field on demand).
pub(super) static WORKTREE_ROOTS: LazyLock<DashMap<PathBuf, PathBuf>> = LazyLock::new(DashMap::new);

/// Process-wide map of `worktree_path -> canonicalized git directory` (e.g.
/// `.git/worktrees/<name>` for linked worktrees, `.git` for the main worktree).
///
/// Populated by [`Repository::prewarm`], [`WorkingTree::prewarm_info`], and
/// [`WorkingTree::git_dir`].
pub(super) static GIT_DIRS: LazyLock<DashMap<PathBuf, PathBuf>> = LazyLock::new(DashMap::new);

/// Process-wide map of `worktree_path -> current branch` (`None` = detached
/// HEAD; missing entry = unborn HEAD or never resolved).
///
/// Populated by [`Repository::prewarm`], [`WorkingTree::prewarm_info`], and
/// [`WorkingTree::branch`]. The cached value is a snapshot at first read; if a
/// hook checks out a different branch mid-command, the entry stays stale —
/// same contract that the per-`RepoCache` map carried before consolidation.
pub(super) static CURRENT_BRANCHES: LazyLock<DashMap<PathBuf, Option<String>>> =
    LazyLock::new(DashMap::new);

/// Process-wide pre-parsed `git config --list -z` output, keyed by the
/// discovery path passed to [`Repository::prewarm`].
///
/// Populated on the cold path by the `git config --list -z` thread spawned
/// from [`Repository::prewarm_at`] (or, when that read declines under
/// `extensions.worktreeConfig`, by the common-dir post-pass that follows
/// it); consumed by [`Repository::at`] when it builds a fresh `RepoCache`
/// for that discovery path. The point is to overlap the rev-parse and
/// config reads — the two big git invocations on the alias-dispatch
/// critical path — so a plain `wt <alias>` pays for one git startup
/// instead of two in series.
///
/// Best-effort, like the rest of `prewarm`. A failed read leaves the entry
/// empty and the on-demand path inside [`Repository::all_config`] re-forks
/// `git config --list -z` exactly as before.
///
/// Keyed by raw discovery path (no canonicalization) because the consumer in
/// [`Repository::at`] holds the same `PathBuf` value the prewarm thread
/// stored — both originate from `base_path()`. Test paths (`Repository::at`
/// against tempdirs) bypass prewarm and never collide with this map.
pub(super) static GIT_CONFIG_PRELOAD: LazyLock<
    DashMap<PathBuf, indexmap::IndexMap<String, Vec<String>>>,
> = LazyLock::new(DashMap::new);

/// Process-wide preloaded `UserConfig` (worktrunk's user `wt.toml`),
/// populated by [`Repository::prewarm_user_config`] from `main`.
///
/// [`Repository::at`] clones it into `cache.user_config` so the first
/// `repo.user_config()` call is a memory hit, removing the ~4 ms TOML parse
/// from the alias-dispatch critical path.
///
/// `OnceLock` (not `DashMap`) because `UserConfig` is process-scoped, not
/// path-scoped: the path-derivation rule (XDG / `$WORKTRUNK_CONFIG_PATH`)
/// doesn't change during a process lifetime.
///
/// Best-effort: a failed prewarm leaves the lock empty and the on-demand
/// path inside [`Repository::user_config`] reloads from disk exactly as
/// before.
pub(super) static WORKTRUNK_USER_CONFIG_PRELOAD: OnceLock<UserConfig> = OnceLock::new();

/// Initialize the global base path for repository operations.
///
/// This should be called once at program startup from main().
/// If not called, defaults to "." (current directory).
///
/// `-C` sets this path without chdir'ing the process, so it is the base for the
/// two things git gets from its own chdir: the repository [`Repository::current`]
/// discovers, and every path the user supplies, which resolves through
/// [`resolve_input_path`]. The process cwd answers a different question — where
/// the user's shell physically is (the `cd` target after a switch, the
/// cwd-removed recovery check) — so `std::env::current_dir()` substitutes for
/// neither.
pub fn set_base_path(path: PathBuf) {
    BASE_PATH.set(path).ok();
}

/// Directory used for repository discovery, including the command's `-C` base.
pub fn base_path() -> &'static PathBuf {
    BASE_PATH.get().unwrap_or(&DEFAULT_BASE_PATH)
}

/// Resolve a path the user supplied, against the directory wt was pointed at.
///
/// Git resolves the paths in its command line against its own `-C`, because it
/// chdir's there first. wt's `-C` sets [`set_base_path`] instead, so the same
/// semantics come from joining onto that path. An absolute path passes through,
/// as does every path when `-C` was not given — the process cwd already resolves
/// those, and joining `.` onto them would surface as a stray `./` in output.
///
/// A leading `~` expands first (see [`crate::path::expand_tilde`]), so the tilde form wt
/// prints its own paths in is a form wt also accepts.
///
/// This is the one resolution point for those paths, so they cannot drift
/// apart: worktree path arguments (`wt switch ../repo.feature`), `wt switch --path`, `--config`,
/// `WORKTRUNK_CONFIG_PATH`, `WORKTRUNK_SYSTEM_CONFIG_PATH`, and the trace file
/// of `wt config state logs profile`. The rule is "the user named a file for wt
/// to open" — three neighbours look similar and are deliberately outside it:
///
/// - Paths wt derives itself (a worktree root from `git worktree list`, an XDG
///   config directory) are already absolute.
/// - `WORKTRUNK_PROJECT_CONFIG_PATH` resolves from the worktree root, its
///   documented base, because the project config is per-worktree.
/// - `WORKTRUNK_BIN` is never opened by wt: the generated shell wrapper
///   expands it.
pub fn resolve_input_path(path: impl AsRef<Path>) -> PathBuf {
    let path = crate::path::expand_tilde(path.as_ref());
    match BASE_PATH.get() {
        Some(base) => base.join(path),
        None => path.into_owned(),
    }
}

/// A worktree selector with trailing path separators removed.
///
/// Git's ref format forbids a name ending in `/`, so a selector that does can
/// only be a path spelling — and shell completion is how one usually arrives.
/// `wt switch docs<tab>` completes against the *directory* `./docs` whenever
/// one sits beside the branch, yielding `docs/`, and the branch lookup then
/// misses a branch that is right there.
///
/// Applied in [`Repository::expand_selector`] — which every token the user
/// typed reaches before resolution — and again in
/// [`Repository::resolve_worktree`], so its `@` fast path tests the normalized
/// token. A [`Selector`] built straight from [`Selector::rewritten_to`] skips
/// it, correctly: a PR's head branch or a cached default branch was never a
/// spelling anyone chose, so there is nothing to strip.
///
/// That normalization has one home at all is what [`Selector`] buys. While
/// "may this token name a path?" was inferred by comparing an expansion's
/// output against its input, stripping a separator underneath that comparison
/// read as a rewrite and silently disabled the path arm — so each assembly of
/// the ladder had to normalize for itself, or not normalize at all.
///
/// A selector of nothing but separators is returned unchanged — `/` is the
/// root directory, and the empty string names nothing at all.
pub fn normalize_selector(name: &str) -> &str {
    let trimmed = name.trim_end_matches(std::path::is_separator);
    if trimmed.is_empty() { name } else { trimmed }
}

/// Quote one path for Git's C-style alternate-object-directory list.
#[cfg(unix)]
fn quote_alternate_object_directory(path: &OsStr) -> OsString {
    use std::os::unix::ffi::{OsStrExt, OsStringExt};

    let mut quoted = Vec::with_capacity(path.as_bytes().len() + 2);
    quoted.push(b'"');
    for &byte in path.as_bytes() {
        match byte {
            b'\\' | b'"' => {
                quoted.push(b'\\');
                quoted.push(byte);
            }
            b'\n' => quoted.extend_from_slice(b"\\n"),
            b'\r' => quoted.extend_from_slice(b"\\r"),
            b'\t' => quoted.extend_from_slice(b"\\t"),
            b'\x08' => quoted.extend_from_slice(b"\\b"),
            b'\x0c' => quoted.extend_from_slice(b"\\f"),
            b' '..=b'~' => quoted.push(byte),
            _ => {
                quoted.push(b'\\');
                quoted.push(b'0' + ((byte >> 6) & 0o7));
                quoted.push(b'0' + ((byte >> 3) & 0o7));
                quoted.push(b'0' + (byte & 0o7));
            }
        }
    }
    quoted.push(b'"');
    OsString::from_vec(quoted)
}

#[cfg(not(unix))]
fn quote_alternate_object_directory(path: &OsStr) -> OsString {
    let mut quoted = String::from("\"");
    for ch in path.to_string_lossy().chars() {
        match ch {
            '\\' | '"' => {
                quoted.push('\\');
                quoted.push(ch);
            }
            '\n' => quoted.push_str("\\n"),
            '\r' => quoted.push_str("\\r"),
            '\t' => quoted.push_str("\\t"),
            _ => quoted.push(ch),
        }
    }
    quoted.push('"');
    quoted.into()
}

/// Prepend the real object database while preserving inherited alternates.
fn alternate_object_directories(primary: &Path) -> OsString {
    let mut alternates = quote_alternate_object_directory(primary.as_os_str());
    if let Some(inherited) =
        std::env::var_os("GIT_ALTERNATE_OBJECT_DIRECTORIES").filter(|value| !value.is_empty())
    {
        alternates.push(if cfg!(windows) { ";" } else { ":" });
        alternates.push(inherited);
    }
    alternates
}

/// Repository state for git operations.
///
/// Represents the shared state of a git repository (the `.git` directory).
/// For worktree-specific operations, use [`WorkingTree`] obtained via
/// [`current_worktree()`](Self::current_worktree) or [`worktree_at()`](Self::worktree_at).
///
/// # Examples
///
/// ```no_run
/// use worktrunk::git::Repository;
///
/// let repo = Repository::current()?;
/// let wt = repo.current_worktree();
///
/// // Repo-wide operations
/// if let Some(default) = repo.default_branch() {
///     println!("Default branch: {}", default);
/// }
///
/// // Worktree-specific operations
/// let branch = wt.branch()?;
/// let dirty = wt.is_dirty()?;
/// # Ok::<(), anyhow::Error>(())
/// ```
#[derive(Debug, Clone)]
pub struct Repository {
    /// Path used for discovering the repository and running git commands.
    /// For repo-wide operations, any path within the repo works.
    discovery_path: PathBuf,
    /// The shared .git directory, computed at construction time.
    git_common_dir: PathBuf,
    /// Cached data for this repository. Shared across clones via Arc.
    pub(super) cache: Arc<RepoCache>,
    /// Shared by every `Repository` that resolves to `git_common_dir`.
    locks: Arc<RepositoryLocks>,
    /// When set, object-writing git plumbing is redirected into a temporary
    /// object database. `None` for the normal persistent path. See
    /// [`Repository::redirect_objects_for_observation`].
    /// Held behind an `Arc` so list's parallel repository clones share one
    /// store, removed when the last clone drops.
    temporary_object_store: Option<Arc<TemporaryObjectStore>>,
}

/// A process-scoped object database plus its visibility registration.
///
/// The shared registration lets repository clones that do not carry the
/// redirect exclude Worktrunk's own directory from untracked-file views. It
/// must disappear with the last redirected clone so a subsequently-created
/// user path at the same location is visible again.
#[derive(Debug)]
struct TemporaryObjectStore {
    directory: tempfile::TempDir,
    alternates: OsString,
    registered_path: PathBuf,
    cache: Arc<RepoCache>,
}

impl Drop for TemporaryObjectStore {
    fn drop(&mut self) {
        self.cache
            .observation_object_directories
            .remove(&self.registered_path);
    }
}

/// Accept only complete selector batches; an unborn HEAD is Git's one
/// expected partial failure. Embedded path newlines invalidate the framing.
fn rev_parse_fields(output: &std::process::Output, count: usize) -> Option<Vec<&[u8]>> {
    let bytes = output.stdout.strip_suffix(b"\n")?;
    let fields: Vec<_> = bytes.split(|byte| *byte == b'\n').collect();
    (fields.len() == count
        && (output.status.success() || fields.last() == Some(&b"HEAD".as_slice())))
    .then_some(fields)
}

impl Repository {
    /// Discover the repository from the current directory.
    ///
    /// This is the primary way to create a Repository. If the -C flag was used,
    /// this uses that path instead of the actual current directory.
    ///
    /// For worktree-specific operations on paths other than cwd, use
    /// `repo.worktree_at(path)` to get a [`WorkingTree`].
    pub fn current() -> anyhow::Result<Self> {
        Self::at(base_path().clone())
    }

    /// Discover the repository from the specified path.
    ///
    /// Creates a new Repository with its own cache. For sharing cache across
    /// operations (e.g., parallel tasks in `wt list`), clone an existing
    /// Repository instead of calling `at()` multiple times.
    ///
    /// Use cases:
    /// - **Command entry points**: Starting a new command that needs a Repository
    /// - **Tests**: Tests that need to operate on test repositories
    ///
    /// For worktree-specific operations within an existing Repository context,
    /// use [`Repository::worktree_at()`] instead.
    pub fn at(path: impl Into<PathBuf>) -> anyhow::Result<Self> {
        let discovery_path = path.into();
        let git_common_dir = Self::resolve_git_common_dir(&discovery_path)?;
        let locks = REPOSITORY_LOCKS
            .entry(git_common_dir.clone())
            .or_insert_with(|| Arc::new(RepositoryLocks::default()))
            .clone();

        let cache = RepoCache::default();
        // Consume any `git config --list -z` map preloaded by
        // `Repository::prewarm` so the first `all_config()` call is a memory
        // hit. The preload is keyed by the same `discovery_path` value that
        // prewarm stashed under (both originate from `base_path()`); a miss
        // (different path, no prewarm, test repo) leaves the OnceCell empty
        // and the on-demand fork inside `all_config` runs as before.
        if let Some(entry) = GIT_CONFIG_PRELOAD.get(&discovery_path) {
            let _ = cache
                .all_config
                .set(std::sync::RwLock::new(entry.value().clone()));
        }

        // Same idea for the worktrunk-side `UserConfig`: if the prewarm
        // thread loaded it already, clone it into the per-Repository cache so
        // the first `repo.user_config()` call is a memory hit. A miss (no
        // prewarm, test repo) leaves the OnceCell empty and the on-demand
        // path in `user_config()` reloads from disk.
        if let Some(preloaded) = WORKTRUNK_USER_CONFIG_PRELOAD.get() {
            let _ = cache.user_config.set(preloaded.clone());
        }

        Ok(Self {
            discovery_path,
            git_common_dir,
            cache: Arc::new(cache),
            locks,
            temporary_object_store: None,
        })
    }

    /// Share registry coordination across fresh repository caches.
    pub(super) fn worktree_registry_read(&self) -> RwLockReadGuard<'_, ()> {
        self.locks
            .worktree_registry
            .read()
            .unwrap_or_else(|error| error.into_inner())
    }

    /// Exclude registry readers and other teardowns for this repository.
    pub(super) fn worktree_registry_write(&self) -> RwLockWriteGuard<'_, ()> {
        self.locks
            .worktree_registry
            .write()
            .unwrap_or_else(|error| error.into_inner())
    }

    /// Serialize safe ref mutations without blocking registry readers.
    pub(super) fn branch_deletions(&self) -> &super::ref_deletion::RefDeletionCoordinator {
        &self.locks.branch_deletion
    }

    /// Return a clone whose object-writing git plumbing is redirected into a
    /// temporary object database.
    ///
    /// Only *observational* commands may redirect. `wt list`'s merge and
    /// conflict probes create ephemeral objects (`write-tree`, `commit-tree`,
    /// `merge-tree --write-tree`) that are never referenced, so writing them to
    /// a throwaway store is harmless and lets the command run in a read-only
    /// checkout. If the system temporary directory is unavailable, the store
    /// falls back to the Git common directory. A *mutating* command must never
    /// redirect because its commit would disappear with the store.
    pub fn redirect_objects_for_observation(&self) -> anyhow::Result<Self> {
        let alternate = self.object_database_path();
        let mut builder = tempfile::Builder::new();
        builder.prefix("worktrunk-list-objects-");
        let directory = match builder.tempdir() {
            Ok(directory) => directory,
            Err(temp_error) => builder.tempdir_in(&self.git_common_dir).context(format!(
                "Failed to create temporary object database in the system temp directory or Git common directory; system temp error: {temp_error}"
            ))?,
        };
        let alternates = alternate_object_directories(&alternate);
        let registered_path = directory.path().to_path_buf();
        self.cache
            .observation_object_directories
            .insert(registered_path.clone(), ());

        let mut clone = self.clone();
        clone.temporary_object_store = Some(Arc::new(TemporaryObjectStore {
            directory,
            alternates,
            registered_path,
            cache: Arc::clone(&self.cache),
        }));
        Ok(clone)
    }

    /// Absolute path to the effective object database that a redirected
    /// repository names as its read-only alternate.
    fn object_database_path(&self) -> PathBuf {
        let objects = std::env::var_os("GIT_OBJECT_DIRECTORY")
            .map(PathBuf::from)
            .map(|path| {
                if path.is_absolute() {
                    path
                } else {
                    std::env::current_dir()
                        .unwrap_or_else(|_| self.discovery_path.clone())
                        .join(path)
                }
            })
            .unwrap_or_else(|| self.git_common_dir.join("objects"));
        canonicalize(&objects).unwrap_or(objects)
    }

    /// The object-directory environment for a redirected repository, or `None`
    /// when object writes go to the real database.
    /// Copied into [`WorkingTree`]'s [`TempIndex`], which builds its own `Cmd`.
    pub(super) fn object_store_environment(&self) -> Option<(&Path, &OsStr)> {
        self.temporary_object_store
            .as_ref()
            .map(|store| (store.directory.path(), store.alternates.as_os_str()))
    }

    /// Add the temporary-object-database environment to `cmd` when this
    /// repository is redirected; otherwise return `cmd` unchanged. Applied to
    /// every git command the repository runs, so a redirected repository's
    /// object writes all land in the temporary store.
    fn with_object_store_env(&self, cmd: Cmd) -> Cmd {
        match self.object_store_environment() {
            Some((directory, alternates)) => cmd
                .env("GIT_OBJECT_DIRECTORY", directory)
                .env("GIT_ALTERNATE_OBJECT_DIRECTORIES", alternates),
            None => cmd,
        }
    }

    /// Eagerly populate the process-wide git-discovery caches
    /// (`GIT_COMMON_DIR_CACHE`, `WORKTREE_ROOTS`, `GIT_DIRS`,
    /// `CURRENT_BRANCHES`), the git bulk-config preload
    /// (`GIT_CONFIG_PRELOAD`), and the worktrunk user-config preload
    /// (`WORKTRUNK_USER_CONFIG_PRELOAD`) for the configured base path.
    ///
    /// Called once from `main` after the logger is registered, before
    /// `init_command_log` and alias dispatch. Three threads run concurrently,
    /// each gated on the cache it populates (a `Repository` constructed
    /// before prewarm fills `GIT_COMMON_DIR_CACHE` but must not suppress the
    /// config preloads — see `prewarm_at`):
    ///
    /// - **rev-parse thread**: a single `git rev-parse` fork that folds the
    ///   two cold-path rev-parses (`--git-common-dir` from
    ///   [`Repository::at`] and the `prewarm_info` batch from
    ///   [`Repository::project_config_path`]) into one.
    /// - **git-config thread**: a single `git config --list -z` fork that the
    ///   bulk config map (`Repository::all_config`) would otherwise spawn
    ///   on first read. When it declines (`extensions.worktreeConfig`), a
    ///   post-pass after the threads join re-reads from the resolved
    ///   `git_common_dir` so the preload still lands.
    /// - **user-config thread**: pure file I/O on `$WORKTRUNK_CONFIG_PATH` /
    ///   XDG paths, parsing worktrunk's user `wt.toml`. No git or
    ///   `Repository` involvement, so it overlaps cleanly with both git
    ///   forks and removes the ~4 ms TOML parse from the alias-dispatch
    ///   critical path.
    ///
    /// The three reads are independent: the git threads start from
    /// `discovery_path` and let git auto-discover the repo; the user-config
    /// thread depends only on env vars and XDG paths. Running them in
    /// parallel saves both the second git startup (~7 ms warm, ~10 ms cold)
    /// and the user-config TOML parse (~4 ms cold) on the alias-dispatch
    /// critical path.
    ///
    /// **Best-effort.** All three threads reuse the existing fallbacks: a
    /// failed rev-parse leaves the discovery caches empty (later
    /// `Repository::resolve_git_common_dir` and `WorkingTree::prewarm_info`
    /// reforks restore behaviour); a failed git-config read leaves the
    /// preload empty (later `Repository::all_config` reforks); a failed
    /// user-config read leaves the preload empty (later `Repository::user_config`
    /// reloads from disk). We never propagate errors from here.
    ///
    /// Two partial-success modes the rev-parse batch handles:
    /// - **Bare repo at the bare root**: `--show-toplevel` errors but
    ///   `--git-common-dir` prints first, so `GIT_COMMON_DIR_CACHE` still
    ///   lands. Per-worktree maps stay empty for that path — same as the
    ///   existing `WorkingTree::root` fallback contract — so `prewarm_info`
    ///   reforks once for the not-inside-a-worktree determination. That edge
    ///   case loses the prewarm benefit but matches the unoptimized baseline.
    /// - **Unborn HEAD**: every selector emits a line but rev-parse exits
    ///   non-zero. We populate `WORKTREE_ROOTS` and `GIT_DIRS` but leave
    ///   `CURRENT_BRANCHES` to the `symbolic-ref` fallback in
    ///   [`WorkingTree::branch`], matching the existing `prewarm_info`
    ///   behaviour.
    ///
    /// Outside any work tree (`wt` invoked from a non-repo directory) the
    /// rev-parse batch and the git-config read both fail and we cache
    /// nothing for them — [`Repository::at`] later runs its own rev-parse
    /// and surfaces the discovery error. The user-config preload still
    /// succeeds (it doesn't depend on the repo).
    pub fn prewarm() {
        Self::prewarm_at(base_path());
    }

    /// Path-explicit form of [`Self::prewarm`], factored out so tests can
    /// drive prewarm against a specific repo without mutating the global
    /// `BASE_PATH` `OnceLock`.
    pub(super) fn prewarm_at(discovery_path: &Path) {
        // Each thread is gated on the cache it populates, not on a shared
        // key. A `Repository` constructed before prewarm (the `-vv` log-file
        // sinks in `log_files::init` resolve one during `logging::init`)
        // fills `GIT_COMMON_DIR_CACHE` without touching the config preloads;
        // gating everything on that one key would silently skip them and
        // every later construction would re-fork `git config --list -z` —
        // which also made `-vv` traces overstate the fork pattern of a
        // normal run. A skipped rev-parse leaves the per-worktree maps to
        // `prewarm_info`, which reforks on first use.
        let need_rev_parse = !GIT_COMMON_DIR_CACHE.contains_key(discovery_path);
        let need_git_config = !GIT_CONFIG_PRELOAD.contains_key(discovery_path);
        let need_user_config = WORKTRUNK_USER_CONFIG_PRELOAD.get().is_none();
        if !need_rev_parse && !need_git_config && !need_user_config {
            return;
        }

        let _span = crate::trace::Span::new("prewarm");

        // Run the rev-parse, git-config, and user-config reads concurrently
        // on scoped threads. The two git threads target the same repo and
        // don't depend on each other's output; the user-config thread is
        // pure file I/O on XDG paths and doesn't touch git at all.
        // Overlapping them removes ~one git startup (~7 ms warm, ~10 ms
        // cold) plus the ~4 ms user-config TOML parse from the
        // alias-dispatch critical path. Failures in any branch leave the
        // caches empty and the on-demand callers re-fork — same
        // best-effort contract `prewarm` always had.
        std::thread::scope(|s| {
            if need_rev_parse {
                s.spawn(|| {
                    let _span = crate::trace::Span::new("prewarm_rev_parse");
                    Self::prewarm_rev_parse(discovery_path);
                });
            }
            if need_git_config {
                s.spawn(|| {
                    let _span = crate::trace::Span::new("prewarm_git_config");
                    Self::prewarm_git_config(discovery_path);
                });
            }
            if need_user_config {
                s.spawn(|| {
                    let _span = crate::trace::Span::new("prewarm_user_config");
                    Self::prewarm_user_config();
                });
            }
        });

        // `prewarm_git_config` declines the preload under
        // `extensions.worktreeConfig` because its discovery-path read misses
        // the main worktree's `config.worktree` overrides ([#2779]). Now that
        // the rev-parse thread has landed the common dir, run the read
        // [`Repository::all_config`] would otherwise fork on first access —
        // `git config --list -z` from `git_common_dir` — and preload that
        // merged map, so those repos get the same memory-hit constructions
        // as everyone else. One serialized fork here replaces the on-demand
        // one; a repo whose rev-parse failed (not a repo at all) skips this.
        if !GIT_CONFIG_PRELOAD.contains_key(discovery_path)
            && let Some(common_dir) = GIT_COMMON_DIR_CACHE
                .get(discovery_path)
                .map(|entry| entry.value().clone())
        {
            let _span = crate::trace::Span::new("prewarm_git_config_common_dir");
            Self::prewarm_git_config_from_common_dir(discovery_path, &common_dir);
        }
    }

    /// Rev-parse half of [`Self::prewarm_at`] — populates
    /// `GIT_COMMON_DIR_CACHE`, `WORKTREE_ROOTS`, `GIT_DIRS`, and
    /// `CURRENT_BRANCHES` from a single `git rev-parse` fork. See
    /// [`Self::prewarm`] for the partial-success contract.
    fn prewarm_rev_parse(discovery_path: &Path) {
        // Order matters: `git rev-parse` emits one stdout line per selector in
        // argument order, and we parse positionally. `--git-common-dir` first
        // so even when later selectors fail (bare repo at the bare root, no
        // worktree, …) the common dir still lands.
        let Ok(output) = Cmd::new("git")
            .args([
                "rev-parse",
                "--git-common-dir",
                "--is-inside-work-tree",
                "--show-toplevel",
                "--git-dir",
                "--symbolic-full-name",
                "HEAD",
            ])
            .current_dir(discovery_path)
            .context(path_to_logging_context(discovery_path))
            .run()
        else {
            return;
        };

        // Bare discovery stops after the common directory and `false`.
        let bare = output
            .stdout
            .strip_suffix(b"\nfalse\n")
            .filter(|path| !path.contains(&b'\n'));
        let fields = if let Some(common) = bare {
            vec![common, b"false".as_slice()]
        } else {
            let Some(fields) = rev_parse_fields(&output, 5).filter(|fields| fields[1] == b"true")
            else {
                return;
            };
            fields
        };
        let mut fields = fields.into_iter();

        // Common-dir precedes selectors that can fail in bare or unborn repos.
        let Some(common_path) = fields.next().and_then(|raw| git_path_from_bytes(raw).ok()) else {
            return;
        };
        let common_absolute = if common_path.is_relative() {
            discovery_path.join(common_path)
        } else {
            common_path
        };
        let Ok(common_resolved) = canonicalize(&common_absolute) else {
            return;
        };
        GIT_COMMON_DIR_CACHE.insert(discovery_path.to_path_buf(), common_resolved);
        let worktree_key =
            canonicalize(discovery_path).unwrap_or_else(|_| discovery_path.to_path_buf());
        if fields.next() != Some(b"true".as_slice()) {
            return;
        }

        if let Some(root) = fields
            .next()
            .and_then(|raw| canonicalize(git_path_from_bytes(raw).ok()?).ok())
        {
            WORKTREE_ROOTS.entry(worktree_key.clone()).or_insert(root);
        }
        if let Some(git_dir) = fields.next().and_then(|raw| {
            let path = git_path_from_bytes(raw).ok()?;
            let absolute = if path.is_relative() {
                discovery_path.join(path)
            } else {
                path
            };
            canonicalize(absolute).ok()
        }) {
            GIT_DIRS.entry(worktree_key.clone()).or_insert(git_dir);
        }
        // An unborn HEAD prints a fallback despite the failed batch; leave
        // its branch unresolved so the canonical branch accessor can ask Git.
        if output.status.success()
            && let Some(raw) = fields.next().and_then(|raw| std::str::from_utf8(raw).ok())
        {
            let branch = raw.strip_prefix("refs/heads/").map(str::to_owned);
            CURRENT_BRANCHES.entry(worktree_key).or_insert(branch);
        }
    }

    /// Git-config half of [`Self::prewarm_at`] — runs `git config --list -z`
    /// from `discovery_path` and stashes the parsed map in
    /// [`GIT_CONFIG_PRELOAD`] for [`Repository::at`] to consume.
    ///
    /// Runs from `discovery_path` rather than `git_common_dir` (which we
    /// don't know yet — the rev-parse thread is racing in parallel). Git's
    /// `config --list` normally emits the same merged system + global + local
    /// config from any path inside the repo, including linked worktrees of
    /// bare repos: linked worktrees and the common dir share one config file,
    /// so the merged output is identical to the existing `git_common_dir`
    /// invocation in [`Repository::all_config`].
    ///
    /// **`extensions.worktreeConfig` exception** ([#2779]): when the
    /// extension is enabled, each worktree gets its own `config.worktree`
    /// file (the main worktree at `.git/config.worktree`, linked worktrees
    /// at `.git/worktrees/<name>/config.worktree`). From a linked worktree
    /// `git config --list` merges only that linked worktree's
    /// `config.worktree`, missing values set on the main worktree's
    /// `config.worktree` — most importantly `core.bare = true` for the
    /// bare-style `myproject/.git + sibling worktrees` layout. Caching that
    /// incomplete map would cause `is_bare()` to read `false`, and the
    /// `repo_path()` fallback would walk one level too high. So when the
    /// parsed map contains `extensions.worktreeconfig=true`, we decline the
    /// preload here; the post-pass in [`Repository::prewarm_at`] re-reads
    /// from `git_common_dir` — which sees the full merged set — via
    /// [`Repository::prewarm_git_config_from_common_dir`] once the
    /// rev-parse thread has resolved it.
    ///
    /// Failures (non-repo directory, corrupted config) are swallowed; the
    /// on-demand path inside `all_config` re-forks the same subprocess and
    /// surfaces the error there.
    ///
    /// [#2779]: https://github.com/max-sixty/worktrunk/issues/2779
    fn prewarm_git_config(discovery_path: &Path) {
        let Ok(output) = Cmd::new("git")
            .args(["config", "--list", "-z"])
            .current_dir(discovery_path)
            .context(path_to_logging_context(discovery_path))
            .run()
        else {
            return;
        };
        if !output.status.success() {
            return;
        }
        let parsed = parse_config_list_z(&output.stdout);
        if worktree_config_enabled(&parsed) {
            return;
        }
        GIT_CONFIG_PRELOAD.insert(discovery_path.to_path_buf(), parsed);
    }

    /// Fallback half of the git-config preload: `git config --list -z` run
    /// from `git_common_dir` — byte-for-byte the invocation
    /// [`Repository::all_config`] forks on first access — parsed and stashed
    /// under `discovery_path` for [`Repository::at`] to consume. Called from
    /// the [`Repository::prewarm_at`] post-pass when
    /// [`Repository::prewarm_git_config`] declined (the
    /// `extensions.worktreeConfig` case, or a failed discovery-path read in
    /// a repo the rev-parse thread still resolved). The common-dir read is
    /// safe to cache in both cases because it produces exactly the map the
    /// on-demand path would at this moment — like every preload it is a
    /// startup snapshot, never invalidated by later `set_config` writes
    /// (which update only the writing instance's `cache.all_config`).
    fn prewarm_git_config_from_common_dir(discovery_path: &Path, common_dir: &Path) {
        let Ok(output) = Cmd::new("git")
            .args(["config", "--list", "-z"])
            .current_dir(common_dir)
            .context(path_to_logging_context(common_dir))
            .run()
        else {
            return;
        };
        if !output.status.success() {
            return;
        }
        let parsed = parse_config_list_z(&output.stdout);
        GIT_CONFIG_PRELOAD.insert(discovery_path.to_path_buf(), parsed);
    }

    /// User-config half of [`Self::prewarm_at`] — loads worktrunk's user
    /// `wt.toml` (and system + env-var layers) and stashes the result in
    /// [`WORKTRUNK_USER_CONFIG_PRELOAD`] for [`Repository::at`] to clone
    /// into per-Repository caches.
    ///
    /// Pure file I/O on `$WORKTRUNK_CONFIG_PATH` / XDG paths — no git, no
    /// `Repository`, no dependence on `discovery_path`. Runs as a sibling
    /// thread to the two git forks so the ~4 ms TOML parse overlaps with
    /// them instead of falling on the alias-dispatch critical path.
    ///
    /// Warnings (parse failures, env-var rejections, validation issues) are
    /// emitted to stderr inline by [`emit_user_config_warnings`], matching
    /// the on-demand path in [`Repository::user_config`]. Prewarm runs in
    /// `main` before alias dispatch, so these warnings emerge before any
    /// command-specific output and before the per-handler
    /// [`Repository::project_config`] reads that surface project-config
    /// warnings.
    ///
    /// Best-effort: if `OnceLock::set` races (a second prewarm reentry, or
    /// a test that already populated the lock) we drop the second value.
    fn prewarm_user_config() {
        let (config, warnings) = UserConfig::load_with_warnings();
        emit_user_config_warnings(&warnings);
        let _ = WORKTRUNK_USER_CONFIG_PRELOAD.set(config);
    }

    /// Resolved user config (global merged with per-project overrides, defaults applied).
    ///
    /// Lazily loads `UserConfig` and resolves it using this repository's project identifier.
    /// Cached for the lifetime of the repository (shared across clones via Arc).
    ///
    /// Falls back to default config if loading fails (e.g., no config file).
    pub fn config(&self) -> &ResolvedConfig {
        self.cache.resolved_config.get_or_init(|| {
            let project_id = self.project_identifier().ok();
            self.user_config().resolved(project_id.as_ref())
        })
    }

    /// Raw user config (as loaded from disk, before project-specific resolution).
    ///
    /// Prefer [`config()`](Self::config) for behavior settings. This is only needed
    /// for operations that require the full `UserConfig` (e.g., path template formatting,
    /// approval state, hook resolution).
    ///
    /// Each config layer (system file, user file, env vars) degrades
    /// independently — a failure in one preserves data from earlier layers.
    /// Issues are surfaced on stderr so they're visible without `RUST_LOG`.
    ///
    /// Typically a memory hit: [`Repository::prewarm`] populates the cache
    /// from `main` before any command runs. Tests and other callers that
    /// bypass prewarm fall through to a fresh `UserConfig::load_with_warnings`
    /// here.
    pub fn user_config(&self) -> &UserConfig {
        self.cache.user_config.get_or_init(|| {
            let (config, warnings) = UserConfig::load_with_warnings();
            emit_user_config_warnings(&warnings);
            config
        })
    }

    /// Resolve the git common directory for a path.
    ///
    /// Always returns a canonicalized absolute path to ensure consistent
    /// comparison with `WorkingTree::git_dir()`.
    ///
    /// Result is cached process-wide in [`GIT_COMMON_DIR_CACHE`] so multiple
    /// `Repository::at()` calls for the same discovery path don't each spawn
    /// `git rev-parse --git-common-dir`.
    fn resolve_git_common_dir(discovery_path: &Path) -> anyhow::Result<PathBuf> {
        if let Some(cached) = GIT_COMMON_DIR_CACHE.get(discovery_path) {
            return Ok(cached.clone());
        }

        // Span attribution for the cold path: the rev-parse subprocess gets
        // its own `[wt-trace] cmd=` record from `Cmd::run`, and this span
        // captures the surrounding canonicalize + cache-insert work too.
        let _span = crate::trace::Span::new("resolve_git_common_dir");

        let args = ["rev-parse", "--git-common-dir"];
        let output = Cmd::new("git")
            .args(args)
            .current_dir(discovery_path)
            .context(path_to_logging_context(discovery_path))
            .run()
            .context("Failed to execute: git rev-parse --git-common-dir")?;

        if !output.status.success() {
            return Err(
                super::error::CommandError::from_failed_output("git", &args, &output).into(),
            );
        }

        let path = super::git_path_from_output(&output.stdout)?;
        // Always canonicalize to resolve symlinks (e.g., /var -> /private/var on macOS)
        let absolute_path = if path.is_relative() {
            discovery_path.join(&path)
        } else {
            path
        };
        let resolved =
            canonicalize(&absolute_path).context("Failed to resolve git common directory")?;
        GIT_COMMON_DIR_CACHE.insert(discovery_path.to_path_buf(), resolved.clone());
        Ok(resolved)
    }

    /// Get the path this repository was discovered from.
    ///
    /// This is primarily for internal use. For worktree operations,
    /// use [`current_worktree()`](Self::current_worktree) or [`worktree_at()`](Self::worktree_at).
    pub fn discovery_path(&self) -> &Path {
        &self.discovery_path
    }

    /// Get a worktree view at this Repository's discovery path.
    ///
    /// This is the primary way to get a [`WorkingTree`] for worktree-specific
    /// operations. For [`Repository::current`] the discovery path is the
    /// process CWD (or `-C` value), so "current" matches its colloquial
    /// meaning. For [`Repository::at`], the discovery path is the path passed
    /// in, and this returns a worktree there rather than at the process CWD —
    /// see #2625 for the bug class that motivated anchoring this to `self`.
    pub fn current_worktree(&self) -> WorkingTree<'_> {
        self.worktree_at(self.discovery_path.clone())
    }

    /// Get a worktree view at a specific path.
    ///
    /// Use this when you need to operate on a worktree other than the current one.
    ///
    /// The path is canonicalized when it exists so that callers passing
    /// equivalent forms (e.g., cwd from JSON vs path from `git worktree list
    /// --porcelain`) hit the same per-worktree cache entries in `RepoCache`.
    /// Falls back to the raw path if canonicalization fails (e.g., path does
    /// not yet exist for a worktree about to be created).
    pub fn worktree_at(&self, path: impl Into<PathBuf>) -> WorkingTree<'_> {
        let raw = path.into();
        let path = canonicalize(&raw).unwrap_or(raw);
        WorkingTree { repo: self, path }
    }

    /// Prime the per-worktree path caches (`WORKTREE_ROOTS` and `GIT_DIRS`)
    /// for every worktree in `worktrees`, from data already in hand.
    ///
    /// `git worktree list` already gives each worktree's top-level path, so
    /// `root()` is just its canonical form, and each worktree's `.git` entry
    /// gives its git dir without a fork. On the `wt list` path this elides the
    /// per-worktree `git rev-parse --show-toplevel` / `--git-dir` subprocesses
    /// (one each per linked worktree, both on the dirty-worktree
    /// `WorkingTreeConflicts` / `GitOperation` critical chain) in favor of
    /// cheap local fs reads — the same facts [`Self::prewarm`] caches for the
    /// discovery worktree, generalized to all of them.
    ///
    /// Seeds via `or_insert`, so an entry the prewarm or a prior call already
    /// resolved is left untouched. A worktree whose git dir can't be derived
    /// cleanly (missing/odd `.git`, un-canonicalizable path) is left for the
    /// `git rev-parse` fallback in [`WorkingTree::git_dir`] — seeding is an
    /// optimization, never a correctness dependency. Prunable worktrees (gone
    /// from disk) are skipped: nothing on disk to read, and their tasks don't
    /// run.
    pub fn prime_worktree_path_caches(&self, worktrees: &[WorktreeInfo]) {
        for wt in worktrees {
            if wt.is_prunable() {
                continue;
            }
            // Key on the canonical path, matching `worktree_at` (and the
            // membership invariant on `WORKTREE_ROOTS`). Skip when the path
            // can't be canonicalized — same guard as `worktree_at`'s callers.
            let Ok(key) = canonicalize(&wt.path) else {
                continue;
            };
            // A worktree's top-level path is its own `root()`.
            WORKTREE_ROOTS.entry(key.clone()).or_insert(key.clone());

            if let Some(git_dir) = Self::git_dir_at(&key) {
                GIT_DIRS.entry(key).or_insert(git_dir);
            }
        }
    }

    /// Read this directory's own `.git`, without a subprocess or walking up
    /// to a parent. A directory is its own Git store; a gitfile points to the
    /// store with `gitdir: <path>`. The returned directory is canonical.
    ///
    /// Reads are deliberately uncached so removal can detect replacement
    /// between gates; `WorkingTree::git_dir` uses a process-wide cache instead.
    /// Read and resolution errors refuse removal; cache priming and main-path
    /// discovery decline entries they cannot resolve.
    fn git_dir_at(dir: &Path) -> Option<PathBuf> {
        let dot_git = dir.join(".git");
        let metadata = std::fs::metadata(&dot_git).ok()?;
        let target = if metadata.is_dir() {
            dot_git
        } else if metadata.is_file() {
            let content = std::fs::read(&dot_git).ok()?;
            let path = super::git_path_from_file(content.strip_prefix(b"gitdir: ")?).ok()?;
            if path.is_relative() {
                dir.join(path)
            } else {
                path
            }
        } else {
            return None;
        };
        let path = canonicalize(target).ok()?;
        std::fs::metadata(&path).ok()?.is_dir().then_some(path)
    }

    /// Get a branch handle for branch-specific operations.
    ///
    /// Use this when you need to query properties of a specific branch.
    pub fn branch(&self, name: &str) -> Branch<'_> {
        Branch {
            repo: self,
            name: name.to_string(),
        }
    }

    // =========================================================================
    // Core repository properties
    // =========================================================================

    /// Get the git common directory (the actual .git directory for the repository).
    ///
    /// For linked worktrees, this returns the shared `.git` directory in the main
    /// worktree, not the per-worktree `.git/worktrees/<name>` directory.
    /// See [`--git-common-dir`][1] for details.
    ///
    /// Always returns an absolute path, resolving any relative paths returned by git.
    /// Result is cached per Repository instance (also used as key for global cache).
    ///
    /// [1]: https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---git-common-dir
    pub fn git_common_dir(&self) -> &Path {
        &self.git_common_dir
    }

    /// Get the epoch timestamp of the last `git fetch`, if available.
    ///
    /// Checks the modification time of `FETCH_HEAD` in the git common directory.
    /// Returns `None` if the file doesn't exist (never fetched) or on any I/O error.
    pub fn last_fetch_epoch(&self) -> Option<u64> {
        let fetch_head = self.git_common_dir().join("FETCH_HEAD");
        let metadata = std::fs::metadata(fetch_head).ok()?;
        let modified = metadata.modified().ok()?;
        modified
            .duration_since(std::time::UNIX_EPOCH)
            .ok()
            .map(|d| d.as_secs())
    }

    /// Get the worktrunk data directory inside the git directory.
    ///
    /// Returns `<git-common-dir>/wt/` (typically `.git/wt/`).
    /// All worktrunk-managed state lives under this single directory.
    pub fn wt_dir(&self) -> PathBuf {
        self.git_common_dir().join("wt")
    }

    /// Get the directory where worktrunk background logs are stored.
    ///
    /// Returns `<git-common-dir>/wt/logs/` (typically `.git/wt/logs/`).
    pub fn wt_logs_dir(&self) -> PathBuf {
        self.wt_dir().join("logs")
    }

    /// Get the directory where worktrees are staged for background deletion.
    ///
    /// Returns `<git-common-dir>/wt/trash/` (typically `.git/wt/trash/`).
    /// Worktrees are renamed here (instant same-filesystem rename) before
    /// being deleted by a background process.
    pub fn wt_trash_dir(&self) -> PathBuf {
        self.wt_dir().join("trash")
    }

    /// The repository root path (the main worktree directory).
    ///
    /// - Normal repositories: the main worktree directory (parent of .git)
    /// - Bare repositories: the bare repository directory itself
    /// - Submodules: the submodule's worktree (e.g., `/parent/sub`, not `/parent/.git/modules/sub`)
    ///
    /// This is the base for template expansion (`{{ repo }}`, `{{ repo_path }}`).
    /// NOT necessarily where established files live — use `primary_worktree()` for that.
    ///
    /// Result is cached in the repository's shared cache (same for all clones).
    ///
    /// # Resolution strategy
    ///
    /// We anchor on `git_common_dir` so that linked worktrees return the
    /// *main* worktree regardless of which worktree we were discovered
    /// from — `git_common_dir` is the stable reference shared across all
    /// worktrees (e.g., `/myapp/.git` whether you're in `/myapp` or
    /// `/myapp.feature`).
    ///
    /// | git_common_dir location    | Signal                     | Resolution                    |
    /// |----------------------------|----------------------------|-------------------------------|
    /// | Bare `.git`                | `core.bare = true`         | `git_common_dir` is the repo  |
    /// | Submodule `.git/modules/X` | `core.worktree` set by git | `rev-parse --show-toplevel`   |
    /// | Separate git dir           | `<common>/gitdir` backlink | `parent(backlink)`            |
    /// | Normal `.git`              | none of the above          | `parent(git_common_dir)`      |
    ///
    /// Submodules need `core.worktree` because their git data lives in the
    /// parent's `.git/modules/` — the `parent(.git)` rule would point at
    /// `.git/modules`, which is wrong. Git writes `core.worktree`
    /// explicitly to compensate.
    ///
    /// We can't read `core.worktree` straight from the bulk config map:
    /// `git config --list -z` merges system/global/local scope, but git
    /// only honors `core.worktree` from **local** config for worktree
    /// discovery. So when the bulk map reports it, we delegate to
    /// `rev-parse --show-toplevel` and let git apply its scope rules; if
    /// the probe fails (non-local value, git ignored it) we fall through
    /// to the normal-repo path. The common case — no `core.worktree`
    /// anywhere — skips the subprocess, which is the point.
    ///
    /// A repository whose git directory lives outside its work tree
    /// (`--separate-git-dir`) has neither signal, and `parent(git_common_dir)`
    /// names the store's parent rather than the work tree. The backlink git
    /// writes there covers it where it exists; see
    /// `separate_git_dir_work_tree` for when that is.
    ///
    /// # Errors
    ///
    /// Returns an error if the bulk config read fails (e.g., git timeout). This
    /// surfaces the failure early rather than caching a potentially wrong path.
    pub fn repo_path(&self) -> anyhow::Result<&Path> {
        self.cache
            .repo_path
            .get_or_try_init(|| {
                if self.is_bare()? {
                    return Ok(self.git_common_dir.clone());
                }

                // `core.worktree` in the bulk map could come from any scope,
                // but git only honors the local one. Let git resolve scope
                // via `rev-parse --show-toplevel` rather than trusting the
                // merged value ourselves.
                if self.config_last("core.worktree")?.is_some()
                    && let Ok(out) = Cmd::new("git")
                        .args(["rev-parse", "--show-toplevel"])
                        .current_dir(&self.git_common_dir)
                        .context(path_to_logging_context(&self.git_common_dir))
                        .run()
                    && out.status.success()
                {
                    return Ok(super::git_path_from_output(&out.stdout)?);
                }

                if let Some(work_tree) = self.separate_git_dir_work_tree() {
                    return Ok(work_tree);
                }

                Ok(self
                    .git_common_dir
                    .parent()
                    .expect("Git directory has no parent")
                    .to_path_buf())
            })
            .map(|p| p.as_path())
    }

    /// The work tree a `--separate-git-dir` repository records in its `gitdir`
    /// backlink, if it has one.
    ///
    /// When the git directory lives outside the work tree, the work tree's
    /// `.git` is a *file* pointing at the store and `parent(git_common_dir)`
    /// names the store's parent — the wrong answer, and the one
    /// `git worktree list` gives too, since git derives its main-worktree
    /// entry by stripping a trailing `/.git` that isn't there (see the
    /// submodule correction in [`Self::list_worktrees`], which this layout
    /// trips the same way).
    ///
    /// Git's own record of the other direction is `<git-common-dir>/gitdir`,
    /// holding the path of the work tree's `.git` file — the same format as a
    /// linked worktree's `.git/worktrees/<name>/gitdir`, down to the relative
    /// form git writes under `worktree.useRelativePaths`, so
    /// [`registration_worktree_path`] reads it. Only
    /// `git worktree repair` writes it; `git init --separate-git-dir` and
    /// `git clone --separate-git-dir` leave the store with no backlink, so a
    /// repository that has never been repaired records its work tree nowhere
    /// and still falls through to `parent(git_common_dir)`. Running
    /// `git worktree repair` from the work tree is what materializes it.
    ///
    /// The backlink is one-way, so it is confirmed rather than trusted:
    /// [`Self::git_dir_at`] reads the `.git` entry sitting at the work tree it
    /// names, and only a work tree that points back at this common dir is
    /// accepted. A backlink left behind by a work tree that has since moved,
    /// been deleted, or been re-pointed at another repository resolves to
    /// something else and falls through to `parent(git_common_dir)` — the
    /// same answer as before, rather than a path that no longer holds this
    /// repository. That round trip is also why a normal repository or a
    /// submodule can't misfire here on a stray `gitdir` file.
    fn separate_git_dir_work_tree(&self) -> Option<PathBuf> {
        let work_tree = registration_worktree_path(&self.git_common_dir).ok()?;
        (Self::git_dir_at(&work_tree)? == self.git_common_dir).then_some(work_tree)
    }

    /// Access the bulk git config map, populating on first call.
    ///
    /// Reads every key from the merged git config (system + global + repo)
    /// via a single `git config --list -z` subprocess. The NUL-delimited
    /// `-z` format handles values containing newlines or `=`. Populated
    /// lazily on first access; every config-reading accessor consults this
    /// map rather than spawning its own subprocess.
    ///
    /// Run from `git_common_dir` so linked worktrees of bare repos correctly
    /// read the bare repo's config.
    pub(super) fn all_config(
        &self,
    ) -> anyhow::Result<&std::sync::RwLock<indexmap::IndexMap<String, Vec<String>>>> {
        self.cache.all_config.get_or_try_init(|| {
            let args = ["config", "--list", "-z"];
            let output = Cmd::new("git")
                .args(args)
                .current_dir(&self.git_common_dir)
                .context(path_to_logging_context(&self.git_common_dir))
                .run()
                .context("failed to read git config")?;
            if !output.status.success() {
                return Err(
                    super::error::CommandError::from_failed_output("git", &args, &output).into(),
                );
            }
            Ok(std::sync::RwLock::new(parse_config_list_z(&output.stdout)))
        })
    }

    /// Read the last value for a config key from the bulk map.
    ///
    /// Convenience wrapper for the common "single-value" accessor pattern.
    /// Git treats the last value as authoritative when a key is set multiple
    /// times; callers that need multivars read through `all_config()` directly.
    ///
    /// Keys are normalized to git's canonical form (section and variable
    /// names lowercased, subsection preserved) so callers may pass the
    /// mixed-case form from git docs (e.g., `init.defaultBranch`) without
    /// missing the lookup.
    pub(super) fn config_last(&self, key: &str) -> anyhow::Result<Option<String>> {
        let canonical = canonical_config_key(key);
        let guard = self.all_config()?.read().unwrap();
        Ok(guard.get(&canonical).and_then(|v| v.last().cloned()))
    }

    /// Read a git-bool config value, defaulting to `false` when the key is
    /// unset or absent.
    ///
    /// Returns `Err` only when the bulk config read itself fails. A missing
    /// key is `Ok(false)`, matching git's own behaviour for unset booleans.
    pub(super) fn config_bool(&self, key: &str) -> anyhow::Result<bool> {
        Ok(self
            .config_last(key)?
            .as_deref()
            .map(parse_git_bool)
            .unwrap_or(false))
    }

    /// Check if this is a bare repository (no working tree).
    ///
    /// Bare repositories have no main worktree — all worktrees are linked
    /// worktrees at templated paths, including the default branch.
    ///
    /// Reads `core.bare` from the bulk config map rather than using `git
    /// rev-parse --is-bare-repository`. The rev-parse approach is unreliable
    /// when run from inside a `.git` directory — when `core.bare` is unset,
    /// git infers based on directory context, and from inside `.git/` there's
    /// no working tree so it returns `true` even for normal repos. This
    /// affects repos where `core.bare` was never written (e.g., repos cloned
    /// by Eclipse/EGit). Reading the config value directly avoids this false
    /// positive.
    ///
    /// When `core.bare` is unset, defaults to non-bare — matching libgit2's
    /// behavior.
    ///
    /// See <https://github.com/max-sixty/worktrunk/issues/1939>.
    pub fn is_bare(&self) -> anyhow::Result<bool> {
        self.config_bool("core.bare")
    }

    /// Whether `commit.gpgSign` asks for signed commits.
    ///
    /// `git commit` and `git merge` honor it; `git commit-tree` ignores it, so
    /// a commit meant to match what porcelain would record passes `-S` itself.
    /// Asked of git from this worktree rather than read from the cached config
    /// map, which is read from the common dir and so misses worktree-scoped
    /// config.
    pub fn signs_commits(&self) -> anyhow::Result<bool> {
        let args = ["config", "--type=bool", "--get", "commit.gpgSign"];
        let output = self.run_command_output(&args)?;
        match output.status.code() {
            Some(0) => Ok(String::from_utf8_lossy(&output.stdout).trim() == "true"),
            // Exit 1: the key is unset.
            Some(1) => Ok(false),
            _ => Err(super::error::CommandError::from_failed_output("git", &args, &output).into()),
        }
    }

    /// Get the sparse checkout paths for this repository.
    ///
    /// Returns the list of paths from `git sparse-checkout list`. For non-sparse
    /// repos, returns an empty slice (the command exits with code 128).
    ///
    /// Assumes cone mode (the git default). Cached using `discovery_path` —
    /// scoped to the worktree the user is running from, not per-listed-worktree.
    pub fn sparse_checkout_paths(&self) -> &[String] {
        self.cache.sparse_checkout_paths.get_or_init(|| {
            let output = match self.run_command_output(&["sparse-checkout", "list"]) {
                Ok(out) => out,
                Err(_) => return Vec::new(),
            };

            if output.status.success() {
                let stdout = String::from_utf8_lossy(&output.stdout);
                stdout.lines().map(String::from).collect()
            } else {
                // Exit 128 = not a sparse checkout (expected, not an error)
                Vec::new()
            }
        })
    }

    /// Check if git's builtin fsmonitor daemon is enabled.
    ///
    /// Returns true for any git-bool truthy value (`true/1/yes/on`), which
    /// matches how git itself routes the bool-or-string `core.fsmonitor`
    /// config to the builtin daemon. Returns false for Watchman hook paths,
    /// disabled, or unset.
    pub fn is_builtin_fsmonitor_enabled(&self) -> bool {
        self.config_bool("core.fsmonitor").unwrap_or(false)
    }

    /// Start the fsmonitor daemon at a worktree path.
    ///
    /// Idempotent — if the daemon is already running, this is a no-op.
    /// Used to avoid auto-start races when running many parallel git commands.
    ///
    /// A running daemon is detected in-process first, the way `git
    /// fsmonitor--daemon start` itself checks before refusing with "already
    /// running": connect to `<git-dir>/fsmonitor--daemon.ipc` and close. That
    /// skips a ~20ms fork per worktree in the steady state, where every daemon
    /// is already up. Any failure to connect (no daemon, stale socket, a path
    /// too long for `sun_path`, an unresolvable git dir) falls through to the
    /// fork, which starts the daemon or reports it running.
    ///
    /// Spawns with null stdio instead of `Cmd::run()` to avoid
    /// pipe inheritance: the daemon process (`git fsmonitor--daemon run --detach`)
    /// inherits pipe file descriptors from its parent, keeping them open
    /// indefinitely. `read_to_end()` in `Command::output()` then blocks forever
    /// waiting for EOF that never comes.
    pub fn start_fsmonitor_daemon_at(&self, path: &Path) {
        #[cfg(unix)]
        if let Ok(git_dir) = self.worktree_at(path).git_dir()
            && socket2::SockAddr::unix(git_dir.join(super::fsmonitor::IPC_SOCKET_NAME))
                .and_then(|address| {
                    crate::shell_exec::stream_socket(socket2::Domain::UNIX)?.connect(&address)
                })
                .is_ok()
        {
            return;
        }
        let context = path_to_logging_context(path);
        let cmd_str = "git fsmonitor--daemon start";
        tracing::debug!(cmd = cmd_str, context = %context, "$ {cmd_str} [{context}]");
        let mut cmd = std::process::Command::new("git");
        cmd.args(["fsmonitor--daemon", "start"])
            .current_dir(path)
            .stdin(Stdio::null())
            .stdout(Stdio::null())
            .stderr(Stdio::null());
        // The one production git spawn that bypasses `Cmd` (see the daemon
        // rationale above), so it re-applies the test floor by hand.
        crate::shell_exec::apply_hermetic_test_env(&mut cmd);
        crate::shell_exec::scrub_directive_env_vars(&mut cmd);
        // Trace the daemon launch so it's attributed in the timeline rather than
        // appearing as a gap on the switch hot path. Wait without captured
        // pipes (unlike `Cmd::run`) — see the daemon rationale above.
        let mut trace = crate::trace::CommandTrace::new(Some(&context), cmd_str);
        let result = crate::shell_exec::spawn(&mut cmd).and_then(|mut child| child.wait());
        match result {
            Ok(status) => {
                trace.complete(status.success());
                if !status.success() {
                    tracing::debug!(status = %status, "fsmonitor daemon start exited {status} (usually fine)");
                }
            }
            Err(e) => {
                trace.fail(&e);
                tracing::debug!(error = %crate::git::error_chain_message(&e), "fsmonitor daemon start failed (usually fine)");
            }
        }
    }

    /// The git operation the worktree at this repository's discovery path is
    /// partway through, if any. See [`WorkingTree::operation_in_progress`].
    pub fn operation_in_progress(&self) -> anyhow::Result<Option<InProgressOperation>> {
        self.worktree_at(self.discovery_path())
            .operation_in_progress()
    }

    /// Fail when the worktree is already partway through a git operation.
    ///
    /// A precondition for every command that rewrites or moves commits:
    /// `wt step rebase`, `wt step squash`, `wt step push`, and `wt merge`.
    /// Mid-rebase, HEAD is detached on a linear extension of the target, so
    /// `is_rebased_onto` — and every ancestry check like it, including the
    /// push's fast-forward check — reads as "already up to date"; without this
    /// gate a caller reports success over a tree that still holds conflict
    /// markers, or moves the target branch onto one. The other states are gated
    /// for the same reason rather than their own symptom: an operation started
    /// from any of them either compounds the half-finished one or dies inside
    /// git with its own plumbing error, and neither tells the user what to do
    /// next.
    ///
    /// Unresolved conflicts are a separate question, and this is the wrong
    /// place to ask it: a conflicted `git stash pop` leaves an unmerged index
    /// with no state file for this check to read. The commands that stage on
    /// the user's behalf ask the index instead, via
    /// [`WorkingTree::ensure_no_unmerged_paths`].
    ///
    /// The refusal names no operation, so nothing here has to track what git
    /// calls each state or how to leave it; `git status` answers both.
    pub fn ensure_no_operation_in_progress(&self, action: &str) -> anyhow::Result<()> {
        match self.operation_in_progress()? {
            Some(_) => Err(crate::git::GitError::OperationInProgress {
                action: action.to_string(),
                branch: None,
            }
            .into()),
            None => Ok(()),
        }
    }

    // =========================================================================
    // Command execution
    // =========================================================================

    /// Get a short display name for this repository, used in logging context.
    ///
    /// Returns "." for the current directory, or the directory name otherwise.
    fn logging_context(&self) -> String {
        path_to_logging_context(&self.discovery_path)
    }

    /// Run a git command in this repository's context.
    ///
    /// Executes the git command with this repository's discovery path as the working directory.
    /// For repo-wide operations, any path within the repo works.
    ///
    /// # Passing refs
    ///
    /// A ref that starts with `-` (e.g. a branch literally named `-foo`,
    /// which `git update-ref refs/heads/-foo HEAD` will write) is parsed as a
    /// flag. When the ref's value isn't provably safe — a SHA, a
    /// `refs/heads/{}` wrap, a hardcoded `HEAD` — put `--end-of-options`
    /// before it, *after* every other flag (everything following becomes
    /// positional, so `git log` rejects later flags). For `git rev-parse`,
    /// use `--verify --end-of-options`: plain `--end-of-options` makes
    /// rev-parse echo the literal marker to stdout ahead of the SHA, and
    /// `--verify` forces single-revision strict mode — so it can't cover the
    /// two-ref `rev-parse <a> <b>` form, which stays unguarded.
    ///
    /// # Examples
    /// ```no_run
    /// use worktrunk::git::Repository;
    ///
    /// let repo = Repository::current()?;
    /// let branches = repo.run_command(&["branch", "--list"])?;
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn run_command(&self, args: &[impl AsRef<OsStr>]) -> anyhow::Result<String> {
        self.run_command_bounded(args, None)
    }

    /// [`run_command`](Self::run_command) with an optional wall-clock bound.
    ///
    /// A child still running when `timeout` expires is killed and the call
    /// fails with [`std::io::ErrorKind::TimedOut`].
    ///
    /// Local git commands pass `None`: they finish or fail on their own, so a
    /// bound would only turn machine load into a spurious failure. The bound
    /// is for the one git command in worktrunk that can reach the wire —
    /// `ls-remote` in [`default_branch`](Self::default_branch), where nothing
    /// else limits how long an unreachable host takes to not answer.
    pub(super) fn run_command_bounded(
        &self,
        args: &[impl AsRef<OsStr>],
        timeout: Option<std::time::Duration>,
    ) -> anyhow::Result<String> {
        Ok(String::from_utf8_lossy(&self.run_command_bytes_bounded(args, timeout)?).into_owned())
    }

    /// Run a git command and return stdout without decoding paths.
    pub fn run_command_bytes(&self, args: &[impl AsRef<OsStr>]) -> anyhow::Result<Vec<u8>> {
        self.run_command_bytes_bounded(args, None)
    }

    fn run_command_bytes_bounded(
        &self,
        args: &[impl AsRef<OsStr>],
        timeout: Option<std::time::Duration>,
    ) -> anyhow::Result<Vec<u8>> {
        let mut cmd = self.with_object_store_env(
            Cmd::new("git")
                .args(args)
                .current_dir(&self.discovery_path)
                .context(self.logging_context()),
        );
        if let Some(timeout) = timeout {
            cmd = cmd.timeout(timeout);
        }
        let output = cmd.run()?;

        if !output.status.success() {
            return Err(
                super::error::CommandError::from_failed_output("git", args, &output).into(),
            );
        }

        Ok(output.stdout)
    }

    /// Run a Git predicate: status 0 is true, 1 is false, and other statuses fail.
    ///
    /// Use for commands with this exit-code contract, such as
    /// `git merge-base --is-ancestor` and `git rev-parse --verify --quiet`.
    /// A failed query must not be treated or cached as a negative answer.
    ///
    /// # Examples
    /// ```no_run
    /// use worktrunk::git::Repository;
    ///
    /// let repo = Repository::current()?;
    /// let merged = repo.run_command_check(&["merge-base", "--is-ancestor", "feature", "main"])?;
    /// # Ok::<(), anyhow::Error>(())
    /// ```
    pub fn run_command_check(&self, args: &[&str]) -> anyhow::Result<bool> {
        let output = self.run_command_output(args)?;
        match output.status.code() {
            Some(0) => Ok(true),
            Some(1) => Ok(false),
            _ => Err(CommandError::from_failed_output("git", args, &output).into()),
        }
    }

    /// Abbreviate a commit SHA for display, honoring `core.abbrev` and
    /// auto-extending for ambiguous prefixes.
    ///
    /// Wraps `git rev-parse --short <sha>`. Use this anywhere a short SHA is
    /// shown to the user or passed to a hook template — never slice
    /// `&sha[..7]` directly, since 7 chars regularly collides in large repos
    /// and ignores the user's `core.abbrev` setting.
    ///
    /// For batches (e.g., abbreviating many worktree heads at once), prefer
    /// folding `%h` into an existing `git log --format` call rather than
    /// looping this helper. See [`commit_details_many`](Self::commit_details_many).
    /// Where that batch doesn't fit — the objects aren't local, or one bad ref
    /// mustn't cost the rest — abbreviate to [`abbrev_len`](Self::abbrev_len).
    pub fn short_sha(&self, sha: &str) -> anyhow::Result<String> {
        Ok(self
            .run_command(&["rev-parse", "--short", sha])?
            .trim()
            .to_string())
    }

    /// How many characters git abbreviates a SHA to in this repo — `core.abbrev`,
    /// or the width git auto-scales from the object count. Resolved once per
    /// repo and shared by every clone, so a caller pays one `git rev-parse` no
    /// matter how many SHAs it goes on to abbreviate.
    ///
    /// This is the width for **a list of SHAs**; [`short_sha`](Self::short_sha)
    /// is the answer for one. `git rev-parse --short` takes a single revision,
    /// so a list has no batched form, and looping it is a fork per SHA — the
    /// trade this exists to avoid. `%h` folded into an existing `git log` is
    /// better still where it fits ([`commit_details_many`](Self::commit_details_many)),
    /// but it needs the objects present and refuses the whole batch on one bad
    /// ref, so it can't serve a list of forge-named commits or a cache of
    /// historical heads.
    ///
    /// What that costs against `short_sha` is disambiguation: git extends a
    /// prefix that collides with another object, and a plain width can't. Absent
    /// objects have nothing to collide with, and a live collision at this width
    /// is rare enough that a display column can wear it.
    ///
    /// Probed with `HEAD` so the length matches the repo's object format (a
    /// SHA-256 repo abbreviates from 64 hex digits, and a literal SHA-1-shaped
    /// probe is not even a valid revision there) — a HEAD whose own prefix is
    /// ambiguous therefore reports a character or two over the base width, which
    /// costs a caller nothing but a slightly longer SHA. Falls back to 7 — git's
    /// default auto-abbreviation length, and what it reports in an objectless
    /// repo — for the one failure a working repo reaches, an unborn HEAD.
    pub fn abbrev_len(&self) -> usize {
        *self.cache.abbrev_len.get_or_init(|| {
            self.short_sha("HEAD")
                .map_or(7, |short| short.chars().count())
        })
    }

    /// Delay before showing progress output for slow operations.
    /// See .claude/rules/cli-output-formatting.md: "Progress messages apply only to slow operations (>400ms)"
    pub const SLOW_OPERATION_DELAY_MS: i64 = 400;

    /// Run a git command with delayed output streaming.
    ///
    /// Thin wrapper over [`Cmd::delayed_stream`](crate::shell_exec::Cmd::delayed_stream):
    /// buffers output initially, then streams to stderr if the command takes
    /// longer than `delay_ms` (quiet for fast operations, progress for slow
    /// ones like `worktree add` on large repos). Routing through `Cmd` is what
    /// gives the command its `[wt-trace]` record and directive scrubbing — see
    /// that method for the full contract.
    pub fn run_command_delayed_stream(
        &self,
        args: &[&str],
        delay_ms: i64,
        progress_message: Option<String>,
    ) -> anyhow::Result<()> {
        Cmd::new("git")
            .args(args.iter().copied())
            .current_dir(&self.discovery_path)
            .context(self.logging_context())
            .delayed_stream(delay_ms, progress_message)
    }

    /// Run a git command and return the raw Output (for inspecting exit codes).
    ///
    /// Use this when exit codes have semantic meaning beyond success/failure.
    /// For most cases, prefer `run_command` (returns stdout) or `run_command_check` (returns bool).
    pub(super) fn run_command_output(&self, args: &[&str]) -> anyhow::Result<std::process::Output> {
        self.with_object_store_env(
            Cmd::new("git")
                .args(args.iter().copied())
                .current_dir(&self.discovery_path)
                .context(self.logging_context()),
        )
        .run()
        .with_context(|| format!("Failed to execute: git {}", args.join(" ")))
    }

    /// Extract structured failure info from a command-runner error.
    ///
    /// Returns `(output, Some(FailedCommand))` when the chain carries
    /// either a [`StreamCommandError`](crate::shell_exec::StreamCommandError)
    /// (from `run_command_delayed_stream`) or a [`super::error::CommandError`]
    /// (from `run_command` / `WorkingTree::run_command`). Falls back to
    /// `(error_string, None)` for other error types (e.g., spawn failures).
    pub fn extract_failed_command(
        err: &anyhow::Error,
    ) -> (String, Option<super::error::FailedCommand>) {
        if let Some(e) = err.downcast_ref::<crate::shell_exec::StreamCommandError>() {
            return (
                e.output.clone(),
                Some(super::error::FailedCommand {
                    command: e.command.clone(),
                    exit_info: e.exit_info(),
                }),
            );
        }
        if let Some(cmd_err) = CommandError::find_in(err) {
            let exit_info =
                super::error::process_exit_description(cmd_err.exit_code, cmd_err.signal);
            return (
                cmd_err.combined_output(),
                Some(super::error::FailedCommand {
                    command: cmd_err.command_string(),
                    exit_info,
                }),
            );
        }
        (err.display_message(), None)
    }
}

/// Normalize a git config key to its canonical form.
///
/// Git section and variable names are case-insensitive; subsection names
/// (the middle parts of 3+-part keys) preserve case. `git config --list`
/// emits the canonical form — so lookups against the parsed map must
/// normalize the same way.
///
/// - 1 or 2 parts (`section` or `section.variable`): lowercase the whole thing.
/// - 3+ parts (`section.subsection….variable`): lowercase first and last parts,
///   preserve the middle.
pub(super) fn canonical_config_key(key: &str) -> String {
    let parts: Vec<&str> = key.split('.').collect();
    match parts.len() {
        0 | 1 => key.to_ascii_lowercase(),
        2 => key.to_ascii_lowercase(),
        _ => {
            let (first, rest) = parts.split_first().unwrap();
            let (last, middle) = rest.split_last().unwrap();
            let mut out = String::with_capacity(key.len());
            out.push_str(&first.to_ascii_lowercase());
            for part in middle {
                out.push('.');
                out.push_str(part);
            }
            out.push('.');
            out.push_str(&last.to_ascii_lowercase());
            out
        }
    }
}

/// True when `extensions.worktreeConfig = true` appears in a parsed config map.
///
/// When this extension is enabled, per-worktree config lives in separate
/// `config.worktree` files — the main worktree's at `.git/config.worktree`,
/// linked worktrees' at `.git/worktrees/<name>/config.worktree`. From a
/// linked worktree, `git config --list` does not merge the main worktree's
/// `config.worktree`, so a config read taken there is missing any value the
/// main worktree set per-worktree (e.g., `core.bare`). [`prewarm_git_config`]
/// uses this to detect and skip the preload in that layout. See [#2779].
///
/// Git emits config keys in lowercased canonical form, so the lookup matches
/// directly without going through [`canonical_config_key`].
///
/// [`prewarm_git_config`]: Repository::prewarm_git_config
/// [#2779]: https://github.com/max-sixty/worktrunk/issues/2779
fn worktree_config_enabled(parsed: &indexmap::IndexMap<String, Vec<String>>) -> bool {
    parsed
        .get("extensions.worktreeconfig")
        .and_then(|v| v.last())
        .map(|v| parse_git_bool(v))
        .unwrap_or(false)
}

/// Parse the output of `git config --list -z`.
///
/// Format: each entry is `key\nvalue\0`. An explicitly empty value
/// (`key = ""`) keeps the newline and parses as `key -> ""`. A key written
/// with no value at all is emitted as bare `key\0`; git reads that as boolean
/// true, so it parses as `key -> "true"`.
///
/// Returns a map from canonical key (as git emits it) to the list of
/// values, preserving order (matches git's own multivar semantics where
/// the last value wins).
fn parse_config_list_z(stdout: &[u8]) -> indexmap::IndexMap<String, Vec<String>> {
    let mut map: indexmap::IndexMap<String, Vec<String>> = indexmap::IndexMap::new();
    for entry in stdout.split(|&b| b == 0) {
        if entry.is_empty() {
            continue;
        }
        let text = String::from_utf8_lossy(entry);
        let (key, value) = match text.split_once('\n') {
            Some((k, v)) => (k, v),
            // A key with no value is git's implicit boolean true.
            None => (text.as_ref(), "true"),
        };
        map.entry(key.to_string())
            .or_default()
            .push(value.to_string());
    }
    map
}

/// Emit `UserConfig::load_with_warnings` warnings to stderr.
///
/// Shared by [`Repository::prewarm_user_config`] (preload thread on `main`)
/// and [`Repository::user_config`] (on-demand path for tests and callers
/// that bypass prewarm). Both routes go through the same formatting so the
/// stderr output is byte-identical regardless of which path runs.
fn emit_user_config_warnings(warnings: &[LoadError]) {
    for warning in warnings {
        emit_config_load_warning(warning);
    }
}

/// Render one [`LoadError`] as a `▲` warning (plus a gutter for the parser's
/// own output, where there is one).
///
/// Also the project-config path: [`Repository::warn_if_project_config_unloadable`]
/// feeds the `LoadError::File` that `ProjectConfig::load` returns through
/// here, so `▲ Project config @ … failed to parse, skipping` and its user
/// counterpart are one line of code rather than two that can drift.
fn emit_config_load_warning(warning: &LoadError) {
    match warning {
        LoadError::File(error) => {
            crate::styling::eprintln!("{}", error.render_warning());
        }
        LoadError::Env { err, vars } => {
            let var_list: Vec<_> = vars
                .iter()
                .map(|(name, value)| format!("{name}={value}"))
                .collect();
            crate::styling::eprintln!(
                "{}",
                crate::styling::warning_message(format!(
                    "Ignoring env var overrides: {}",
                    var_list.join(", ")
                ))
            );
            crate::styling::eprintln!("{}", crate::styling::format_with_gutter(err.trim(), None));
        }
        LoadError::CliOverride { err, overrides } => {
            crate::styling::eprintln!(
                "{}",
                crate::styling::warning_message(format!(
                    "Ignoring --config-set overrides: {}",
                    overrides.join(", ")
                ))
            );
            crate::styling::eprintln!("{}", crate::styling::format_with_gutter(err.trim(), None));
        }
        LoadError::Validation(err) => {
            crate::styling::eprintln!(
                "{}",
                crate::styling::warning_message(format!("Config validation warning: {err}"))
            );
        }
    }
}

/// Parse a git boolean config value.
///
/// Accepts the forms `git config --type=bool` normalizes: `true/1/yes/on`
/// (case-insensitive) → `true`; anything else → `false`.
fn parse_git_bool(value: &str) -> bool {
    matches!(
        value.trim().to_ascii_lowercase().as_str(),
        "true" | "1" | "yes" | "on"
    )
}

#[cfg(test)]
mod tests;