How to merge a stack of pull requests in GitHub

Merging a stack of pull requests (PRs) in GitHub, especially in a sequential order, can enhance the efficiency of managing code changes across multiple branches. This guide will walk you through merging stacked pull requests in GitHub, as well as explore some common workflows and best practices for merging PRs in order.

Understanding stacked pull requests

A stack of pull requests refers to multiple PRs that depend on each other. These PRs are typically created from branches in a hierarchy, where each pull request builds upon the previous one. This allows for breaking down large sets of changes into smaller, manageable parts.

For example:

1. PR 1 – feat: add feature A
2. PR 2 – refactor: refactor feature A
3. PR 3 – test: add tests for feature A

Why merge pull requests in a stack?

Merging pull requests in a stack offers several advantages:

• Easier code review: Smaller, focused PRs are easier to review than a single, large one.
• Fewer merge conflicts: By resolving dependencies in sequence, you reduce the risk of conflicts.
• Improved collaboration: Different team members can work on related but separate tasks without waiting for large batches of changes to be approved.

However, managing and merging stacked pull requests manually can be complex. GitHub natively supports basic workflows, but integrating tools like Graphite can further simplify the process.

Manually merging a stack of pull requests

If you're using GitHub without any automation, merging stacked pull requests manually means you'll need to make sure that they are merged in the correct order.

Step 1: Review and approve each PR in sequence

Each pull request should go through the review process before merging. For example, start with PR 1, approve and merge it, and then move to PR 2.

Step 2: Rebase PRs on the main branch

Before merging the next pull request in the stack, ensure it’s rebased on the main branch to pick up the latest changes. This reduces the likelihood of merge conflicts.

You can rebase a PR by checking out the branch locally and running:

git fetch origin
git checkout pr-branch-name
git rebase main

Step 3: Merge pull requests in order

Once all PRs are reviewed and rebased, you can start merging. First, merge PR 1, then PR 2, and so on. GitHub’s web interface offers a straightforward way to merge each PR once it’s ready.

Here’s the sequence:

1. Merge PR 1.
2. Wait for the merge to complete and update the main branch.
3. Rebase PR 2 and merge it.
4. Repeat this process for PR 3 and the remaining PRs.

This manual process works, but for larger stacks or more complex dependencies, automation is a time saver.

Automating stack merges with Graphite

Graphite allows you to merge a stack of pull requests automatically. Stacking is highly beneficial for those who deal with complex pull request chains and want to ensure each PR is merged in sequence to avoid manual overhead.

How Graphite's automatic stack merge works

Graphite automates the process by detecting dependencies between PRs and ensuring that they are merged sequentially, one after the other. It eliminates the need for manual rebasing and helps manage merge conflicts.

To use Graphite:

1. Create a stack of PRs: Graphite identifies your PRs as part of a stack based on branch dependencies.
2. Set merge rules: Configure rules that define the order in which the PRs should be merged, whether they should rebase automatically, and what to do in case of conflicts.
3. Trigger stack merge: Graphite’s automation kicks in, handling each pull request in sequence, making sure they are merged only when their dependencies are resolved.

Best practices for managing stacked PRs

1. Use small, focused PRs: Breaking down large changes into smaller PRs makes reviewing easier and helps manage dependencies.
2. Label dependent PRs clearly: In the pull request description, make it clear that a PR depends on another one being merged first. This improves communication with your team.
3. Automate your workflow: Tools like Graphite can save time and reduce errors when working with a stack of pull requests, especially for larger teams and projects.

Using the GitHub CLI for stacked PR merges

If you prefer working from the terminal, the GitHub CLI offers commands that can help manage a stack of PRs.

Example workflow with GitHub CLI:

# List pull requests
gh pr list

# Merge pull requests one by one
gh pr merge <pr-number> --rebase

While this method still requires some manual input, it simplifies rebase and merge steps and can be an efficient alternative for smaller stacks.

Merging multiple pull requests in GitHub, especially in a stack, is a key component of an efficient workflow. While manual methods work for smaller PRs, automation tools like Graphite make managing pull request chains smoother, especially for complex, interdependent changes.