With the GitHub CLI, what does `gh pr checkout 482` do in your local clone, including when the pull request comes from a fork?
answer
- fetch first, then a local branch
- same repository versus fork head
- the pull request ref on the base repository
- fast-forward only unless forced
basics
~20 sgh pr checkout fetches the pull request's head and checks it out as a local branch named after the head branch, set up to track it; for a fork with no remote it fetches refs/pull/482/head from the base repository instead.
solid answer
~40 s`gh pr checkout 482` (alias `co`; it also takes a URL or a branch name) turns a pull request number into Git commands. If a remote for the head repository exists, it fetches the head branch from that remote and runs `git checkout -b <branch> --track <remote>/<branch>`. For a fork you have no remote for, it fetches `refs/pull/482/head` from the base repository into a local branch and writes `branch.<name>.remote`, `pushRemote` and `merge`. When the author allows maintainer edits, those point at the fork's branch, so `git pull` and `git push` follow the contributor's branch. A head branch named like the default branch becomes `<owner>/main` locally. On a second run it fast-forwards an existing branch; `--force` hard-resets it instead. `--detach`, `--branch` and, since gh 2.98.0, `--worktree <path>` change where the code lands.
code
bash · 7 lines# Check out pull request 482, then review it without leaving the shell
gh pr checkout 482
gh pr diff 482 --name-only
gh pr review 482 --request-changes -b "Please add a test for the empty input case"
# Same pull request into a separate worktree (gh 2.98.0 or later)
gh pr checkout 482 --worktree ../widgets-pr-482go deeper
Recall that gh pr checkout takes a number, URL or branch and leaves you on a local branch that tracks the pull request. Know that gh pr diff and gh pr review finish the review.
Explain the two paths: a remote you already have, or the base repository's pull request ref for a fork, plus the fast-forward-only rerun and what --force changes.
Show judgement about local state: when --force destroys work, when --detach or --worktree is the safer choice, and why pushing to a contributor's fork depends on maintainer edits.
Weigh how much review a team does locally versus in the browser, and what a terminal-first review flow means for consistency of review comments and onboarding.
## What the command is for A **pull request** on GitHub is a request to merge a **head branch** into a **base branch**. To run a colleague's change, step through it in a debugger or try a fix on it, you need that head branch on your own machine. Done by hand, that means looking up which repository the branch lives in, adding a remote, fetching and creating a tracking branch. `gh pr checkout` does all of that from a single number: ```bash gh pr checkout 482 ``` The argument can be a pull request **number**, its **URL** or its **head branch name**. The command also has the short alias `gh pr co`. With no argument in an interactive terminal it offers the ten most recent open pull requests to pick from; in a script with no terminal it stops with an error asking for a number, URL or branch. ## Case 1: the head branch is reachable through a remote you have When the pull request comes from a branch of the same repository, or from a fork you already added as a remote, gh reuses that remote: 1. It fetches the head branch into a **remote-tracking ref** (`refs/remotes/<remote>/<branch>`) with `--no-tags`. 2. If no local branch of that name exists, it runs `git checkout -b <branch> --track <remote>/<branch>`. The new branch tracks the remote one, so a later `git pull` brings in new commits and `git push` sends yours back. 3. If a local branch of that name already exists, it checks it out and runs `git merge --ff-only` against the freshly fetched ref. ## Case 2: a fork you have no remote for Most outside contributions arrive from forks you have never added. gh does not add a remote for them. It uses the read-only ref that GitHub keeps on the **base** repository for every pull request: - It fetches `refs/pull/482/head` straight into a local branch, named after the head branch. - If the head branch has the same name as the repository's default branch (a contributor who opened the pull request from their fork's `main`), the local branch is named `<owner>/main`, for example `alice/main`, so it never collides with your own `main`. - It writes three Git config entries for that branch: `branch.<name>.remote`, `branch.<name>.pushRemote` and `branch.<name>.merge`. - When the author has left **maintainer edits** allowed, those entries point at the fork's URL and its `refs/heads/<branch>`. `git pull` then follows the contributor's branch, and `git push` writes to it, which works only if you have write access to the base repository. - When maintainer edits are off, they point at the base repository's pull request ref. You can still pull updates, but the pull request ref is not something you can push to. ## Re-running it after the author pushes again | Situation | What plain `gh pr checkout 482` does | With `--force` | |---|---|---| | No local branch yet | creates and checks out the branch | same | | Local branch exists, author added commits | fast-forwards it (`git merge --ff-only`) | hard-resets it | | Local branch exists, author force-pushed or you committed locally | the fast-forward fails and the command errors | `git reset --hard` to the pull request's head, discarding local commits | The safe default refuses to rewrite your branch. `--force` is the explicit choice to throw away whatever you had locally. ## Flags that change where the code lands - `--branch` / `-b <name>` uses a local branch name of your choice instead of the head branch name. - `--detach` checks out the pull request's head as a **detached HEAD**, creating no branch at all. This is useful for a quick look or a build you will not commit on. - `--recurse-submodules` runs `git submodule sync --recursive` and `git submodule update --init --recursive` after the checkout. - `--worktree <path>`, added in **gh 2.98.0**, checks the pull request out into a separate Git worktree at that path. Your current working copy, with its uncommitted work, stays exactly as it was. Older releases reject the flag. ## Reviewing it once it is checked out The checkout is usually the first step of a review. The rest stays in the terminal: - `gh pr diff 482` prints the pull request's diff. `--name-only` lists only the files, `--patch` prints patch format and `--exclude` drops paths matching a glob. - `gh pr review 482 --approve` approves. `--request-changes` and `--comment` need a body (`-b` or `--body-file`); gh refuses a blank body for both of them. - In a script, `gh pr review` needs exactly one of `--approve`, `--request-changes` or `--comment`. What each kind of review means for merging (whether an approval counts, what dismissing a review does) is GitHub's behaviour, covered by the material on code review. gh only submits the review. ## Why interviewers ask it The question shows whether a candidate knows what the tool does to their repository or just types the command. The ones who know can explain why a second checkout fails after a force-push, why the branch is called `alice/main`, and why `git push` sometimes updates a contributor's fork.
- The author force-pushed and `gh pr checkout 482` now fails. What are your options?The failure is the fast-forward-only merge refusing rewritten history. `gh pr checkout 482 --force` runs `git reset --hard` to the pull request's new head and discards any local commits on that branch. If you had commits worth keeping, put them on another branch first. `--detach` gives you a throwaway look without touching the branch.
- You are mid-change with uncommitted files. How do you look at the pull request without stashing?Since gh 2.98.0, `gh pr checkout 482 --worktree ../wt-482` checks the pull request out into a separate worktree. Your current working copy stays as it is, and you `cd` into the new path to build or test the pull request. On older releases you would stash, or create a worktree by hand.
- Why can you sometimes `git push` to a contributor's fork after checking out their pull request?When the author left maintainer edits allowed and you have write access to the base repository, gh points the branch's `remote` and `pushRemote` at the fork's branch. A push then updates the pull request directly. With maintainer edits off, the branch tracks the base repository's pull request ref instead, which you cannot push to.
- gh pr checkout always adds a new git remote for the contributor's fork
- Re-running gh pr checkout silently resets your local branch to the pull request
- The local branch is always named after the pull request number
- You must clone the contributor's fork separately before you can test their pull request
- gh pr review --request-changes works in a script without a review body
Assumes gh 2.102; the --worktree flag of gh pr checkout was added in gh 2.98.0, and older releases reject it.