Support `gh stack checkout <branch>` for branches that only exist on remote

[skarim]

Summary

When a branch exists on the remote but not locally, gh stack checkout <branch> currently fails to find the branch. I had to run gh pr view to get the PR number and pass that to gh stack checkout as a workaround. The command should accept a branch name that only exists on the remote and create a corresponding local tracking branch (or otherwise resolve it) so users don't have to fetch the PR number first.

Steps to reproduce

1. Ensure the branch exists on origin but is not checked out locally (e.g., created via GitHub or pushed from another machine).
2. Run: gh stack checkout <branch-name>
3. Command fails to find the branch (unless the branch already exists locally).

Expected behavior

• gh stack checkout <branch> should accept a remote-only branch name and either:
  • automatically fetch the branch from the remote and create a local tracking branch, or
  • resolve the branch name to the associated PR and check out that PR branch without requiring the user to run gh pr view first.

Proposed solution / notes

• When the branch is not found locally, try resolving it against remote refs (e.g., origin/) and create a local tracking branch.
• Alternatively, allow passing a branch name and have the CLI look up a matching open PR on GitHub and operate on that PR directly.
• Ensure behavior is consistent for forks and for branches with the same name on multiple remotes.

Impact

This is a UX friction point: users who create branches on GitHub or work across machines end up needing extra steps (running gh pr view to get a PR number) to check out a branch using gh stack.

Environment / example

• gh version: (example) gh version 2.x
• OS: (example) macOS / Linux

Please update gh stack checkout to support remote-only branches or add clearer docs/CLI hints about the current limitation.

View original Slack conversation