A monorepo is easy to describe and surprisingly hard to evaluate.

The simple definition is one repository containing many projects. The useful definition is more demanding: a monorepo is an engineering model where code, dependency information, build rules, ownership, and change history can be reasoned about as one connected system.

That distinction matters. Putting several folders into one Git repository gives you shared storage. It does not automatically give you the properties that make very large repositories valuable.

This note synthesises publicly documented material. It does not describe private code, unreleased systems, or non-public operational details.

The real advantage is atomic change

Imagine a shared interface used by hundreds of services. In a multi-repository setup, changing that interface can require a sequence of coordinated releases:

  1. Publish a compatible version of the interface.
  2. Update every consumer.
  3. Wait for those updates to deploy.
  4. Remove the old interface.

Each step introduces a temporary state that must be supported. With a monorepo and a build system that understands dependencies, the interface and its consumers can often change together. The repository records one coherent transition from the old state to the new state.

That is the important property: related code can move atomically.

Visibility changes engineering behaviour

Shared visibility makes several workflows easier:

  • Searching for every use of an API before changing it.
  • Finding an existing library instead of creating a second one.
  • Applying a security fix across many consumers.
  • Establishing one version of a third-party dependency.
  • Understanding ownership through code rather than organisational memory.

This can reduce duplication, but only when discovery is good. A repository containing millions of files is not useful if search, navigation, and indexing feel slow.

Repository scale therefore becomes a developer-tooling problem. Fast search, code intelligence, dependency graphs, build caching, ownership metadata, and automated refactoring are the interface through which engineers experience the repository.

Piper is not "Git, but bigger"

Google has publicly described Piper as its source-control system for a large monolithic repository. The interesting lesson is not that every company should build a custom version-control system. It is that repository architecture and surrounding tooling have to be designed together.

At sufficiently large scale, several assumptions made by ordinary local clones stop working:

  • A developer should not need every file on their machine.
  • Reading a file and editing a file can be separate operations.
  • Repository-wide operations need indexes rather than filesystem scans.
  • Build and test selection must use dependency information.
  • Large refactors need automation and reviewable intermediate steps.

The repository is therefore better understood as a service than a folder. A developer works with a relevant view of a much larger source graph.

Monorepo does not mean monolith

A monorepo is a source-management choice. A monolith is a runtime architecture.

One repository can contain hundreds of independently deployed services. Conversely, one large application can be split across several repositories. The repository answers where source code lives and how changes cross boundaries. The runtime answers how the system is built, deployed, scaled, and isolated.

The costs are real

Large repositories concentrate complexity:

  • Access control becomes more subtle.
  • Continuous integration can become expensive.
  • A poorly designed change can affect a wide surface area.
  • Build tooling has to avoid rebuilding the world.
  • Ownership boundaries need to stay legible.

The strongest monorepo examples work because organisations invest in the systems around the repository. Copying the directory structure without the tooling can produce the costs without the benefits.

A practical decision test

Do changes regularly cross repository boundaries?

If a product change frequently requires coordinated updates across services and shared packages, atomic changes may be valuable.

Can the build system understand dependencies?

Without dependency-aware builds and test selection, repository growth quickly slows feedback loops.

Is ownership visible?

A shared repository should make responsibility clearer, not create a large unowned commons.

Are teams willing to standardise?

Monorepos reward common conventions for formatting, testing, dependency management, and release metadata. If every directory behaves independently, shared storage achieves little.

The broader lesson

The valuable idea is not that one repository always wins. It is that code organisation should optimise the movement of changes through a system.

Good version control makes a change easy to understand, review, validate, and reverse. At small scale, Git and a few repositories may do that perfectly. At very large scale, a monorepo can offer unusually strong consistency, but only when supported by equally strong infrastructure.

The repository is not the strategy. The developer experience around change is.

Public references