Graphite Reviewer is now Diamond

Git Monorepo: Best practices for scalability

Greg Foster
Greg Foster
Graphite software engineer
Try Graphite


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


Managing monorepos with Git can be challenging, especially as the size and complexity of your projects increase. Here's a guide on best practices to ensure your Git monorepo remains scalable and performant.

A Git monorepo is a single repository containing multiple projects, which can range from applications to microservices. This structure is beneficial for visibility, collaboration, and standardized tooling across teams​​.

Git itself was developed to manage a large project — the Linux kernel — making it inherently suitable for monorepo management. However, as projects grow, performance can become an issue, and strategies must be employed to manage the repository effectively​​.

There are specific tools and Git features designed to help manage large repositories:

  • Virtual Filesystem for Git (VFS): Allows for streaming support, downloading objects as needed, which is especially useful for very large repositories​​.

  • Sparse checkouts and partial clones: Enable developers to work with a large repository without cloning the entire codebase​​.

  • Git Large File Storage (LFS): An extension for Git that improves support for large files, streamlining push and pull operations​​.

  • Keep history clean: Use rebase to maintain a linear history, and ensure commits are atomic and relevant to avoid bloating the repository​​.

  • Use tags and refs wisely: Manage the number of refs to prevent performance degradation during operations like clone, fetch, or push​​.

  • Directory organization: A unified structure helps in easy navigation and discovery within the repository​​.

  • Branch management: Maintain hygiene by keeping branches small and considering trunk-based development​​.

As a Git monorepo grows, commands like git log or git blame can slow down due to the large number of commits. To mitigate this, you can:

  • Use git blame with care: Only run it when necessary, and consider using tools that can bypass the performance issues​​.

  • Optimize refs: Manage your refs to ensure operations involving them are not hindered by the sheer volume​​.

A Git monorepo is often the right choice for projects where unified versioning is essential, and when there is a need for tight collaboration across multiple codebases. However, it's crucial to recognize that not all parts of an organization's software need to be in the same monorepo; unrelated projects can be managed separately​​.

Managing large-scale Git monorepos can introduce challenges such as merge conflicts, complex CI/CD pipelines, and coordination across distributed teams. Graphite offers a suite of tools designed to address these challenges, enhancing productivity and streamlining workflows.

Graphite enables developers to create stacked pull requests, allowing large changes to be broken down into smaller, manageable pieces. This approach facilitates parallel development and reduces the overhead associated with large, monolithic PRs. By stacking PRs, teams can maintain momentum without waiting for one PR to merge before starting the next.

Merge conflicts are a common pain point in monorepos. Graphite's automated merge queue continuously rebases and tests stacked PRs against the main branch, ensuring that conflicts are identified and resolved early in the development process. This proactive approach keeps the main branch stable and reduces the likelihood of integration issues.

For teams spread across different time zones, Graphite offers features like a shared pull request inbox and actionable notifications. These tools keep team members informed and engaged, facilitating asynchronous code reviews and reducing bottlenecks in the development process.

By integrating Graphite into your Git monorepo workflow, you can overcome common challenges associated with large repositories, improve collaboration, and accelerate your development cycle.

With ongoing investments by companies like Microsoft and the development of open-source tools, the capabilities of Git to handle monorepos are improving, offering more flexibility and overcoming many initial challenges​​.

Built for the world's fastest engineering teams, now available for everyone