Hmbown/CodeWhale · error · anyhow::Error

worktree branch must not be empty

Error message

worktree branch must not be empty

What it means

provision_worktree validates its spec before touching git: a branch name that is empty after trimming bails immediately (the repo-root existence check follows). The branch becomes a real `git worktree add` argument and a ref name, and git rejects empty/whitespace branch names with worse diagnostics, so the guard fails fast with an actionable message.

Source

Thrown at crates/lane/src/worktree.rs:33

    pub repo_root: PathBuf,
    /// Branch to create (from `base_ref`).
    pub branch: String,
    /// Directory for the new worktree (created by `git worktree add`).
    pub path: PathBuf,
    /// Base ref to branch from (default `HEAD`).
    pub base_ref: Option<String>,
}

#[derive(Debug, Clone)]
pub struct ProvisionedWorktree {
    pub path: PathBuf,
    pub branch: String,
}

/// Create a git worktree + branch for a lane.
pub fn provision_worktree(spec: &WorktreeProvision) -> Result<ProvisionedWorktree> {
    if spec.branch.trim().is_empty() {
        bail!("worktree branch must not be empty");
    }
    if !spec.repo_root.exists() {
        bail!("repo root does not exist: {}", spec.repo_root.display());
    }
    if let Some(parent) = spec.path.parent() {
        fs::create_dir_all(parent)
            .with_context(|| format!("create worktree parent {}", parent.display()))?;
    }
    let base = spec.base_ref.as_deref().unwrap_or("HEAD");
    // Capture git output instead of inheriting the caller's terminal. Runtime
    // callers include the raw-mode TUI launch screen, where even one inherited
    // progress/error line corrupts the alternate-screen buffer.
    let output = Command::new("git")
        .current_dir(&spec.repo_root)
        .args([
            "worktree",
            "add",
            "-b",

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Supply a real branch name (e.g. lanes/<lane-id>) in the WorktreeProvision spec
2. Default the branch when the caller has none: format!("lane-{lane_id}")
3. Validate trimmed non-emptiness where you build the spec so failure surfaces at the source

Example fix

// before
let spec = WorktreeProvision { branch: title.clone(), .. }; // title may be blank

// after
let branch = if title.trim().is_empty() {
    format!("lane-{lane_id}")
} else {
    title.trim().to_string()
};
let spec = WorktreeProvision { branch, .. };

anyhow::ensure!(!spec.branch.trim().is_empty(), "worktree branch must not be empty");

fn branch_name_valid(branch: &str) -> bool {
    !branch.trim().is_empty() && !branch.contains("..") && !branch.starts_with('-')
}

When it happens

Trigger: Calling provision_worktree with spec.branch = "", " ", or a value that only looks present (e.g. built from an empty option or an id that failed to generate). Whitespace-only names are caught because the check uses trim().

Common situations: Branch names derived from user input or lane titles that were blank; formatting bugs producing empty strings (format! with missing args); Option fields defaulted to empty instead of None; copy-paste configs with an uncommented empty branch key.

Related errors

• tmux runtime requires a non-empty command
• inline runtime requires a non-empty command
• --worktree-repo and --branch must be provided together
• project workspace path cannot be empty
• terminal lane transition requires a terminal status

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/c06ef52273452f97. Report an issue: GitHub.