nikivdev/code · error

Specify branch with: f upstream setup --branch <branch-name>

Error message

Specify branch with: f upstream setup --branch <branch-name>

What it means

`setup_upstream_internal` (src/upstream.rs:~195) tries to auto-detect which branch of the `upstream` remote to track. When detection fails (branch argument not supplied and remote branches cannot be inferred), it prints the available `upstream/*` branches and bails, asking the user to name the branch explicitly.

Source

Thrown at src/upstream.rs:199

    // Determine upstream branch (explicit > HEAD > main > master)
    let upstream_branch = if let Some(branch) = upstream_branch {
        branch.to_string()
    } else if let Ok(head_ref) = git_capture(&["symbolic-ref", "refs/remotes/upstream/HEAD"]) {
        head_ref.trim().replace("refs/remotes/upstream/", "")
    } else if git_capture(&["rev-parse", "--verify", "refs/remotes/upstream/main"]).is_ok() {
        "main".to_string()
    } else if git_capture(&["rev-parse", "--verify", "refs/remotes/upstream/master"]).is_ok() {
        "master".to_string()
    } else {
        // List available branches
        let branches = git_capture(&["branch", "-r", "--list", "upstream/*"])?;
        println!("Cannot auto-detect upstream branch.");
        println!("Available upstream branches:");
        for line in branches.lines() {
            println!("  {}", line.trim());
        }
        bail!("Specify branch with: f upstream setup --branch <branch-name>");
    };

    // Check if upstream branch exists on remote
    let remote_ref = format!("refs/remotes/upstream/{}", upstream_branch);
    if git_capture(&["rev-parse", "--verify", &remote_ref]).is_err() {
        let branches = git_capture(&["branch", "-r", "--list", "upstream/*"])?;
        println!("Branch 'upstream/{}' not found.", upstream_branch);
        println!("Available upstream branches:");
        for line in branches.lines() {
            println!("  {}", line.trim());
        }
        bail!("Specify branch with: f upstream setup --branch <branch-name>");
    }

    // Create or update local upstream branch
    let local_upstream_exists =
        git_capture(&["rev-parse", "--verify", "refs/heads/upstream"]).is_ok();
    let upstream_ref = format!("upstream/{}", upstream_branch);

View on GitHub (pinned to a747e741ae)

Solutions

1. Run the command from the printed list, e.g. `f upstream setup --branch main` (or master/develop).
2. Fetch first so remote branches are visible: `git fetch upstream`, then retry setup.
3. Confirm the upstream's default branch (`git remote show upstream` or the repo's GitHub page) and pass that name.
4. If tracking a specific feature line, pass its exact remote branch name with --branch.

Example fix

// before (fails, ambiguous branches)
f upstream setup
// after
f upstream setup --branch main

# detect and pass the upstream default branch explicitly
BRANCH="$(git remote show upstream | awk '/HEAD branch/{print $NF}')"
f upstream setup --branch "$BRANCH"

When it happens

Trigger: Calling `f upstream setup` without `--branch` while `git branch -r --list upstream/*` yields branches that can't be auto-selected (ambiguous, e.g. master + main + develop) or none resolvable.

Common situations: Upstream repo uses an unusual default branch name or has both `master` and `main`; user forgot `--branch` after adding the remote; upstream branches not yet fetched locally so the list is incomplete.

Related errors

• No upstream remote. Use: f upstream setup --url <upstream-re
• No git remotes configured; cannot push PR head {}
• could not determine repo name (use --repo)
• detached HEAD (checkout a branch first)
• missing push remote for {}

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/90639d2332bcb5ad. Report an issue: GitHub.