Unsupported flag --orphan when checking out pull request

Error message

Unsupported flag --orphan when checking out pull request

What it means

Same guard as the -b case: sanitizeCheckoutFlags rejects `--orphan` because creating an orphan (history-less) branch is incompatible with how hub checks out a pull request's head ref into a new local branch. The error is returned before any git command runs.

Source

Thrown at commands/checkout.go:156

			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

Remove --orphan; check out the PR normally with `hub checkout <pr-url>`.
If you truly need an orphan branch, run it separately: `git checkout --orphan newbranch` after checking out the PR.
Use raw git plumbing: git fetch origin pull/<n>/head, then git checkout --orphan mybranch and git reset --hard FETCH_HEAD.

Example fix

// before
hub checkout https://github.com/owner/repo/pull/42 --orphan
// after
hub checkout https://github.com/owner/repo/pull/42
git checkout --orphan fresh-start

Defensive patterns

Strategy: validation

Validate before calling

case " $extra_args " in
  *" --orphan "*) echo "--orphan is unsupported with hub PR checkout"; exit 1 ;;
esac

Prevention

Never combine --orphan with hub checkout of a PR URL.
Create orphan branches with plain git checkout --orphan in a separate step.
Sanitize forwarded arguments in wrapper scripts.

When it happens

Trigger: Running `hub checkout <pr-url> --orphan` — passing git-checkout's --orphan flag alongside a pull-request checkout.

Common situations: Scripts templating `git checkout --orphan` conversions onto the hub PR form; users wanting to start a fresh branch from a PR without history — an inherently conflicting request.

Related errors

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