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.

Practice

1. What is the main difference between Git submodules and Git subtrees?

easy

A. Submodules and subtrees are identical in how they manage external repositories.

B. Submodules copy external repositories; subtrees link them separately.

C. Submodules merge external repositories automatically; subtrees require manual merging.

D. Submodules link external repositories separately; subtrees copy them into your project.

Solution

1. Step 1: Understand submodules behavior

   Submodules keep external repositories linked but separate from the main project folder.

2. Step 2: Understand subtrees behavior

   Subtrees copy the external repository content directly into your project folder, making it part of your codebase.

3. Final Answer:

   Submodules link external repositories separately; subtrees copy them into your project. -> Option D

4. Quick Check:

   Submodules = separate links, Subtrees = copied content [OK]

Hint: Remember: submodules link, subtrees copy [OK]

Common Mistakes:

• Confusing which method copies code versus links it
• Thinking submodules merge code automatically
• Assuming subtrees keep repos separate

2. Which Git command correctly adds a submodule to your repository?

easy

A. git subtree add --prefix=folder_name repo_url branch

B. git submodule add repo_url folder_name

C. git add submodule repo_url folder_name

D. git clone --submodule repo_url folder_name

Solution

1. Step 1: Identify the correct syntax for adding a submodule

   The correct command is 'git submodule add' followed by the repository URL and the folder name.

2. Step 2: Verify other options

   git subtree add --prefix=folder_name repo_url branch is for subtrees, not submodules. git add submodule repo_url folder_name and git clone --submodule repo_url folder_name are invalid Git commands for adding submodules.

3. Final Answer:

   git submodule add repo_url folder_name -> Option B

4. Quick Check:

   Submodule add uses 'git submodule add' [OK]

Hint: Submodule add always starts with 'git submodule add' [OK]

Common Mistakes:

• Using 'git subtree add' for submodules
• Trying to add submodules with 'git add'
• Confusing clone options with submodule commands

3. Given the commands below, what will be the result after cloning a repository with a submodule?

git clone https://example.com/main-repo.git
cd main-repo
git submodule update --init --recursive

medium

A. Only the main repository is cloned; submodules remain empty folders.

B. The submodules are cloned but not initialized.

C. The main repository and all submodules are cloned and initialized.

D. The clone fails because submodules require separate cloning.

Solution

1. Step 1: Understand cloning with submodules

   Cloning the main repo alone does not fetch submodule content; submodules are empty initially.

2. Step 2: Use 'git submodule update --init --recursive'

   This command fetches and initializes all submodules recursively, filling their folders with content.

3. Final Answer:

   The main repository and all submodules are cloned and initialized. -> Option C

4. Quick Check:

   Submodule update with init fetches submodules [OK]

Hint: Run 'git submodule update --init --recursive' after clone [OK]

Common Mistakes:

• Assuming submodules clone automatically with main repo
• Skipping the submodule update command
• Confusing initialization with cloning

4. You added a subtree with git subtree add --prefix=lib https://example.com/lib.git main but later changes in the subtree are not reflected in your main repo. What is the likely cause?

medium

A. You forgot to pull subtree updates with git subtree pull.

B. Subtrees automatically sync changes; no action needed.

C. You must use git submodule update to sync subtrees.

D. Subtrees cannot be updated once added.

Solution

1. Step 1: Understand subtree update process

   Subtrees copy code but do not auto-sync; you must manually pull updates.

2. Step 2: Identify correct command to update subtree

   The command 'git subtree pull' fetches and merges changes from the external repo into your subtree folder.

3. Final Answer:

   You forgot to pull subtree updates with git subtree pull. -> Option A

4. Quick Check:

   Subtrees require manual pull to update [OK]

Hint: Use 'git subtree pull' to update subtree changes [OK]

Common Mistakes:

• Expecting automatic subtree sync
• Using submodule commands for subtrees
• Thinking subtrees are read-only

5. You want to include a third-party library in your project. You want to keep it separate for easy updates but also want your team to clone the project with one command without extra steps. Which approach is best?

hard

A. Use Git subtrees to copy the library into your project for simpler cloning.

B. Use Git submodules and instruct the team to run extra commands after cloning.

C. Manually copy the library files without Git integration.

D. Use Git submodules but disable recursive cloning.

Solution

1. Step 1: Analyze submodules pros and cons

   Submodules keep code separate but require extra commands after cloning to initialize submodules.

2. Step 2: Analyze subtrees pros and cons

   Subtrees copy the library into the project, so cloning is simple with one command and no extra steps.

3. Final Answer:

   Use Git subtrees to copy the library into your project for simpler cloning. -> Option A

4. Quick Check:

   Subtrees simplify cloning by embedding code [OK]

Hint: Subtrees = easy clone; submodules = extra steps [OK]

Common Mistakes:

• Choosing submodules despite extra clone steps
• Ignoring subtree benefits for team convenience
• Thinking manual copy is better than Git methods