Submodules vs subtrees comparison in Git - Trade-offs & Expert Analysis

Overview - Submodules vs subtrees comparison

What is it?

Submodules and subtrees are two ways to include one Git repository inside another. They help manage projects that depend on other projects by linking or embedding their code. Submodules keep the external project separate but connected, while subtrees merge the external project into the main repository. Both methods let you work with multiple codebases together but in different ways.

Why it matters

Without submodules or subtrees, managing code that depends on other projects would be messy and error-prone. You would have to copy code manually or lose track of updates, causing bugs and wasted time. These tools solve the problem by organizing dependencies clearly, making collaboration and updates easier and safer. This improves productivity and reduces mistakes in software projects.

Where it fits

Before learning this, you should understand basic Git concepts like repositories, commits, branches, and remotes. After mastering submodules and subtrees, you can explore advanced Git workflows, continuous integration setups, and dependency management strategies in larger projects.

Mental Model

Core Idea

Submodules link to external projects as separate references, while subtrees embed external projects directly into your repository history.

Think of it like...

Imagine building a bookshelf: submodules are like placing a separate, pre-made box on a shelf that you can swap out anytime, while subtrees are like building the box directly into the shelf so it becomes part of the whole structure.

Main Repo
├── Submodule (pointer to external repo)
│    └── External Repo (separate)
└── Subtree (merged external repo)
     └── External Repo (integrated history)

Build-Up - 8 Steps

1

Foundation

Understanding Git repositories basics

Concept: Learn what a Git repository is and how it tracks project files and history.

A Git repository is like a folder that keeps track of all changes to your project files over time. It records snapshots called commits, which let you go back or share your work. You can have multiple repositories for different projects.

Result

You know how Git stores and tracks your project changes.

Understanding repositories is essential because submodules and subtrees work by linking or embedding these repositories.

2

Foundation

What is a Git submodule?

Concept: Introduce submodules as a way to link an external repository inside your main repository.

A submodule is a special folder inside your main project that points to a specific commit of another Git repository. It keeps the external project separate but connected. You add it with 'git submodule add '.

Result

Your main project now references an external project without merging its files directly.

Knowing that submodules keep external projects separate helps you understand their update and management process.

3

Intermediate

What is a Git subtree?

Concept: Explain subtrees as a way to merge an external repository into your main repository's history.

A subtree copies the external project's files and history into a subdirectory of your main project. You add it with 'git subtree add --prefix= '. This makes the external project part of your repository.

Result

The external project is fully integrated into your main repository's files and history.

Understanding that subtrees merge histories clarifies why they are easier to work with but can increase repository size.

4

Intermediate

Managing updates with submodules

🤔Before reading on: do you think updating a submodule automatically updates your main project? Commit to your answer.

Concept: Learn how to update and synchronize submodules with their external repositories.

To update a submodule, you must enter its folder and run 'git pull' or update the commit pointer in the main repo. The main project does not update submodules automatically; you control when to update.

Result

You can keep submodules at specific versions and update them manually when needed.

Knowing that submodules require manual updates prevents confusion about why changes in external projects don't appear automatically.

5

Intermediate

Managing updates with subtrees

🤔Before reading on: do you think subtree updates require manual merging or are automatic? Commit to your answer.

Concept: Understand how to pull changes from the external project into your subtree and push changes back.

You update a subtree with 'git subtree pull --prefix= '. This merges changes into your main repo. You can also push changes back with 'git subtree push'. This makes subtree updates more integrated.

Result

Your main project includes the latest changes from the external project and can contribute back.

Knowing subtree updates merge histories helps you see why they are more seamless but require careful conflict handling.

6

Advanced

Comparing pros and cons of submodules

🤔Before reading on: do you think submodules simplify or complicate collaboration? Commit to your answer.

Concept: Explore the advantages and disadvantages of using submodules in projects.

Pros: Keeps external projects separate, smaller main repo size, precise control over versions. Cons: Requires extra commands to clone and update, can confuse beginners, harder to manage multiple submodules.

Result

You understand when submodules are beneficial and when they add complexity.

Understanding submodules' tradeoffs helps you choose them for projects needing strict separation and version control.

7

Advanced

Comparing pros and cons of subtrees

🤔Before reading on: do you think subtrees increase or decrease repository size? Commit to your answer.

Concept: Explore the advantages and disadvantages of using subtrees in projects.

Pros: No extra commands needed after cloning, easier collaboration, integrated history. Cons: Larger repository size, more complex history, harder to remove external projects cleanly.

Result

You understand when subtrees are beneficial and when they might cause issues.

Knowing subtrees embed external projects helps you anticipate repository growth and history complexity.

8

Expert

Choosing between submodules and subtrees in production

🤔Before reading on: do you think submodules or subtrees are better for large teams? Commit to your answer.

Concept: Learn criteria and real-world patterns for selecting submodules or subtrees in professional projects.

Use submodules when you want strict version control and separation, especially if external projects are large or change independently. Use subtrees when you want simpler workflows and tighter integration, or when external projects rarely change. Consider team skills, repository size, and update frequency.

Result

You can make informed decisions about dependency management strategies in real projects.

Knowing the practical tradeoffs and team needs prevents costly mistakes in project structure and collaboration.

Under the Hood

Submodules store a special file that records the commit hash of the external repository. When you clone or update, Git reads this pointer to fetch the exact version. Subtrees copy the external repository's commits into your main repository's history under a subdirectory, merging histories. This means subtrees duplicate data but allow seamless integration.

Why designed this way?

Submodules were designed to keep projects separate and avoid duplication, reflecting the modular nature of dependencies. Subtrees were created to simplify workflows by embedding dependencies directly, trading off size for ease of use. Both approaches address different needs and historical Git limitations.

Main Repo
├─ .gitmodules (submodule pointers)
│    └─ Points to External Repo commit
├─ Submodule Folder (empty except pointer)
└─ Subtree Folder
     ├─ External Repo files
     └─ External Repo commits merged into main history

Myth Busters - 4 Common Misconceptions

Quick: Does cloning a repository with submodules automatically clone all submodules? Commit yes or no.

Common Belief: Cloning a repo automatically clones all its submodules without extra commands.

Reality: Git clones the main repository only; you must run 'git submodule update --init' to clone submodules.

Why it matters: Without this knowledge, developers may miss submodule code, causing build failures or confusion.

Quick: Do subtrees keep external projects completely separate from your repo? Commit yes or no.

Common Belief: Subtrees keep external projects separate like submodules do.

Reality: Subtrees merge external projects into your repository history, making them part of your repo.

Why it matters: Misunderstanding this leads to unexpected repository size growth and complex history.

Quick: Can you push changes made inside a submodule directly from the main repo? Commit yes or no.

Common Belief: You can push changes inside a submodule directly from the main repository commands.

Reality: You must enter the submodule directory and push changes separately; the main repo does not handle submodule pushes.

Why it matters: Ignoring this causes failed pushes and lost changes, frustrating collaboration.

Quick: Are subtrees always better than submodules for all projects? Commit yes or no.

Common Belief: Subtrees are always better because they simplify workflows.

Reality: Subtrees are not always better; they increase repo size and complicate history, which can be problematic for large or frequently changing dependencies.

Why it matters: Choosing subtrees blindly can cause performance issues and harder maintenance.

Expert Zone

1

Submodules require careful synchronization between team members to avoid detached HEAD states and broken builds.

2

Subtrees can cause duplicated commits if not managed carefully, leading to confusing history and merge conflicts.

3

Using submodules with CI/CD pipelines often requires extra scripting to initialize and update submodules correctly.

When NOT to use

Avoid submodules when your team prefers simple workflows or when dependencies rarely change, as submodules add complexity. Avoid subtrees when repository size and clean history are priorities, or when you need to remove dependencies easily. Alternatives include package managers or Git vendor branches.

Production Patterns

Large projects often use submodules for third-party libraries to keep them isolated and versioned precisely. Subtrees are common in monorepos or when integrating stable internal libraries to simplify development. Some teams combine both, using submodules for volatile dependencies and subtrees for stable ones.

Connections

Package Managers

Alternative approach to managing external code dependencies

Understanding submodules and subtrees clarifies why package managers like npm or pip automate dependency handling differently, focusing on binaries or source code versions.

Monorepo Architecture

Subtrees support monorepos by embedding multiple projects into one repository

Knowing how subtrees merge histories helps grasp how monorepos manage many projects together with shared version control.

Modular Design in Software Engineering

Both submodules and subtrees reflect modular design principles by separating or integrating components

Recognizing this connection helps appreciate how version control strategies mirror software design patterns for maintainability.

Common Pitfalls

#1 Forgetting to initialize submodules after cloning

Wrong approach:

git clone https://example.com/project.git
# No submodule initialization

Correct approach:

git clone https://example.com/project.git
git submodule update --init --recursive

Root cause:

Assuming cloning fetches all code including submodules, ignoring that submodules require explicit initialization.

#2 Committing changes inside a submodule without updating main repo pointer

Wrong approach:

cd submodule
# make changes
git commit -am 'change'
cd ..
git commit -am 'main repo commit' # without updating submodule pointer

Correct approach:

cd submodule
# make changes
git commit -am 'change'
cd ..
git add submodule
git commit -m 'update submodule pointer'

Root cause:

Not understanding that the main repo tracks submodule commits by pointer, so pointer must be updated after submodule changes.

#3 Using subtree add without specifying prefix directory

Wrong approach:

git subtree add https://example.com/lib.git main

Correct approach:

git subtree add --prefix=lib https://example.com/lib.git main

Root cause:

Missing the --prefix option causes Git to fail or put files in wrong place, showing lack of understanding subtree structure.

Key Takeaways

Git submodules link external repositories as separate pointers, requiring manual updates and initialization.

Git subtrees embed external repositories into your main repository history, simplifying workflows but increasing size.

Choosing between submodules and subtrees depends on project needs like separation, update frequency, and team workflow.

Misunderstanding how submodules and subtrees work leads to common errors like missing code or confusing history.

Mastering both tools empowers you to manage complex projects with multiple dependencies effectively.