How to Use the Command 'gh pr merge' (with Examples)

The gh pr merge command is part of the GitHub CLI (Command-Line Interface). This command facilitates the merging of pull requests directly from the command line, providing developers with a more seamless and efficient workflow. Whether you are collaborating on open-source projects or managing enterprise-level software development, the ability to merge pull requests via a command-line interface offers greater flexibility, efficiency, and control over your codebase.

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

Code:

gh pr merge

Motivation:

Merging the pull request associated with the current branch interactively is particularly useful when you are working on a feature branch locally and want to integrate your changes into the main project codebase. By merging interactively, you can follow guided prompts that confirm your choices at each step, ensuring that the merge process goes smoothly and according to your preferences.

Explanation:

• gh pr merge: This command identifies the pull request linked to the branch you’re currently working on in your repository. It enters an interactive mode, making it easier to confirm steps or make necessary changes before finalizing the merge.

Example Output:

? What merge method would you like to use? (Use arrows to move, type to filter)
> merge: Create a merge commit
  squash: Squash and merge
  rebase: Rebase and merge

Use case 2: Merge the Specified Pull Request, Interactively

Code:

gh pr merge pr_number

Motivation:

When you have multiple pull requests open and you want to merge a specific one, specifying the pull request number offers precision and clarity. This is especially useful in large projects where multiple features and fixes are being handled simultaneously, allowing you to merge only the PR you’ve reviewed and approved.

Explanation:

• gh pr merge: Initiates the merge process.
• pr_number: This placeholder is replaced with the numeric identifier of the specific pull request you wish to merge.

Example Output:

? What merge method would you like to use for pull request #45? (Use arrows to move, type to filter)
  merge: Create a merge commit
  squash: Squash and merge
  rebase: Rebase and merge

Use case 3: Merge the Pull Request, Removing the Branch on Both the Local and the Remote

Code:

gh pr merge --delete-branch

Motivation:

After a pull request has been successfully merged, the associated feature branch often becomes redundant. Automatically deleting the branch both locally and on the remote server helps maintain a clean working environment and reduces the clutter of stale branches. This practice is a hallmark of a well-organized and efficient development workflow.

Explanation:

• gh pr merge: Begins the merge process for the current pull request.
• --delete-branch: This flag ensures that once the merge is finalized, the branch used for that pull request is deleted on both the local machine and the remote repository, contributing to a tidier repository.

Example Output:

? What merge method would you like to use? squash: Squash and merge
- Deleting branch "feature-branch" locally and on remote
✓ Successfully merged and deleted branch

Use case 4: Merge the Current Pull Request with the Specified Merge Strategy

Code:

gh pr merge --merge

or

gh pr merge --squash

or

gh pr merge --rebase

Motivation:

Different projects and teams may use different merging strategies based on their workflow preferences. Some teams prefer to keep a linear history with rebase, while others like to maintain all merges for historical reasons. Offering multiple strategies like merge, squash, and rebase ensures that each team can adhere to their chosen workflow for consistency and compliance with their development standards.

Explanation:

• gh pr merge: Begins the process of merging a pull request.
• --merge: Indicates that a normal merge commit should be created.
• --squash: Combines all commits in the branch into a single commit before merging.
• --rebase: Reapplies all commits of the pull request on top of the base branch, keeping the commit history linear.

Example Output:

✓ Pull request #47 successfully merged using strategy: rebase

Use case 5: Merge the Current Pull Request with the Specified Merge Strategy and Commit Message

Code:

gh pr merge --merge --subject "Add feature X"

Motivation:

When merging a pull request, specifying a commit message ensures that the reason for the merge and the main contributions of the pull request are clearly documented in the version control history. This is especially important for maintaining a clear and informative history, which is invaluable during code reviews, audits, or when tracing back through commit logs.

Explanation:

• gh pr merge: Initializes the merge process.
• --merge: Uses the merge commit strategy.
• --subject "Add feature X": Provides a subject line for the merge commit message.

Example Output:

✓ Pull request #53 successfully merged with commit message: "Add feature X"

Use case 6: Squash the Current Pull Request into One Commit with the Message Body and Merge

Code:

gh pr merge --squash --body="Implemented new feature Y with tests"

Motivation:

Squashing all the changes from a pull request into a single commit before merging can make the project’s history easier to read and track. This approach minimizes the number of commits in the main branch, often resulting in a more understandable and straightforward project history. It’s helpful for containing feature-related changes or improvements in a single, concise commit.

Explanation:

• gh pr merge: Sets off the pull request merge process.
• --squash: Ensures all commits from the PR are consolidated into one.
• --body="Implemented new feature Y with tests": Sets the message body for the newly created commit after a squash, explaining the changes introduced by this squash and merge operation.

Example Output:

✓ Pull request #65 successfully squashed and merged with message: "Implemented new feature Y with tests"

Use case 7: Display Help

Code:

gh pr merge --help

Motivation:

Using the --help flag provides detailed information about the command options, flags, and arguments. This is especially useful for new users or when introducing new team members to the tool, ensuring everyone can quickly become proficient with using the CLI for managing their pull requests.

Explanation:

• gh pr merge: Refers to the local pull request being acted upon.
• --help: Displays a help guide, explaining each of the available options and how to use them correctly.

Example Output:

gh pr merge: Merge a pull request
Flags:
  --delete-branch              Delete the local and remote branch after the merge
  --merge                      Create a merge commit
  --squash                     Squash and merge
  --rebase                     Rebase and merge
  --subject string             Set the commit subject
  --body string                Set the commit body

Conclusion

In summary, the gh pr merge command in the GitHub CLI offers flexibility and control to developers who wish to manage pull requests efficiently from the command line. With options for interactive merging, strategy selection, message specification, and branch management, it covers a wide range of needs in modern software development. Overall, the command stands out as a core part of the GitHub CLI, supporting various workflows and enhancing productivity in code collaboration environments.