Using the `gh pr` command for GitHub pull requests (with examples)
GitHub’s CLI (Command Line Interface) provides a convenient way to manage pull requests on GitHub repositories through the gh pr command. This article will walk you through different use cases of the gh pr command, providing code examples, motivations, explanations for each argument, and example outputs.
Use Case 1: Creating a pull request
To create a pull request using the gh pr create command, simply run:
gh pr create
Motivation: Creating a pull request is a common task when collaborating with others on a GitHub repository. Using the gh pr create command, you can quickly create a pull request without leaving the command line.
Explanation: The gh pr create command takes no arguments. It automatically detects the base branch and the head branch of the pull request based on your local branch. It opens the pull request in your default web browser, where you can add a title, description, and reviewers.
Example Output: After running gh pr create, a new pull request will be created on the GitHub repository. The command will output the URL of the created pull request in the terminal.
Use Case 2: Checking out a specific pull request locally
To check out a specific pull request locally using the gh pr checkout command, provide the pull request number as an argument:
gh pr checkout pr_number
Motivation: When working on a project, you may need to review or test a specific pull request before merging it. By checking out a specific pull request locally, you can easily switch to that branch and make changes, run tests, or review the code.
Explanation: The gh pr checkout command allows you to fetch and switch to a pull request’s branch locally. You need to specify the pull request number as the pr_number argument.
Example Output: After running gh pr checkout 42, the command will fetch the pull request with number 42 from the remote repository and checkout the corresponding branch locally. You will see the output of git commands indicating the branch switching operation.
Use Case 3: Viewing the changes made in a pull request
To view the changes made in a pull request for the current branch, you can use the gh pr diff command:
gh pr diff
Motivation: Understanding the differences introduced by a pull request is crucial when reviewing code changes. With the gh pr diff command, you can view the changes made in a pull request directly on the command line without having to open a web browser.
Explanation: The gh pr diff command shows the differences between the base branch and the head branch of the current pull request. It displays the added, modified, and deleted files as a diff output.
Example Output: Running gh pr diff will display a Git-style diff output that highlights the added and changed lines in the code. You will see the file names, line numbers, and the actual changes made.
Use Case 4: Approving a pull request
To approve a pull request for the current branch, you can execute the gh pr review command with the --approve flag:
gh pr review --approve
Motivation: An approval from reviewers is often required before a pull request can be merged. Using the gh pr review --approve command, you can easily provide your approval without leaving the command line.
Explanation: The gh pr review command is used to perform various review operations on pull requests. By adding the --approve flag, the command will approve the current pull request, signaling that the changes are acceptable.
Example Output: After running gh pr review --approve, the command will send your approval to the pull request on GitHub. You will see the output indicating that the review was submitted successfully.
Use Case 5: Merging a pull request interactively
To merge the pull request associated with the current branch interactively, you can use the gh pr merge command:
gh pr merge
Motivation: Merging pull requests is a common task when accepting and integrating changes into the main branch. The gh pr merge command provides an interactive prompt that allows you to choose the merge method, confirm the merge, and optionally delete the source branch.
Explanation: The gh pr merge command opens an interactive prompt that guides you through the merging process. It displays information about the pull request, including the number of commits, changed files, and merge status. You can choose between different merge methods, such as merge commit, squash, or rebase, and also decide whether to delete the source branch.
Example Output: Running gh pr merge will display an interactive prompt with information about the pull request and various options to choose from. After confirming the merge, the command will merge the pull request into the base branch and output the merge commit details.
Use Case 6: Editing a pull request interactively
To edit a pull request interactively, you can use the gh pr edit command:
gh pr edit
Motivation: Editing a pull request may be necessary to update the title, description, or target branch. The gh pr edit command provides an interactive prompt that allows you to make these changes directly from the command line.
Explanation: The gh pr edit command opens an interactive prompt that allows you to modify the properties of the current pull request. It lets you update the title, description, and target branch interactively.
Example Output: After running gh pr edit, the command will open an interactive prompt with the current properties of the pull request pre-filled. You can edit the desired fields and save the changes. The command will output the updated properties of the pull request.
Use Case 7: Editing the base branch of a pull request
To edit the base branch of a pull request, you can use the gh pr edit command with the --base flag:
gh pr edit --base branch_name
Motivation: Changing the base branch of a pull request can be necessary when the target branch needs to be updated. By using the gh pr edit --base command, you can easily modify the base branch from the command line.
Explanation: The gh pr edit --base command allows you to change the target branch of the current pull request. The branch_name argument represents the new base branch.
Example Output: After running gh pr edit --base release, the command will modify the base branch of the pull request to release. You will see the output confirming the successfully updated base branch.
Use Case 8: Checking the status of pull requests in a repository
To check the status of pull requests in the current repository, you can use the gh pr status command:
gh pr status
Motivation: Keeping track of the open and closed pull requests in a repository is important for project management and collaboration. The gh pr status command provides an overview of the pull requests in the current repository, their status, and other relevant information.
Explanation: The gh pr status command displays a list of pull requests in the current repository, grouped by their status (open, closed, or merged). It shows the pull request number, title, author, and relevant dates.
Example Output: Running gh pr status will display a table with information about each pull request in the repository. You will see details such as the pull request number, title, author, and status.
