How to split an existing pull request on GitHub

Sometimes, a PR grows too large, making it difficult to review. Splitting a PR into smaller, manageable pieces can improve clarity, facilitate more thorough reviews, and speed up the integration process.

Why Split a Pull Request?

1. Ease of Review: Smaller PRs are easier to understand and review, leading to more effective code inspections and fewer oversights.

2. Focused Changes: Each PR can focus on a single aspect of the change, reducing the cognitive load on reviewers.

3. Faster Integration: Smaller PRs can be integrated faster, reducing the time changes sit in review queues, which in turn minimizes merge conflicts.

4. Better Discussion: Discussions can be more focused and actionable when they revolve around specific, isolated changes.

The Case for Short Pull Requests

According to a Graphite.dev blog post, the optimal PR size is approximately 50 lines. The data suggests that PRs of this size are reviewed and merged about 40% faster than those with 250 lines. Moreover, they are less likely to be reverted and typically garner more thorough reviews with 40% more comments per line of code. These bite-sized PRs not only expedite the review process but also enhance the overall quality and understanding of the code changes.

How to Split an Existing PR on GitHub

Identifying the Split Points

Before splitting a PR, identify logical breakpoints within your changes where the code can be divided into self-contained updates.

Steps for Splitting a PR:

1. Create New Branches for Each Segment:
   Based on the identified split points, create new branches from the current branch's latest commit.

   git checkout -b new-branch-for-segment

2. Cherry-Pick Commits:
   Use git cherry-pick to move commits related to each segment onto the corresponding new branches.

   git cherry-pick <commit-hash>

3. Push the New Branches:
   Push each new branch to the repository.

   git push origin new-branch-for-segment

4. Open New PRs:
   In GitHub, navigate to each new branch and open a new PR for each segment.

5. Close the Original PR:
   Once the new PRs are created, close the original PR with a comment linking to the new PRs for context.

Using Graphite CLI to Split PRs

Graphite CLI can simplify the process of splitting PRs by managing the creation of new branches and the movement of changes.

Steps with Graphite CLI:

1. Identify the Changes to Move:
   Determine which changes or commits will form the basis of the new, smaller PRs.

2. Create and Manage Stacks:
   Use gt stack create to create new stacks for each set of changes.

3. Move Changes Between Stacks:
   Utilize gt stack fix or gt split to move changes to the appropriate stacks.

4. Push the Stacks and Open PRs:
   Push the new stacks to GitHub using gt push and then use GitHub's interface to open new PRs for each stack.

5. Link to the New PRs:
   In the original PR, mention the new PRs and provide reasoning for the split to maintain context and transparency.

Conclusion

Splitting a large PR into smaller, more digestible chunks can greatly improve the review process. Both Git and Graphite CLI offer tools to facilitate this, whether through manual branch and commit management or through automated stack manipulation. By following the steps outlined in this guide, teams can maintain an efficient and effective review workflow.

For more detailed command usage and to understand advanced features, refer to the official Graphite documentation. Remember to link to specific sections that pertain to the commands used in this guide for users seeking more in-depth knowledge.