How to break up large pull requests

Large pull requests (PRs) can slow down code reviews, increase the risk of merge conflicts, and make it harder for teams to understand and maintain code. Breaking up these monolithic changes into smaller, focused PRs not only accelerates review cycles but also promotes better code quality. In this guide, we’ll discuss:

• Why large PRs are problematic
• The benefits of splitting them up
• Various techniques for dividing changes manually using Git
• How to leverage tools like Graphite for automated splitting and stacking
• Best practices to keep your PRs small and manageable

Why break up large pull requests

Large PRs tend to be overwhelming for reviewers and can introduce several challenges:

• Review bottlenecks: massive changes can lead to long review cycles and missed issues
• Increased merge conflicts: bundling many changes together makes integration more error prone
• Loss of context: when hundreds of lines of code change at once, it’s difficult for reviewers to pinpoint problems or understand the rationale behind modifications

Studies and industry best practices suggest that keeping PRs to around 50–200 lines results in faster reviews and fewer bugs. Splitting large changes into smaller, incremental pieces helps maintain a steady flow in your development process.

Benefits of splitting large pull requests

By breaking up large PRs, teams enjoy several advantages:

• Faster reviews: smaller changes are easier to review thoroughly, resulting in quicker feedback loops.
• Improved collaboration: with each PR focused on a single concern, communication becomes clearer and more actionable.
• Reduced risk: isolated changes are simpler to test, making it easier to identify and fix bugs.
• Incremental integration: merging smaller PRs into the main branch ensures that integration issues are caught early.

Techniques for breaking up large pull requests

There are two main approaches to splitting up large changes:

1. Manual splitting using git

Before introducing tools, you can break up a PR by identifying logical split points within your changes. A common manual workflow might be:

• Identify independent chunks: look for boundaries in functionality or file changes.
• Create new branches: use Git to branch off from your current work at these split points.
• Cherry-pick or separate commits: move relevant commits into the new branches.
• Open separate PRs: submit each branch as its own pull request and close (or update) the original large PR.

Example commands:

# assume you're on a feature branch with many changes
# create a new branch for the first logical chunk
git checkout -b feature-part-1

# use cherry-pick to move commits that belong to part 1
git cherry-pick <commit-hash>

# push and open a new PR
git push origin feature-part-1

For a detailed walkthrough, see Graphite’s guide on splitting an existing pull request on GitHub and the guide on splitting a PR into multiple PRs.

2. Automated splitting with Graphite CLI and stacking

Graphite offers command-line tools and a VS Code extension that simplify the process of splitting a large PR and stacking changes. The Graphite CLI automates tasks like rebasing, creating new branches from specific changes, and submitting a stack of smaller PRs. In a stacking workflow, each new PR is built on top of the previous one so that reviewers can progress incrementally.

Key commands include:

• gt create: stage changes and create a new branch with a commit
• gt split: interactively select changes (by commit or hunk) to form a new PR
• gt submit: push the branches and open new PRs for each segment
• gt modify: amend commits and automatically restack dependent branches

Example workflow:

1. Create the initial PR:

   Terminal

   # from your feature branch, stage and commit a small set of changes
   gt create --all --message "feat: add initial component"
   gt submit
   
   

2. Stack additional changes:

   Terminal

   # after the first PR is open, continue working on the next small change
   gt create --all --message "feat: update component styles"
   gt submit --stack
   
   

Graphite automatically handles branch dependencies and rebasing so that when one PR is merged, the stacked ones update accordingly.

Best practices for breaking up large pull requests

To ensure that your efforts in splitting up PRs yield maximum benefits, consider these best practices:

• Keep changes atomic: each PR should have a single purpose, whether it’s a feature enhancement, a bug fix, or a refactor
• Set internal guidelines: aim for PRs under 200 lines (ideally around 50 lines) to keep reviews manageable
• Use descriptive commit messages: explain the rationale behind changes so reviewers understand the context
• Leverage automation: use tools like Graphite to automate the splitting, stacking, and rebasing processes
• Review early and often: submit your smaller PRs as soon as they’re ready to gather feedback and unblock further work
• Document dependencies: if a PR depends on another, clearly reference it in the description (e.g., “depends on #123”) so reviewers know the order of merging

These practices not only improve review quality but also help maintain a clean Git history.

Conclusion

Breaking up large pull requests into smaller, focused units is essential for maintaining rapid, high-quality development. By applying both manual techniques and automated workflows using Graphite’s CLI and stacking features, teams can:

• Simplify code reviews
• Minimize merge conflicts
• Accelerate feedback loops
• Enable incremental integration of changes

For additional insights, explore Graphite’s comprehensive guides on splitting PRs, managing large pull requests, and stacking workflows.