Skip to content

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

7.3 KB
Raw Blame
//! Branch - a handle for branch-specific git operations.

use super::Repository;
use crate::git::{CommandError, GitError};

/// Whether `refs/heads/<name>` is a well-formed ref, which is what a branch is.
///
/// A worktree selector is tried as a branch first and as a path second (see
/// [`Repository::resolve_worktree`](super::Repository::resolve_worktree)), so
/// when neither matches, the error has to pick which of the two the user meant.
/// This answers it: a name git could never put under `refs/heads/` — an
/// absolute path, `~/…`, `./…`, a Windows drive letter — was only ever a path,
/// and reporting it as a missing branch sends the user to `wt list --branches`
/// for something that would never appear there.
///
/// The rules are git's own, as `git check-ref-format refs/heads/<name>` applies
/// them; `branch_name_matches_git_check_ref_format` pins each one against that
/// command. In-process because it runs wherever a selector fails to resolve,
/// where a subprocess would buy nothing.
pub fn is_valid_branch_name(name: &str) -> bool {
    if name.is_empty() || name.ends_with('.') || name.contains("..") || name.contains("@{") {
        return false;
    }
    if name.chars().any(|c| {
        c.is_ascii_control() || matches!(c, ' ' | '~' | '^' | ':' | '?' | '*' | '[' | '\\')
    }) {
        return false;
    }
    // An empty component covers a leading `/`, a trailing `/`, and `//`.
    name.split('/')
        .all(|part| !part.is_empty() && !part.starts_with('.') && !part.ends_with(".lock"))
}

/// A handle for running git commands on a specific branch.
///
/// This type holds a reference to [`Repository`] and a branch name.
/// All branch-specific operations (like `exists`, `upstream`) are on this type.
///
/// # Examples
///
/// ```no_run
/// use worktrunk::git::Repository;
///
/// let repo = Repository::current()?;
/// let branch = repo.branch("feature");
///
/// // Branch-specific operations
/// let _ = branch.exists_locally();
/// let _ = branch.upstream();
/// let _ = branch.remotes();
///
/// # Ok::<(), anyhow::Error>(())
/// ```
#[derive(Debug)]
#[must_use]
pub struct Branch<'a> {
    pub(super) repo: &'a Repository,
    pub(super) name: String,
}

impl<'a> Branch<'a> {
    /// Get the branch name.
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Require a literal name Git accepts when creating a branch.
    ///
    /// Branch creation has stricter rules than ref syntax (for example, HEAD
    /// is reserved). Git owns these rules; selector resolution continues to use
    /// [`is_valid_branch_name`] for refs that may already exist.
    pub fn require_valid_name(&self) -> anyhow::Result<()> {
        let args = ["check-ref-format", "--branch", self.name()];
        let output = self.repo.run_command_output(&args)?;
        match output.status.code() {
            // Git expands checkout-history expressions and echoes the result.
            // Creation must not silently choose a different branch name.
            Some(0) if output.stdout.trim_ascii_end() == self.name.as_bytes() => Ok(()),
            Some(0 | 128) => Err(GitError::InvalidBranchName {
                name: self.name.clone(),
            }
            .into()),
            _ => Err(CommandError::from_failed_output("git", &args, &output).into()),
        }
    }

    /// Check if this branch exists locally.
    pub fn exists_locally(&self) -> anyhow::Result<bool> {
        self.repo.ref_exists(&format!("refs/heads/{}", self.name))
    }

    /// Check if this branch exists (local or remote).
    ///
    /// Checks all remotes, matching git's default behavior for `git checkout`.
    pub fn exists(&self) -> anyhow::Result<bool> {
        // Try local branch first
        if self.exists_locally()? {
            return Ok(true);
        }

        // Check if any remote has this branch
        Ok(!self.remotes()?.is_empty())
    }

    /// Find which remotes have this branch.
    ///
    /// Returns a list of remote names that have this branch (e.g., `["origin"]`).
    /// Returns an empty list if no remotes have this branch.
    ///
    /// Filters the repository's remote-branch inventory (see
    /// [`Repository::remote_branches`]); the first call within a command
    /// triggers the `refs/remotes/` scan that populates the inventory.
    ///
    /// [`Repository::remote_branches`]: super::Repository::remote_branches
    pub fn remotes(&self) -> anyhow::Result<Vec<String>> {
        Ok(self
            .repo
            .remote_branches()?
            .iter()
            .filter(|r| r.local_name == self.name)
            .map(|r| r.remote_name.clone())
            .collect())
    }

    /// Get the upstream tracking branch for this branch.
    ///
    /// Reads from the repository's local-branch inventory (see
    /// [`Repository::local_branches`]). The first call within a command
    /// triggers the `refs/heads/` scan that populates the inventory;
    /// subsequent lookups are O(1). Returns `None` when no upstream is
    /// configured, when no local branch by this name exists, or when the
    /// configured upstream is gone from its remote (git's `[gone]` track
    /// state).
    ///
    /// [`Repository::local_branches`]: super::Repository::local_branches
    pub fn upstream(&self) -> anyhow::Result<Option<String>> {
        Ok(self
            .repo
            .local_branch(&self.name)?
            .and_then(|b| b.upstream_short.clone()))
    }

    /// Configured upstream remote, as reported by git's local-branch inventory.
    /// Local tracking (`.`) has no remote.
    pub fn upstream_remote(&self) -> anyhow::Result<Option<String>> {
        Ok(self
            .repo
            .local_branch(&self.name)?
            .and_then(|b| b.upstream_remote.clone()))
    }

    /// Where this branch pushes: a remote name, or a URL when
    /// `branch.<name>.pushRemote` is one (`gh pr checkout` sets that for a
    /// fork's PR). Resolves `pushRemote` → `remote.pushDefault` → the tracking
    /// remote, as `git push` does.
    ///
    /// Reads `%(push:remotename)` from the local-branch inventory (see
    /// [`Repository::local_branches`]), so it forks nothing after the first
    /// scan. Unlike `@{push}`, that field doesn't fail when the push remote is
    /// a URL. Returns `None` when no push remote is configured or no local
    /// branch has this name.
    ///
    /// [`Repository::local_branches`]: super::Repository::local_branches
    pub fn push_remote(&self) -> Option<String> {
        self.repo
            .local_branch(&self.name)
            .ok()
            .flatten()
            .and_then(|b| b.push_remote.clone())
    }

    /// Get the URL of the remote where this branch would be pushed.
    ///
    /// A remote name goes through `effective_remote_url` to apply
    /// `url.insteadOf` rewrites; a URL push remote is returned as is.
    /// Returns `None` if no push remote is configured or the remote has no URL.
    pub fn push_remote_url(&self) -> Option<String> {
        let push_remote = self.push_remote()?;
        if is_url(&push_remote) {
            Some(push_remote)
        } else {
            self.repo.effective_remote_url(&push_remote)
        }
    }
}

/// Whether a push remote from `%(push:remotename)` is a URL rather than a
/// remote name.
fn is_url(push_remote: &str) -> bool {
    push_remote.contains("://") || push_remote.starts_with("git@")
}