How Google Manages Billions of Lines of Code in a Single Monorepo

Google has famously adopted a monorepo strategy for decades, storing billions of lines of code in a single, colossal repository. While this approach might seem counterintuitive in an era dominated by distributed repositories, it has proven to be a foundational decision for Google, enabling immense productivity and global visibility. This document explores the intricate details, custom tooling, and cultural shifts that make Google’s monorepo not just feasible, but highly effective at an unprecedented scale.

The Monorepo Paradox: A Historical Perspective

Google’s journey with a monorepo began long before the modern distributed version control systems became prevalent. Initially, Google utilized CVS (Concurrent Versions System), then transitioned to Perforce. As their codebase grew, Perforce struggled to scale, leading Google to engineer a custom distributed storage and tooling stack. This decision was made at a time when the industry was moving towards splitting codebases into multiple, smaller repositories (polyrepos). Google, however, chose to double down on its monorepo philosophy, recognizing the inherent productivity advantages of global visibility.

Scale of Google’s Monorepo (circa 2014 data)

To truly grasp the magnitude, consider these statistics from 2014:

• Size: The monorepo was approximately 84 terabytes (TB), containing over 2 billion lines of code.
• Activity: Engineers modified 15 million lines of code across 250,000 files weekly.
• Commits: An average of 40,000 commits were processed per workday.
• Read Traffic: The system handled 500,000 queries per second for read traffic.

These numbers highlight the extreme demands placed on their version control system and the necessity for highly specialized solutions.

Custom Tooling: The Backbone of Google’s Monorepo

Managing a monorepo of this scale is not merely a storage and retrieval problem; it’s a developer experience challenge. Google’s success hinges on a sophisticated ecosystem of custom-built tools that abstract away the complexity and enhance developer productivity.

Sits (Clients in the Cloud)

Sits is a critical component that enables developers to work with the massive monorepo locally without cloning the entire 84TB codebase. It functions as a cloud storage system paired with Linux FUSE (File System in User Space).

• Lazy Loading: Sits lazily loads files as they are accessed. When a developer navigates a directory, only the metadata for the files within that directory is fetched initially.
• Copy-on-Write Semantics: Local workspaces are maintained using a copy-on-write approach. Only files that are explicitly changed by the developer are kept as local copies. All other files are referenced directly from the remote, actual source tree. This ensures that local environments remain lightweight and efficient.

Piper

While not detailed in the transcript, Piper is mentioned as part of Google’s comprehensive CI/CD workflow, indicating a robust infrastructure built around the monorepo to handle continuous integration and deployment at scale.

Development Workflow: Trunk-Based Development

Google employs a strict trunk-based development model, which simplifies branching and merging complexities inherent in a monorepo.

• Single Mainline Branch: There is only one primary branch, often referred to as mainline, trunk, or head. All development and merges occur directly into this single branch.
• Short-Lived Workspaces: Developers create temporary, short-lived workspaces for their changes. Once changes are complete and reviewed, they are merged directly into the mainline.
• No Release Branches: Unlike typical Git workflows with multiple release branches, Google’s system operates on a single, continuously evolving mainline. This means teams are responsible for maintaining backward compatibility, as all downstream dependencies rely on the latest mainline version.

Owner’s Review System

To manage code ownership and ensure quality in a globally visible codebase, Google implements an owner’s review system:

• OWNERS Files: Every folder or subdirectory can contain an OWNERS file. This file lists the user IDs or groups that have ownership over the corresponding code.
• Mandatory Approvals: If a developer attempts to modify a file within a subdirectory they do not own, they must obtain approval from the designated owners before their changes can be merged into mainline.
• Visibility with Guardrails: While the source code is generally accessible to all engineers, guardrails are in place to restrict visibility for sensitive or proprietary codebases, ensuring appropriate access control.

Key Advantages of Google’s Monorepo

Google’s monorepo, supported by its custom tooling and development practices, offers several significant advantages:

1. Elimination of Diamond Dependency Conflicts

In a polyrepo setup, diamond dependency conflicts occur when a service (A) depends on two libraries (B and C), which in turn both depend on a common library (D), but require different versions (e.g., B needs D v1.0, C needs D v2.0). This creates a complex versioning nightmare.

In Google’s monorepo:

• Single Source of Truth: Everything merges to mainline, meaning there’s effectively only one version of any given library or component at any time.
• Backward Compatibility: Teams are inherently responsible for maintaining backward compatibility when they update their code. If a change breaks compatibility, all downstream services must adapt accordingly when they pull the latest mainline.
• Simplified Dependency Management: This approach eliminates the need to manage multiple versions of dependencies, drastically simplifying the build and deployment process.

2. Simplified Refactoring and Global Changes

Refactoring across multiple repositories can be a daunting task, requiring coordinated changes and deployments across many teams. In a monorepo:

• Atomic Changes: Large-scale refactorings or API changes can be performed atomically across the entire codebase, as all code resides in one place.
• Automated Transformations (Rosie Hub): Google utilizes an automatic refactoring engine, reportedly via a system called Rosie Hub. This system can perform large-scale code transformations, using MapReduce-like jobs to automatically update downstream dependencies when a file or API changes. While the speaker notes not having direct experience with Rosie Hub, its existence highlights Google’s investment in automated code maintenance.

3. Enhanced Developer Experience and Productivity

• Global Visibility: Developers have immediate access to all internal code, fostering code reuse and preventing redundant efforts.
• **Reduced