How to use the command 'gh pr merge' (with examples)

The command ‘gh pr merge’ is part of the GitHub CLI tool and is used to merge GitHub pull requests. It provides several options for merging pull requests with different strategies and configurations.

Use case 1: Merge the pull request associated with the current branch interactively

Code:

gh pr merge

Motivation: This use case is useful when you want to merge the pull request associated with the current branch interactively. It allows you to review and confirm the changes before merging.

Explanation: The command ‘gh pr merge’ without specifying a pull request number merges the pull request associated with the current branch. By running this command, you will be prompted to review the changes and confirm the merge.

Example output:

✔ Merged pull request #42 (BranchName) into main

Use case 2: Merge the specified pull request interactively

Code:

gh pr merge pr_number

Motivation: This use case is helpful when you want to merge a specific pull request interactively. It allows you to merge a pull request based on its number, regardless of the current branch.

Explanation: By providing the pull request number as an argument to the command ‘gh pr merge’, you can merge that specific pull request interactively. This is useful when you want to focus on merging a particular pull request without switching branches.

Example output:

✔ Merged pull request #42 (BranchName) into main

Use case 3: Merge the pull request and remove the branch

Code:

gh pr merge --delete-branch

Motivation: This use case is beneficial when you want to automatically delete the branch after merging a pull request. It helps keep the repository clean and avoid clutter from merged branches.

Explanation: The ‘–delete-branch’ flag is used in conjunction with the ‘gh pr merge’ command. When provided, it removes the branch associated with the merged pull request both locally and remotely.

Example output:

✔ Merged pull request #42 (BranchName) into main 
✔ Deleted branch BranchName

Use case 4: Merge the current pull request with a specific merge strategy

Code:

gh pr merge --merge|squash|rebase

Motivation: This use case is useful when you want to merge the current pull request using a specific merge strategy, such as ‘merge’, ‘squash’, or ‘rebase’. Each strategy has its own advantages and may be more suitable depending on the situation.

Explanation: By adding the ‘–merge’, ‘–squash’, or ‘–rebase’ flag to the ‘gh pr merge’ command, you can specify the merge strategy to use for the current pull request. This allows you to have control over how the changes are incorporated into the target branch.

Example output:

✔ Merged pull request #42 (BranchName) into main using the 'merge' strategy

Use case 5: Merge the current pull request with a merge strategy and a custom commit message

Code:

gh pr merge --merge|squash|rebase --subject commit_message

Motivation: This use case is helpful when you want to merge the current pull request using a specific merge strategy and provide a custom commit message. Custom commit messages can provide clarity about the changes being merged.

Explanation: The ‘–subject’ flag is used in conjunction with the ‘–merge’, ‘–squash’, or ‘–rebase’ flag to specify a custom commit message for the merge. This allows you to add a descriptive message that explains the purpose of the changes being merged.

Example output:

✔ Merged pull request #42 (BranchName) into main using the 'merge' strategy with commit message: "Implemented new feature"

Use case 6: Squash the current pull request into one commit with a custom commit message

Code:

gh pr merge --squash --body="commit_message_body"

Motivation: This use case is beneficial when you want to squash the current pull request into a single commit, providing a custom commit message. Squashing multiple commits into one can help improve the commit history and make it more concise.

Explanation: The ‘–squash’ flag is used to squash the current pull request into one commit. Additionally, the ‘–body’ flag allows you to provide a custom commit message body. This message can include more detailed information about the changes.

Example output:

✔ Merged pull request #42 (BranchName) into main using the 'squash' strategy with commit message: "Implemented new feature: Fix bug and refactor code"

Use case 7: Display help

Code:

gh pr merge --help

Motivation: This use case provides access to the command’s help documentation, which can be useful when you need to understand the available options and command usage.

Explanation: Adding the ‘–help’ flag to the ‘gh pr merge’ command displays the help documentation, which contains information about each available option, their explanations, and examples.

Example output (partial):

...
Merge GitHub pull requests.

USAGE
  gh pr merge [<number>] [flags]
...

More information: <https://cli.github.com/manual/gh_pr_merge>

Conclusion:

The ‘gh pr merge’ command is a powerful tool for merging GitHub pull requests. It provides various options to handle different merge scenarios, allowing users to customize the merge process according to their needs. Whether you want to merge interactively, specify a merge strategy, or add custom commit messages, ‘gh pr merge’ has you covered.