Unsupported flag -b when checking out pull request

Error message

Unsupported flag -b when checking out pull request

What it means

When `hub checkout <pull-request-url>` runs, sanitizeCheckoutFlags scans the user's extra git arguments and rejects flags that conflict with hub's pull-request checkout behavior. `-b` (create a new branch) is rejected because hub already creates its own branch named after the PR, so passing -b is unsupported.

Source

Thrown at commands/checkout.go:152

			if err != nil {
				return
			}

			remote = project.GitURL("", "", true)
			mergeRef = fmt.Sprintf("refs/heads/%s", pullRequest.Head.Ref)
		}

		if mc, err := git.Config(fmt.Sprintf("branch.%s.merge", newBranchName)); err != nil || mc == "" {
			args.After("git", "config", fmt.Sprintf("branch.%s.remote", newBranchName), remote)
			args.After("git", "config", fmt.Sprintf("branch.%s.merge", newBranchName), mergeRef)
		}
	}
	return
}

func sanitizeCheckoutFlags(args *Args) error {
	if i := args.IndexOfParam("-b"); i != -1 {
		return fmt.Errorf("Unsupported flag -b when checking out pull request")
	}

	if i := args.IndexOfParam("--orphan"); i != -1 {
		return fmt.Errorf("Unsupported flag --orphan when checking out pull request")
	}

	return nil
}

func replaceCheckoutParam(args *Args, checkoutURL string, replacement ...string) {
	idx := args.IndexOfParam(checkoutURL)
	args.RemoveParam(idx)
	args.InsertParam(idx, replacement...)
}

View on GitHub (pinned to 5c547ed804)

Solutions

Drop the -b flag: `hub checkout <pr-url>` already creates a local branch for the PR.
Rename the branch afterwards with `git branch -m` if you want a custom name.
Use plain `git fetch origin pull/<n>/head && git checkout -b myname FETCH_HEAD` if you need full control over the branch creation.

Example fix

// before
hub checkout https://github.com/owner/repo/pull/42 -b my-feature
// after
hub checkout https://github.com/owner/repo/pull/42
git branch -m my-feature

Defensive patterns

Strategy: validation

Validate before calling

// Strip -b/--orphan before invoking hub checkout for a PR:
args := filtered(args, func(a string) bool { return a != "-b" && a != "--orphan" })

Prevention

Remember hub checkout creates the PR branch for you; never pass -b.
In scripts that forward args to hub checkout, filter git-only flags first.
Rename branches post-checkout with git branch -m instead of -b.

When it happens

Trigger: Running `hub checkout <pr-url-or-number> -b <branch>` — i.e. appending git-checkout's -b flag to a hub PR checkout command.

Common situations: Muscle memory from `git checkout -b feature` applied to the hub PR checkout form; scripting that blindly forwards extra args to git checkout; users wanting a custom branch name for the PR.

Related errors

AI-assisted analysis of mislav/hub@5c547ed804 (2026-09-01). Data as JSON: /api/errors/0b1709e763e5de83. Report an issue: GitHub.