Submodules vs subtrees comparison in Git - Visual Side-by-Side Comparison

Process Flow - Submodules vs subtrees comparison

Start: Main Repo

↓

Add Submodule

↓

Link external repo

↓

Separate commit history

↓

Add Subtree

↓

Embed external repo

↓

Merge commit history

↓

No separate clone needed

Shows two ways to include external repositories: submodules link separately, subtrees embed and merge.

Execution Sample

Git

git submodule add https://github.com/lib/example.git libs/example
# Adds example repo as a submodule

git subtree add --prefix=libs/example https://github.com/lib/example.git main --squash
# Adds example repo as a subtree

Commands to add an external repo as a submodule and as a subtree.

Process Table

Step	Action	Effect on Main Repo	Commit History	Clone Behavior
1	Add submodule	Adds a link to external repo in .gitmodules and folder	Separate commit history maintained	Requires separate clone/update of submodule
2	Commit submodule change	Records submodule pointer commit	Main repo commits pointer, not submodule content	Submodule content not stored in main repo
3	Add subtree	Copies external repo files into subfolder	Commit history merged or squashed into main repo	No separate clone needed, all content in main repo
4	Commit subtree change	Records merged content in main repo	Full or squashed history included	All content versioned together
5	Update submodule	Must run git submodule update separately	Submodule updated independently	Separate step needed
6	Update subtree	Use git subtree pull to merge updates	Updates merged into main repo history	Single repo update
7	Exit	Comparison complete	Shows differences in history and clone	Shows differences in workflow

💡 Comparison ends after showing key differences in usage and behavior

Status Tracker

Variable	Start	After Step 1	After Step 3	After Step 5	After Step 6	Final
Main Repo Content	Empty or original	Link to submodule folder added	External repo files copied in subtree folder	Submodule pointer updated	Subtree files updated	Final state with submodule link and subtree files
Commit History	Original commits	Main repo commits pointer to submodule commit	Main repo commits include subtree commits merged	Submodule commits updated separately	Subtree commits merged into main repo	Combined commit history state
Clone Behavior	Clone main repo only	Need separate clone/update for submodule	All files present in main repo clone	Submodule update separate	Subtree update integrated	Clone and update behavior compared

Key Moments - 3 Insights

Why does the submodule require a separate clone or update step?

Because submodules are linked repositories, not embedded, so git treats them as separate repos needing their own clone or update (see execution_table step 1 and 5).

How does the commit history differ between submodules and subtrees?

Submodules keep their commit history separate and only store a pointer in the main repo, while subtrees merge or squash the external repo's commits into the main repo's history (see execution_table steps 1, 3, and 4).

What happens to the external repo files in a subtree compared to a submodule?

In a subtree, the external repo files are copied directly into the main repo folder, making them part of the main repo content, unlike submodules which only link to the external repo (see execution_table steps 1 and 3).

Visual Quiz - 3 Questions

Look at the execution table, at which step does the main repo start including the external repo files directly?

A Step 1

B Step 3

C Step 5

D Step 6

💡 Hint

Check the 'Effect on Main Repo' column for when files are copied in

According to the variable tracker, what is the clone behavior after adding a submodule?

A All files are included in the main repo clone

B No clone needed for submodule

C Separate clone or update is needed for the submodule

D Submodule files are merged automatically

💡 Hint

Look at 'Clone Behavior' after Step 1 in variable_tracker

If you want the external repo commits merged into your main repo history, which method should you use?

A Subtree

B Neither

C Submodule

D Both

💡 Hint

Refer to 'Commit History' in execution_table steps 3 and 4

Concept Snapshot

Git Submodules vs Subtrees:
- Submodules link external repos as separate folders
- Submodules keep separate commit history and need separate updates
- Subtrees copy external repo files into main repo folder
- Subtrees merge or squash commit history into main repo
- Subtrees require no separate clone or update steps
- Choose submodules for separate control, subtrees for integrated history

Full Transcript

This visual execution compares git submodules and subtrees. Submodules add a link to an external repo, keeping its commit history separate and requiring separate clone and update commands. Subtrees copy the external repo files into a subfolder of the main repo and merge or squash the commit history, so all content and history are integrated. The execution table shows step-by-step actions and effects on the main repo, commit history, and clone behavior. The variable tracker follows changes in main repo content, commit history, and clone behavior across steps. Key moments clarify why submodules need separate updates, how commit histories differ, and how external files are handled. The quiz tests understanding of when files are included, clone behavior, and commit history merging. The snapshot summarizes the main differences and when to use each method.