Checkout a pull request

Working with pull requests (PRs) is a way for collaborators to receive context and give feedback on code changes. Sometimes, you need to checkout these PRs locally to review, test, or continue development. This guide explains how to checkout pull requests in Git from different remotes using both the command line and GitHub CLI approaches.

Understanding pull requests in Git

A pull request in platforms like GitHub is a way to request that another branch be merged into a base branch, usually from a fork or another branch within the same repository. PRs are central to collaborative projects, allowing for code review and discussion before changes are integrated into the main project.

Step 1: Configure Git to fetch pull requests

For repositories like those on GitHub, you can configure Git to fetch all of the pull requests from the original repository (upstream) by modifying your Git configuration:

git config --add remote.origin.fetch "+refs/pull/*/head:refs/remotes/origin/pr/*"

This command updates the fetch configuration for the origin remote, instructing Git to fetch pull request data into a new ref namespace, pr/*. Here’s what each part means:

• +refs/pull/*/head: This specifies that Git should fetch the head (the tip of the branch) of all pull requests.
• refs/remotes/origin/pr/*: This tells Git to store these heads in a local ref path that can be checked out easily.

This is useful if you want to checkout and view many PRs in sequence.

Step 2: Fetch all pull requests

Once you've configured Git to recognize pull requests:

git fetch origin

This command pulls all pull request data into your local repository under the refs specified earlier.

Step 3: Checkout a specific pull request

After fetching the pull requests, you can checkout a specific one by referring to its PR number:

git checkout pr/123

Replace 123 with the actual pull request number. This command switches your working directory to the state of the pull request.

Alternative method: using github cli

If you use GitHub and have the GitHub CLI installed, you can checkout pull requests directly without configuring the fetch settings:

1. List open pull requests:

   Terminal

   gh pr list
   
   

2. Checkout a pull request by number:

   Terminal

   gh pr checkout 123
   
   

   Replace 123 with the pull request number. The GitHub CLI handles the fetching and checking out steps for you.

Step 4: Review and test the pull request locally

With the PR checked out locally, you can now compile the code, run tests, or do manual testing to ensure that the changes meet the project's standards and do not introduce bugs.

Best practices and tips

• Keep your local and remote branches updated: Regularly pull changes from the main branch of your repository to keep your PR branches up-to-date and avoid conflicts.

• Review changes thoroughly: Use the local checkout to perform a thorough review of the pull request changes. Look for code quality, functionality, and integration with existing code.

• Clean up after testing: Once you're done testing or have merged the PR, switch back to your main branch and delete the local PR branch if necessary:

  Terminal

  git checkout main
  git branch -D pr/123  # Delete the local PR branch
  
  

For further reading on checking out pull requests, see the official GitHub documentation.

How to checkout a pull request using Graphite CLI

Graphite's CLI simplifies the process of working with pull requests and enables advanced workflows like PR stacking. To check out a specific pull request for review or further development, you can use the following steps:

Step 1: Install and set up Graphite CLI

Ensure you have Graphite CLI installed and configured. Follow the instructions in the Graphite CLI installation guide.

Step 2: Identify the pull request

To check out a pull request, you first need to know the name or identifier of the branch associated with the PR. If you are using Graphite’s PR inbox, it integrates tightly with your Git workflow, making it easy to track and identify the pull request.

Step 3: Checkout the pull request

To check out a pull request, use the gt commands as follows:

# List all available branches or PRs
gt log short

# Checkout a specific PR branch
gt checkout <branch-name>

Replace <branch-name> with the branch name associated with the PR. Graphite CLI simplifies this process by ensuring all stack-related changes are seamlessly pulled in and aligned with your workflow.

Step 4: Work with the pull request

After checking out the PR:

• Review changes: You can use your editor or tools like git diff to inspect changes.
• Make edits: Modify the code if needed and stage changes for new commits.
• Restack if necessary: If this PR is part of a stack, you can ensure dependent branches are synchronized using gt restack.

# Restack the current branch and all dependent branches
gt restack

Step 5: Submit changes back to the remote

Once your changes are ready, you can push them back to the remote repository and update the pull request:

gt submit

This command also ensures the PR stack remains updated and ready for review. If you'd like to assign reviewers at the same time, you can add the --reviewers option:

gt submit --reviewers <username>

Graphite CLI makes it easy to manage PRs, stacks, and updates in one cohesive workflow. For more details, see the Graphite CLI quick start guide.