Safely Check Out a GitHub Pull Request with gh

You will finish with a local checkout of a GitHub pull request that you can inspect or test, while keeping your existing work safe. The examples use GitHub CLI 2.87.3, installed here as package version 2.45.0-1ubuntu0.3+esm3. Allow about ten minutes for a clean working tree and a pull request that is already available on GitHub.

You need gh, Git, an authenticated GitHub CLI session, and a local clone of the repository. This command changes the current repository's working tree and branch, but it does not merge the pull request. It normally needs no elevated privileges. Do not use sudo for it: root-owned files created by later build commands are harder to clean up.

1. Check the installed command and repository

Start with read-only checks. Run these from the local clone that contains the pull request's base repository:

$ gh --version
gh version 2.87.3 (2026-02-23)
$ git rev-parse --show-toplevel
/home/you/src/example
$ gh auth status
github.com
  Logged in to github.com account YOUR_ACCOUNT

The account line varies. If gh auth status reports that you are not logged in, authenticate through your normal organisation-approved process before continuing. An authenticated account still needs permission to read the repository and pull request.

2. Protect uncommitted work

Before checkout, inspect the worktree:

$ git status --short

No output means there are no tracked or untracked changes for Git to report. That is the simplest state for switching branches. If you see work that you need, stop and either commit it on a suitable branch or save it with a deliberate stash:

$ git switch -c work-before-pr
$ git add path/to/your-file
$ git commit -m 'WIP: save local changes'

Do not blindly run git clean -fd or discard changes to make checkout convenient. Those operations can remove untracked files permanently. If you used a new WIP branch, you can return to it later with git switch work-before-pr.

3. Check out a specific pull request

Use its number when you are already in the correct repository:

$ gh pr checkout 123
From https://github.com/OWNER/REPOSITORY
Switched to branch 'fix-example'

The branch name and fetch output depend on the pull request. The command resolves the pull request, fetches its head, and creates or updates a local branch. To remove ambiguity, you can pass the full pull request URL:

$ gh pr checkout https://github.com/OWNER/REPOSITORY/pull/123

For a repository other than the current one, select it explicitly with --repo:

$ gh pr checkout 123 --repo OWNER/REPOSITORY

After either form, verify what Git selected:

$ git status --short --branch
## fix-example
$ gh pr view --json number,title,headRefName,baseRefName
{
  "number": 123,
  "title": "Example fix",
  "headRefName": "fix-example",
  "baseRefName": "main"
}

The JSON values are examples, not fixed output. The important check is that the number, title and head branch match the change you meant to inspect.

4. Choose a safe local branch name

By default, the local branch uses the pull request head branch name. That can be confusing when you already have a branch with the same name, or when you are comparing several pull requests. Choose a distinct local name with --branch:

$ gh pr checkout 123 --branch review-pr-123
$ git branch --show-current
review-pr-123

This changes only the local name. Keep the pull request number in the name when you expect to review more than one candidate. It makes later cleanup easier to audit.

5. Use detached HEAD for a throwaway inspection

If you only need to build or read the pull request and do not want a local branch, use --detach:

$ gh pr checkout 123 --detach
$ git status --short --branch
## HEAD (no branch)
$ git log -1 --oneline
abc1234 Example fix

A detached HEAD is easy to leave accidentally. Before making commits, switch to a named branch or create one:

$ git switch -c review-pr-123-notes

When the inspection is over, return to your previous branch by name, for example git switch main. If you created a disposable branch and have checked that it contains nothing useful, remove it with git branch -d review-pr-123-notes. Git will refuse if that branch has unmerged commits; do not replace -d with -D unless you have checked the commits and accept irreversible local loss.

6. Understand force and submodule options

--force is the dangerous option in this command. It resets an existing local branch to the latest state of the pull request. Treat that as destructive: first record the branch and inspect its commits:

$ git branch --show-current
review-pr-123
$ git log --oneline --decorate -5

If the branch contains work you might need, make a backup reference before using force:

$ git branch backup/review-pr-123-before-force
$ gh pr checkout 123 --branch review-pr-123 --force

The backup branch is your recovery point. To restore it, switch away from the target branch and reset or recreate the working branch only after checking its commits. A safe, explicit route is:

$ git switch backup/review-pr-123-before-force
$ git log --oneline -5

Use --recurse-submodules only when the repository's test or build genuinely needs its submodules updated. That option changes nested repositories as part of checkout and may fetch more data. Check the result with git submodule status. Do not assume a submodule update is harmless in a worktree containing local edits inside a submodule.

7. Diagnose the common failures

If the pull request number is rejected, confirm the repository and number with gh pr view 123 --repo OWNER/REPOSITORY. If access fails, check gh auth status and repository permissions. If checkout refuses because local changes would be overwritten, return to step 2. Save or commit the work; do not solve the error by deleting files.

If the branch already exists, decide whether it is the branch you want. Use a new name with --branch for an independent review. Use --force only after creating a backup and accepting that the target branch will be reset. If a fetch or checkout is interrupted, inspect git status and git branch --show-current before retrying.

The installed 2.87.3 command advertises the options documented above: --branch, --detach, --force, --recurse-submodules, and inherited --repo. Check gh pr checkout --help on another machine before copying this guide there, because GitHub CLI versions can add options or alter their help text.