How to Manage GitHub Pull Requests with 'gh pr' (with examples)

The gh pr command is part of the GitHub CLI (Command Line Interface) that allows developers to manage pull requests directly from the terminal. This command provides a streamlined way to create, review, and manipulate pull requests, integrating these tasks seamlessly into your development workflow without having to leave the command line interface. This is particularly useful for developers who prefer a terminal-centric workflow, as it reduces context switching and enhances productivity.

Use case 1: Create a Pull Request

Code:

gh pr create

Motivation: Creating a pull request is a fundamental task in collaborative software development. It allows developers to propose changes to a repository, request reviews from collaborators, and initiate discussions about the code modifications. Using the gh pr create command simplifies this process by enabling you to create pull requests directly from the command line without navigating through the GitHub web interface.

Explanation: This command initiates an interactive process where you’ll be prompted to provide essential details about your pull request, such as the title, description, and branch details. The command does not require additional arguments as it interacts with the current branch to form the basis of the pull request.

Example Output:

? Title [My new feature]: Add sorting by date feature
? Body [Leave blank for no description]: This pull request adds a new sorting feature by date...
? What's next? Submit

Use case 2: Check Out a Specific Pull Request Locally

Code:

gh pr checkout [pr_number]

Motivation: Checking out a pull request locally is crucial for developers who need to examine changes in detail and test them in their personal environment before merging. It allows for a thorough review process without affecting the main branch.

Explanation: The [pr_number] argument is the unique identifier for the pull request you want to check out. This command fetches the pull request branch and switches to it, making it easy to explore the changes it introduces.

Example Output:

Switched to branch 'pr-123'
Your branch is up to date with 'origin/pr-123'.

Use case 3: View the Changes Made in the Pull Request for the Current Branch

Code:

gh pr diff

Motivation: Viewing differences in a pull request is crucial to understanding the code changes that it introduces. This helps team members or collaborators to inspect modifications, review the impact on the existing codebase, and ensure that it adheres to the project’s coding standards.

Explanation: This command displays the differences (diff) between the current branch and the branch associated with the pull request. It gives a detailed view of additions, deletions, and modifications.

Example Output:

diff --git a/file.txt b/file.txt
index e69de29..35e8e9c 100644
--- a/file.txt
+++ b/file.txt
@@ -0,0 +1,5 @@
+This is a new line added
+Another line added

Use case 4: Approve the Pull Request for the Current Branch

Code:

gh pr review --approve

Motivation: Approving a pull request is a formal acknowledgment that the proposed changes are satisfactory and ready to be merged. In team settings, this is a critical step in the code review process, as it communicates consensus about the quality and readiness of the code.

Explanation: The --approve flag is used with gh pr review to register your approval for the changes in the current pull request. It signals that you have reviewed the changes and find them acceptable.

Example Output:

Review approved for 'add-new-feature'

Use case 5: Merge the Pull Request Associated with the Current Branch Interactively

Code:

gh pr merge

Motivation: Merging a pull request is the final step in integrating proposed changes into the mainline of a project. This command helps streamline the merging process by doing it directly from the terminal, saving time and reducing potential errors from context switching.

Explanation: Running this command initiates an interactive process where you’ll confirm the merge action and select an appropriate merge method (e.g., merge, squash, rebase).

Example Output:

? Merge pull request? Yes
✔ Merged pull request #123 (feature-branch) into main.

Use case 6: Edit a Pull Request Interactively

Code:

gh pr edit

Motivation: Editing a pull request is often necessary when details such as the description, title, or reviewers need updating. This command allows these modifications to be made swiftly through the command line.

Explanation: The gh pr edit command prompts you to change certain details of your pull request interactively, such as the title or description. This is useful for ensuring pull request information is accurate and up to date.

Example Output:

? Title [Update feature branch]: Add exception handling
? Description: Added context to existing methods...

Use case 7: Edit the Base Branch of a Pull Request

Code:

gh pr edit --base [branch_name]

Motivation: Sometimes a pull request needs to be retargeted to a different base branch. The gh pr edit --base command facilitates this transition without requiring an entirely new pull request, preserving discussion history and existing reviews.

Explanation: The --base [branch_name] argument allows you to specify a new base branch for the current pull request, effectively changing the diff context against which your changes will be measured.

Example Output:

? Change the base branch? Yes
✔ Set the base branch to 'development'.

Use case 8: Check the Status of the Current Repository’s Pull Requests

Code:

gh pr status

Motivation: Keeping track of the status of all pull requests in a repository is vital for project management and prioritization. Knowing which pull requests are open, merged, or under review helps project maintainers and contributors stay informed about the progress and state of development efforts.

Explanation: This command displays a summary of pull request statuses for the current repository, listing them as open, closed, or merged, along with their titles and branch information.

Example Output:

Relevant pull requests in current repo:

Current branch
  #321  New feature implementation

Created by you
  #300  Fix issue 404  (merged)

Requesting a code review from you
  #302  Improve documentation

Conclusion

The gh pr command in the GitHub CLI offers a powerful suite of tools for managing pull requests directly from the terminal. Whether you’re creating, reviewing, or merging pull requests, these capabilities offer improved efficiency and ease for developers working within a CLI environment. Each use case covered demonstrates the versatility of the gh pr command and how it can be integrated into everyday GitHub workflows, empowering you to handle your projects more effectively.