Why submodules manage nested repos in Git - Visual Breakdown

Process Flow - Why submodules manage nested repos

Main Repo

↓

Add Submodule

↓

Submodule Repo Cloned

↓

Main Repo Tracks Submodule Commit

↓

Update Submodule Separately

↓

Commit Submodule Change in Main Repo

Shows how a main git repo adds and tracks a nested repo as a submodule, managing its commit separately.

Execution Sample

Git

git submodule add https://github.com/example/lib.git libs/lib
cd libs/lib
git checkout v1.0
cd ../..
git commit -am "Add lib submodule at v1.0"

Adds a nested repo as a submodule, checks out a version, then commits the submodule reference in the main repo.

Process Table

Step	Action	Result	Main Repo State	Submodule State
1	Run 'git submodule add https://github.com/example/lib.git libs/lib'	Submodule cloned into libs/lib	Tracks submodule path and commit	Cloned at HEAD of default branch
2	cd libs/lib	Enter submodule directory	No change	Inside submodule repo
3	git checkout v1.0	Submodule checked out at tag v1.0	No change	Detached HEAD at v1.0
4	cd ../..	Return to main repo root	No change	No change
5	git commit -am "Add lib submodule at v1.0"	Main repo records submodule commit	Submodule commit recorded in .gitmodules and index	No change
6	Later, update submodule	Submodule can be updated independently	Main repo must commit updated submodule commit	Submodule can move to new commit
7	Exit	Process complete	Main repo tracks specific submodule commit	Submodule is nested repo managed separately

💡 Submodule manages nested repo commit separately; main repo tracks submodule commit reference.

Status Tracker

Variable	Start	After Step 1	After Step 3	After Step 5	Final
Main Repo .gitmodules	empty	contains submodule path and URL	no change	tracked submodule commit	tracked submodule commit
Submodule Commit	none	cloned at HEAD	checked out v1.0 tag	no change	can update independently

Key Moments - 3 Insights

Why does the main repo track a specific commit of the submodule?

Because the main repo records the exact commit of the submodule it uses, ensuring consistent versions (see execution_table step 5).

Can you update the submodule independently from the main repo?

Yes, you can update the submodule repo separately, but you must commit the new submodule commit in the main repo to track the change (see execution_table step 6).

What happens if you don't commit the submodule update in the main repo?

The main repo will still point to the old submodule commit, causing version mismatch (see execution_table step 6 and exit_note).

Visual Quiz - 3 Questions

Look at the execution_table at step 3, what is the submodule state?

A Cloned at HEAD of default branch

B Detached HEAD at tag v1.0

C Submodule commit recorded in main repo

D No submodule present

💡 Hint

Check the 'Submodule State' column at step 3 in execution_table.

At which step does the main repo record the submodule commit?

A Step 1

B Step 3

C Step 5

D Step 6

💡 Hint

Look at the 'Main Repo State' column for when the commit happens in execution_table.

If you update the submodule but do not commit in the main repo, what happens?

A Main repo tracks old submodule commit causing mismatch

B Main repo tracks new submodule commit automatically

C Submodule is deleted

D Main repo breaks and cannot commit

💡 Hint

Refer to key_moments about committing submodule updates and execution_table step 6.

Concept Snapshot

Git submodules let you include a nested repo inside a main repo.
You add a submodule with 'git submodule add <url> <path>'.
The main repo tracks a specific commit of the submodule.
You update submodules separately and commit their new commit in main repo.
This keeps nested repos versions consistent and manageable.

Full Transcript

This visual execution shows how git submodules manage nested repositories. First, you add a submodule to your main repo, which clones the nested repo inside a folder. Then you can checkout a specific commit or tag in the submodule. The main repo tracks this exact commit in its .gitmodules and index. Later, you can update the submodule independently, but you must commit the new submodule commit in the main repo to keep versions consistent. If you don't commit the update, the main repo still points to the old submodule commit, causing mismatch. This process helps manage nested repos clearly and safely.

Practice

1. Why do Git submodules help when you want to include another repository inside your project?

easy

A. They merge the nested repository's history into the main project.

B. They keep the nested repository separate with its own history.

C. They copy all files from the nested repository permanently.

D. They delete the nested repository after adding it.

Solution

1. Step 1: Understand submodule purpose

   Git submodules allow you to include another repository inside your project but keep it separate.

2. Step 2: Recognize history separation

   This means the nested repo keeps its own commit history and does not merge with the main project.

3. Final Answer:

   They keep the nested repository separate with its own history. -> Option B

4. Quick Check:

   Submodules keep histories separate = A [OK]

Hint: Submodules keep nested repos separate, not merged [OK]

Common Mistakes:

• Thinking submodules merge histories
• Assuming submodules copy files permanently
• Believing submodules delete nested repos

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

easy

A. git submodule add https://github.com/example/repo.git

B. git add submodule https://github.com/example/repo.git

C. git clone submodule https://github.com/example/repo.git

D. git submodule clone https://github.com/example/repo.git

Solution

1. Step 1: Recall submodule add syntax

   The correct command to add a submodule is git submodule add <repo-url>.

2. Step 2: Check options for correct syntax

   Only git submodule add https://github.com/example/repo.git matches this syntax exactly.

3. Final Answer:

   git submodule add https://github.com/example/repo.git -> Option A

4. Quick Check:

   Use 'git submodule add' to add submodules = C [OK]

Hint: Add submodules with 'git submodule add' command [OK]

Common Mistakes:

• Using 'git add submodule' which is invalid
• Trying 'git clone submodule' which is not a command
• Confusing 'git submodule clone' which doesn't exist

3. What is the output of running git submodule update --init after cloning a repository with submodules?

medium

A. It lists all submodules without downloading them.

B. It deletes all submodule directories from the project.

C. It fetches and checks out the submodule repositories at the recorded commit.

D. It merges submodule commits into the main repository.

Solution

1. Step 1: Understand 'git submodule update --init'

   This command downloads the submodule repositories and checks out the commit recorded in the main repo.

2. Step 2: Compare options with command behavior

   Only It fetches and checks out the submodule repositories at the recorded commit. correctly describes this behavior; others describe incorrect actions.

3. Final Answer:

   It fetches and checks out the submodule repositories at the recorded commit. -> Option C

4. Quick Check:

   'git submodule update --init' fetches submodules = D [OK]

Hint: Update and initialize submodules with 'git submodule update --init' [OK]

Common Mistakes:

• Thinking it deletes submodules
• Assuming it merges submodule commits
• Believing it only lists submodules

4. You cloned a repository with submodules but forgot to run git submodule update --init. What problem will you face?

medium

A. The submodule folders will be empty or missing files.

B. The main repository will not clone properly.

C. The submodules will automatically update without any command.

D. The repository will merge submodule commits automatically.

Solution

1. Step 1: Understand cloning with submodules

   When cloning, submodule folders exist but are empty until you initialize and update them.

2. Step 2: Identify the effect of missing update

   Without running git submodule update --init, submodule content is not fetched, so folders are empty or incomplete.

3. Final Answer:

   The submodule folders will be empty or missing files. -> Option A

4. Quick Check:

   Missing 'git submodule update --init' causes empty submodule folders = B [OK]

Hint: Always run 'git submodule update --init' after cloning repos with submodules [OK]

Common Mistakes:

• Expecting submodules to auto-update
• Thinking main repo cloning fails
• Assuming submodules merge automatically

5. You want to update a submodule to a newer commit and push this change to the main repository. Which sequence of commands is correct?

hard

A. cd submodule_dir; git pull; git merge main; git push

B. git submodule update --init; git commit -m 'Update submodule'; git push

C. git clone submodule_dir; git push; git commit -m 'Update submodule'

D. cd submodule_dir; git checkout new_commit; cd ..; git add submodule_dir; git commit -m 'Update submodule'; git push

Solution

1. Step 1: Update submodule commit

   Navigate into the submodule directory and checkout the desired new commit.

2. Step 2: Stage and commit submodule change in main repo

   Return to main repo, add the submodule directory change, commit with a message, then push.

3. Final Answer:

   cd submodule_dir; git checkout new_commit; cd ..; git add submodule_dir; git commit -m 'Update submodule'; git push -> Option D

4. Quick Check:

   Update submodule commit then commit in main repo = A [OK]

Hint: Update submodule inside folder, then commit main repo change [OK]

Common Mistakes:

• Trying to update submodule without committing main repo
• Running 'git submodule update --init' instead of checkout
• Confusing clone with update commands