Table of contents

• Key challenges in monorepos
• Branch naming best practices
• Keep changes small and focused
• Rebase often to stay in sync
• Squash commits for clean merges
• Review and land large changes safely
• How Graphite helps
• Conclusion

Monorepos—single repositories containing code for multiple projects—help teams centralize code and collaboration. Feature branch workflows let developers isolate changes before merging them into the main branch. But in monorepos, where all teams share one codebase, effective branch management is essential.

Key challenges in monorepos

Working with feature branches in a monorepo introduces several challenges:

• Change scope isolation: Keep feature branches focused on one logical change. Avoid mixing unrelated updates.
• Cross-package conflicts: Multiple teams working in parallel can cause merge conflicts if they touch the same files. Frequent rebases and smaller changes reduce the risk.
• Messy history: With many contributors, history can become noisy. Clean histories help with traceability and troubleshooting.

Branch naming best practices

Since all teams share the same Git namespace, clear and consistent branch naming helps:

• Use prefixes like feature/ or bugfix/: e.g. feature/onboarding-tour.
• Include ticket IDs or scopes: e.g. feature/ABC-123-login.
• Prevent naming collisions by adding project or team info: e.g. mobile/feature/login-ui.
• Clean up merged branches to reduce clutter.

Keep changes small and focused

Short-lived feature branches reduce conflicts and make reviews easier. Large features should be broken into multiple smaller branches—e.g. scaffolding, logic, and edge case handling. This is often called stacked development, where each branch builds on the last and can be reviewed independently.

Use feature flags if a full feature can't be delivered all at once. You can merge incomplete work behind a flag and release it later, avoiding long-lived branches.

Rebase often to stay in sync

Feature branches should rebase or merge from main frequently to stay current. Rebasing keeps the commit history clean by avoiding unnecessary merge commits. It also lets you test your changes against the latest codebase.

Benefits include:

• Early detection of conflicts.
• Fewer integration surprises.
• CI runs against the most recent code.

Avoid rebasing if others are working on the same branch—merge instead to avoid rewriting shared history.

Squash commits for clean merges

When merging to main, squashing condenses many commits into one. This simplifies the commit history and makes changes easier to understand. Use descriptive messages that mention what changed and why. Prefix messages with affected modules (e.g. auth: handle timeout errors).

Merge strategies:

• Merge commits preserve all history but can clutter git log.
• Squash and merge simplifies history—ideal for monorepos.
• Rebase and fast-forward keeps a linear history without merge commits.

Use CI and code review checks to block broken or unreviewed code from reaching main. A merge queue can help coordinate safe, serialized merges. Learn more about automated vs. manual code reviews and how to find the right balance for your team.

Review and land large changes safely

Large changes (e.g. refactors or broad feature additions) require extra care:

• Split them into reviewable parts.
• Assign reviewers by package or domain.
• Use flags to avoid exposing incomplete features.
• Test extensively and plan for rollbacks.

A merge queue tests and merges each PR against the latest main, reducing the risk of post-merge breakage. This is especially helpful in high-velocity monorepos.

How Graphite helps

Graphite is a tool built for modern teams working in Git-based monorepos. It supports stack-based development, automates reviews, and helps keep branches healthy.

Key features include:

• Stacked pull requests: Break big changes into smaller, dependent PRs that can be reviewed and merged independently. Learn more about stacked diffs.
• Merge queue: Keeps main stable by testing and merging PRs one at a time after rebasing. Read more about merge queues.
• PR inbox: View and manage all your outgoing and incoming PRs in one place.
• Slack notifications: Stay updated on reviews and commits without leaving chat.
• Review automation: Graphite’s Diamond bot offers AI-powered code review to catch issues early.

Stacked development lets teams work in parallel. While one PR is under review, developers can keep building the next one. This reduces idle time and improves delivery speed.

With Graphite, teams working in monorepos get clean history, fewer conflicts, and more control over how changes land. It’s a productivity boost that makes branching workflows smoother and safer.

Conclusion

Managing feature branch workflows in a monorepo requires clear strategies, disciplined practices, and the right tools. By keeping branches focused, rebasing often, squashing commits, and leveraging tools like Graphite, teams can minimize conflicts, maintain a clean history, and accelerate delivery. Adopting these best practices ensures that even as your codebase and team grow, your development process remains efficient, collaborative, and resilient.