View source for Git Monorepos Explained: From Basics to Advanced Features


<span id="strategies-for-managing-a-monorepo"></span>
=== ## Strategies for Managing a Monorepo ===

When a monorepo grows large, checking out the entire codebase becomes slow and consumes a lot of disk space. Modern Git provides two key features to handle this.

<span id="sparse-checkout"></span>
==== 1. Sparse Checkout ====

Sparse checkout allows you to check out only a specific subset of files and directories from the repository, even though you’ve cloned the entire repository history. This makes your local working directory smaller and more manageable.

<span id="partial-clone"></span>
==== 2. Partial Clone ====

A partial clone goes a step further by allowing you to clone the repository without downloading all of its objects (blobs, i.e., file content). Files are downloaded from the server only when you actually need them, like during a checkout. This significantly reduces the initial clone time and disk usage.


-----

<span id="example-using-sparse-checkout"></span>
=== ## Example: Using Sparse Checkout ===

Let’s imagine a monorepo with the following structure:

<pre>my-monorepo/
├── apps/
│   ├── web-app/
│   └── mobile-app/
├── libs/
│   ├── ui-components/
│   └── data-utils/
└── services/
    ├── auth-service/
    └── payment-service/</pre>
Now, let’s say you’re a web developer who only needs to work on the <code>web-app</code> and the shared <code>ui-components</code> library. Here’s how you would use sparse checkout to get only those two directories.

<span id="step-by-step-commands"></span>
==== '''Step-by-Step Commands''' ====

<ol style="list-style-type: decimal;">
<li><p>'''Clone the Repository without Checking Out Files'''</p>
<p>First, clone the repository but tell Git not to populate the working directory yet. This is much faster because it only fetches the Git metadata. For even better performance on large repos, you can combine this with a partial clone (<code>--filter=blob:none</code>).</p>
<syntaxhighlight lang="bash"># Clone with partial clone for best performance
git clone --filter=blob:none --no-checkout git@github.com:your-org/my-monorepo.git

cd my-monorepo</syntaxhighlight></li>
<li><p>'''Initialize Sparse Checkout'''</p>
<p>Inside the new directory, enable the sparse-checkout feature. The <code>--cone</code> argument is recommended as it’s a simpler and more performant mode that works with entire directories.</p>
<syntaxhighlight lang="bash">git sparse-checkout init --cone</syntaxhighlight></li>
<li><p>'''Define Which Directories to Check Out'''</p>
<p>Now, tell Git which directories you want in your working copy. In our case, it’s <code>apps/web-app</code> and <code>libs/ui-components</code>.</p>
<syntaxhighlight lang="bash">git sparse-checkout set apps/web-app libs/ui-components</syntaxhighlight></li>
<li><p>'''Check Out the Files'''</p>
<p>Finally, check out the branch you want to work on. Git will now pull down ''only'' the directories you specified.</p>
<syntaxhighlight lang="bash">git checkout main
# Or: git switch main</syntaxhighlight></li></ol>

Your <code>my-monorepo</code> folder will now look like this, containing only the projects you need:

<pre>my-monorepo/
├── apps/
│   └── web-app/
├── libs/
│   └── ui-components/
└── .git/</pre>
You can now work as you normally would. When you run <code>git pull</code>, it will fetch updates for the entire repository but will only update the files in your sparse working directory.


-----

<span id="monorepo-workflow"></span>
=== ## Monorepo Workflow ===

The day-to-day workflow is nearly identical to a regular Git workflow. The main difference is that a single commit can touch multiple independent projects.

<ul>
<li><p>'''Atomic Commits''': If a change in <code>libs/ui-components</code> requires a corresponding change in <code>apps/web-app</code>, you can commit both changes together. This is a major advantage of monorepos, as it keeps related changes grouped in a single, atomic unit.</p>
<syntaxhighlight lang="bash"># Make changes in both directories
# ...edit files in apps/web-app and libs/ui-components...

# Stage all changes
git add .

# Commit the changes with a descriptive message
git commit -m "feat(ui, web): Update button component and implement in header"

# Push the commit
git push origin main</syntaxhighlight></li></ul>


-----

<span id="pros-and-cons-of-a-monorepo"></span>
=== ## Pros and Cons of a Monorepo ===

<span id="advantages"></span>
==== '''Advantages''' ✅ ====

* '''Simplified Dependency Management''': You can directly import code from other projects in the monorepo without needing a package manager or complex versioning schemes for internal libraries.
* '''Atomic Commits''': Changes across multiple projects (e.g., an API service and its web client) can be made in a single commit, making the history easier to understand and roll back.
* '''Large-Scale Refactoring''': It’s much easier to refactor code that affects multiple parts of your codebase simultaneously.
* '''Unified Tooling''': You can enforce a single set of build, lint, and test tools across all projects.

<span id="disadvantages"></span>
==== '''Disadvantages''' ❌ ====

* '''Performance''': Without <code>sparse-checkout</code> and <code>partial-clone</code>, Git commands like <code>git status</code> can become very slow as the repository grows.
* '''CI/CD Complexity''': Your CI/CD system needs to be smart enough to only build and test the projects that were actually affected by a commit, rather than rebuilding everything every time. This often requires custom scripting or specialized tools.
* '''Access Control''': It’s harder to restrict access to specific parts of the codebase. The <code>CODEOWNERS</code> file can help assign responsibility but doesn’t prevent viewing.
* '''Learning Curve''': Developers need to learn the specific monorepo workflows and tooling your organization adopts.

-----

== Why Use --cone in Git Sparse-Checkout? Efficiency at Scale ==

<span id="cone-mode-vs.-non-cone-mode"></span>
=== ## Cone Mode vs. Non-Cone Mode ===

Here’s a breakdown of the key differences:

{| class="wikitable"
|-
! style="text-align: left;"| Feature
! style="text-align: left;"| ✅ '''Cone Mode (<code>--cone</code>)'''
! style="text-align: left;"| ❌ '''Non-Cone Mode'''
|-
| style="text-align: left;"| '''How it Works'''
| style="text-align: left;"| You specify a list of directories. Git checks out everything within those directories, recursively.
| style="text-align: left;"| You provide complex <code>.gitignore</code>-style patterns (like <code>src/**/*.js</code> or <code>!**/test.*</code>).
|-
| style="text-align: left;"| '''Performance'''
| style="text-align: left;"| '''Extremely fast.''' Git can determine what to include using simple prefix matching, which scales very well in large repositories.
| style="text-align: left;"| '''Can be very slow.''' It has to match every file against every pattern, which can lead to poor performance on large codebases.
|-
| style="text-align: left;"| '''Simplicity'''
| style="text-align: left;"| '''Simple and intuitive.''' You just list the folders you want to work on.
| style="text-align: left;"| '''Complex.''' The pattern syntax can be tricky, especially with inclusion and exclusion rules.
|-
| style="text-align: left;"| '''Flexibility'''
| style="text-align: left;"| '''Less flexible.''' You can’t exclude a specific sub-directory or file within a larger directory you’ve included.
| style="text-align: left;"| '''Very flexible.''' Allows for granular control over exactly which files and folders are checked out.
|}


-----

<span id="how-cone-mode-works-in-practice"></span>
=== ## How Cone Mode Works in Practice ===

When you use cone mode, Git thinks in terms of a “cone” expanding from the root of your repository. When you specify a directory, you get:

# '''All files''' in the root directory.
# '''The full recursive contents''' of the directory you specified.
# '''All files''' in the parent directories leading to your specified directory.

<span id="example"></span>
==== '''Example''' ====

Imagine this repository structure:

<pre>my-monorepo/
├── docs/
│   └── guide.md
├── services/
│   ├── auth-service/
│   │   ├── src/
│   │   └── package.json
│   └── payment-service/
├── web/
│   ├── src/
│   │   └── index.js
│   └── package.json
└── README.md</pre>
If you only want to work on the <code>web</code> project, you would run:

<syntaxhighlight lang="bash"># Initialize sparse checkout in the recommended cone mode
git sparse-checkout init --cone

# Set the directory you want to work in
git sparse-checkout set web</syntaxhighlight>
Your local file system would then look like this:

<pre>my-monorepo/
├── web/
│   ├── src/
│   │   └── index.js
│   └── package.json
└── README.md</pre>
Notice that you automatically get the <code>README.md</code> file from the root, but not the <code>docs</code> or <code>services</code> folders. If you had specified <code>services/auth-service</code>, your checkout would include the root <code>README.md</code>, the top-level <code>services</code> directory (but only its files, if any), and the full contents of <code>auth-service</code>.

<span id="why---cone-is-recommended"></span>
=== ## Why <code>--cone</code> is Recommended ===

For most monorepo use cases, the cone model is superior because:

* '''🚀 Performance:''' It’s designed to handle massive repositories with millions of files, where the old pattern-matching system would become unusably slow.
* '''🧠 Simplicity:''' The mental model is much easier. You just think “I need this folder,” and Git handles the rest efficiently.
* '''🤝 Future-Proofing:''' It’s the modern standard and works better with other advanced Git features like the <code>--sparse-index</code>.

You should only use the older non-cone mode if you have a critical need to exclude specific files or subdirectories from a larger checked-out directory, and you’re willing to accept the potential performance cost.


== Finding Directories After Git Sparse-Checkout Init --cone ==

<span id="how-to-see-available-directories"></span>
=== ## How to See Available Directories ===

To see the list of all top-level directories available in the repository, you can use the '''<code>git ls-tree</code>''' command. This command lists the contents of a specific Git tree object (in this case, the latest commit) without needing to check them out.

Here is the most useful command for this situation:

<syntaxhighlight lang="bash">git ls-tree -d --name-only HEAD</syntaxhighlight>
<span id="what-this-command-does"></span>
=== '''What This Command Does''' ===

* '''<code>git ls-tree</code>''': The base command to list the contents of a tree object.
* '''<code>-d</code>''': This flag filters the list to show '''only directories'''.
* '''<code>--name-only</code>''': This ensures the output shows just the names of the directories, making it clean and easy to read.
* '''<code>HEAD</code>''': This tells Git to look at the tree of the currently checked-out commit.

The output will be a list of the top-level folders in your repository. For example:

<pre>apps
libs
services
docs</pre>
<span id="what-to-do-next"></span>
=== '''What to Do Next''' ===

Once you see the directory you want to work on from that list, you can add it to your sparse checkout set.

For example, if you want to work on the <code>apps</code> and <code>libs</code> directories, you would run:

<syntaxhighlight lang="bash">git sparse-checkout set apps libs</syntaxhighlight>
After you run this command, Git will immediately populate your working directory with the <code>apps</code> and <code>libs</code> folders and all of their contents.