DEV Community

Cover image for 📦 Managing Multiple Projects in One Repository: Submodules, Subtrees, Monorepos & Partial Cloning Explained
Codespear profile image K-kibet
K-kibet for Codespear

Posted on

📦 Managing Multiple Projects in One Repository: Submodules, Subtrees, Monorepos & Partial Cloning Explained

#github #git #cli #docker

Modern software development often involves several related projects that need to live together—perhaps a shared library, a mobile app, an admin dashboard, and a backend API. Managing these independently while keeping them organized in a single place requires the right Git strategy.

In this guide, we’ll explore four powerful approaches to organizing multiple projects under one repository:

  • Git Submodules
  • Git Subtrees
  • Monorepo structure
  • Partial cloning using sparse-checkout

Each technique has its strengths and ideal use cases. Let’s break them down with clear examples.

🔧 1. Git Submodules — Independent Projects Inside a Parent Repository

Git submodules let you embed separate Git repositories inside a parent repository. Each submodule maintains its own commit history and remote origin.

✔ When to Use Submodules

  • When projects must remain completely independent
  • When you want separate version control per project
  • When reused modules belong in multiple repositories

📌 Example Use Case

Main project: mega-suite
Submodules:

  • ui-engine
  • data-analyzer

📥 Adding a Submodule 

git submodule add https://github.com/example/ui-engine.git modules/ui-engine
git commit -m "Added ui-engine as submodule"
Enter fullscreen mode Exit fullscreen mode

This creates a .gitmodules file that tracks submodule entries.

▶ Initialize & Update Submodules 

git submodule update --init --recursive
Enter fullscreen mode Exit fullscreen mode

🔄 Working Inside a Submodule 

cd modules/ui-engine
git checkout main
Enter fullscreen mode Exit fullscreen mode

💡 Pros

  • Clean separation
  • Reusable modules
  • Independent version history

⚠ Limitations

  • Can confuse beginners
  • Requires extra commands to sync
  • Submodules can break if misconfigured

🌳 2. Git Subtrees — Embed Projects Without Complexity

Git subtrees merge another repository into a folder inside your repo—without the extra complexity of submodules.

✔ When to Use Subtrees

  • When you want all code in one repo
  • But still want to pull updates from external repos
  • And you don’t want the overhead of submodules

📌 Example Use Case

Main repository: mega-suite
Subtree projects:

  • ui-engine
  • data-analyzer

➕ Add a Subtree 

git remote add ui-engine https://github.com/example/ui-engine.git
git subtree add --prefix=modules/ui-engine ui-engine main --squash
Enter fullscreen mode Exit fullscreen mode

🔄 Updating the Subtree 

git subtree pull --prefix=modules/ui-engine ui-engine main --squash
Enter fullscreen mode Exit fullscreen mode

💡 Pros

  • Everything stored inside one repo
  • No special clone commands
  • Easier than submodules
  • No detached HEAD issues

⚠ Limitations

  • Repo size grows faster
  • No true isolation between projects

🏢 3. Monorepos — A Single Repo for Multiple Projects

A monorepo is a repository where all projects live together—even if they are unrelated. Big companies like Google, Meta, and Microsoft use monorepos to streamline development.

✔ When to Use a Monorepo

  • When projects depend on each other
  • When you want shared tooling and libraries
  • When you want centralized versioning

📁 Example Monorepo Structure: 

mega-suite/
├── apps/
│   ├── dashboard/
│   └── mobile/
├── services/
│   ├── auth-service/
│   └── billing-service/
└── shared/
    ├── ui-kit/
    └── utils/
Enter fullscreen mode Exit fullscreen mode

💡 Pros

  • Easy refactoring across multiple projects
  • Shared code lives in one place
  • One repository to maintain
  • Unified versioning

⚠ Limitations

  • Repo can grow very large
  • Requires tooling (NX, Lerna, Turborepo)
  • Requires discipline to maintain structure

📥 4. Partial Cloning — Clone Only the Project You Need

Partial cloning (via sparse-checkout) allows users to clone only specific folders instead of the entire repository. This is perfect for monorepos.

✔ When to Use Sparse-Checkout / Partial Cloning

  • Repo is too large
  • Developers work on only one project
  • You want to save disk space and bandwidth

📌 Example Setup

Monorepo: mega-suite
Folders:

  • apps/dashboard
  • apps/mobile

🧩 Clone Repo Without Checkout 

git clone --no-checkout https://github.com/example/mega-suite.git
cd mega-suite
Enter fullscreen mode Exit fullscreen mode

🔧 Initialize Sparse Checkout 

git sparse-checkout init
git sparse-checkout set apps/dashboard
Enter fullscreen mode Exit fullscreen mode

▶ Checkout Files 

git checkout main
Enter fullscreen mode Exit fullscreen mode

Now only the dashboard project is downloaded!

💡 Pros

  • Works perfectly with monorepos
  • Saves disk space
  • Developers download only what they need

⚠ Limitations

  • Requires Git 2.25+
  • Adds a bit of setup complexity

🎯 Which Approach Should You Choose?

Use Case Best Method
Projects must remain fully independent Submodules
Want all code in one repo but keep external sources Subtrees
Multiple related apps/libraries in one place Monorepo
Only need to clone specific folders Partial cloning

🚀 Final Thoughts

Organizing multiple projects under one Git repository isn’t one-size-fits-all. Each method—submodules, subtrees, monorepos, and partial cloning—serves a different purpose.

  • For strict independence → Submodules
  • For simpler integration → Subtrees
  • For large ecosystems → Monorepos
  • For large repos requiring selective cloning → Partial cloning

Pick the strategy that fits your workflow and scale your projects with confidence.

Top comments (0)