Multirepo vs. Monorepo

Introduction

This document compares and analyzes two approaches to organizing source repositories in a version control system—multirepo and monorepo—to help engineering organizations choose between them.

Why the Choice Matters

Before considering which approach to use, we need to understand why it matters. The answer becomes clear when we look at how a project starts and evolves.

The Initial Project Structure

Projects often begin as monolithic services. With a small codebase and few developers, handling everything in one place is efficient. Because the system is a single unit rather than separate components, it is also managed in one repository.

Moving to Microservices as a Project Grows

As a project grows, a monolithic system can cause problems, notably tight coupling and low cohesion. To address them, engineering organizations begin separating the system by domain into microservices. At that point, they must decide whether to manage those services in one repository or in separate repositories.

Multirepo vs. Monorepo

The distinction is whether the system’s modules are managed in separate repositories or a single repository. We call the first approach multirepo and the second monorepo.

Multirepo

Each service in the system has its own repository.
Services are not integrated at the source-code level.
Each service occupies a separate directory.

Advantages

• Clear ownership
  
  • Each repository has a designated owner.
• Less risk of breaking master
  • The codebases are completely separate.
  • Work in different services is less likely to conflict and break master.
• Faster version control and CI
  • Small repositories make tools driven by repository hooks faster.

Disadvantages

• Code reuse is harder, increasing the likelihood of duplication.
  • Using code from another repository requires extra work.
• A single feature may require merges into several repositories.
• Code reviews are split across repositories.
• Versions can become incompatible.
  • A breaking change does not propagate immediately to other repositories.
• Dependency hell
  • Dependency graphs become very complex as projects grow.
  • Changes to each other’s code are harder to accommodate.

Monorepo

All services in the system are managed together in one repository.
Services are integrated at the source-code level.
Service directories form a tree under the repository root.

Advantages

• Continuous source integrity
  • The repository maintains a valid state in which all services work together.
• Unified version control
  • Integrated services can easily be managed under one version.
• Easier code sharing and reuse
  • Integration already happens at the source-code level.
• Easier dependency management
  • Dependencies across all services can be inspected and configured in one repository.
• Atomic changes
  • A change happens in a single step in one repository rather than across several steps.
• Easier collaboration between project teams
  • Teams work in one repository and can readily access multiple services.
• Flexible team boundaries and code ownership
  • Ownership need not be confined to one repository or one service.
• Unified CI and testing
  • All source code is integrated, making CI and testing easier to configure.
• A clear tree view of the entire codebase
• All changes are visible in a single code review.

Disadvantages

• Dependencies can proliferate without discipline.
  • Because adding dependencies is easy, excessive coupling can develop.
• Slower version control and CI
  • Large repositories slow down tools driven by repository hooks.

Comparing Key Characteristics

Code Ownership

For ownership, whether the system uses microservices matters more than whether it uses one repository or several. If services are cleanly separated by domain, ownership can be assigned per service.

In a monolithic system, services are not yet clearly separated, so ownership must be divided among different parts of one service. This can make ownership boundaries ambiguous. The best solution is to split the system into microservices. If that is difficult, tooling can assign code owners by directory.

Propagating Breaking Changes

In a multirepo setup, each repository manages its own source, so a breaking change does not automatically propagate to dependent modules. In a monorepo, everyone works from the same source tree, allowing a breaking change to be detected immediately as an error.

Code Review

When a feature requires changes in several repositories, a multirepo setup also spreads its reviews across those repositories. In a monorepo, the work is handled as a single change in one repository, giving reviewers a clearer view of its effects.

Dependency Management

A monorepo has an advantage because all source code is managed in one place. All dependencies can be inspected there, and related configuration files can be maintained together. In a multirepo setup, each repository knows only its own dependencies, making the overall dependency graph harder to understand.

Version Management

Both approaches have strengths and weaknesses. Because each service has its own version control history in a multirepo setup, independent service versioning is easier. As discussed above, however, this can cause version conflicts between services. A monorepo starts from unified version management. Because all source code is integrated, applying different versioning and release strategies to individual services is more difficult. Fine-grained version management requires more sophisticated branching strategies and supporting tools.

Tool Performance

Multirepo has an advantage here. Tools operate on individual, smaller repositories, making each unit of work smaller and faster. However, tools that apply version control or CI to selected parts of a repository can address this issue in a monorepo as well.

Conclusion

At first glance, monorepo and multirepo are simply different ways of dividing repositories. Looking more closely reveals distinct strengths, weaknesses, and many considerations across their key characteristics.

Which should an engineering organization choose? Start with the system architecture you have today or plan to build, then consider which approach fits it. If the system is divided into modules with simple dependencies, multiple repositories may be easier to manage. If the system and engineering organization are growing, and the dependency graph is likely to become much more complex, a monorepo may be more useful.

References

Monorepos at Other Companies

• Google - Why Google Stores Billions of Lines of Code in a Single Repository(Video)
• Google - Why Google Stores Billions of Lines of Code in a Single Repository
• Facebook - Scaling Mercurial at Facebook
• Uber - Uber Technology Day: Monorepo to Multirepo and Back Again(Video)
• Uber - The Journey To Android Monorepo: The History Of Uber Engineering’s Android Codebase Organization
• Airbnb - From Monorail to Monorepo: Airbnb’s journey into Microservices
• Spotify - Segment's transition back to a monorepo(Video)
• Netflix - Towards true continuous integration: distributed repositories and dependencies

Other Resources

• Monorepos in the Wild
• Awesome Monorepo
• Advantages of monorepos
• Report: “We went Monorepo.”
• Monorepos: Please don't!
• Monorepos: Please do!