Adding a submodule in Git - Step-by-Step Execution

Process Flow - Adding a submodule

Start in main repo

↓

Run git submodule add <url> <path>

↓

Git clones submodule repo into <path>

↓

Git records submodule info in .gitmodules

↓

Stage .gitmodules and submodule path

↓

Commit changes

↓

Submodule added successfully

This flow shows how adding a submodule clones another repo inside your repo, records it, stages, and commits the change.

Execution Sample

Git

git submodule add https://github.com/example/lib.git libs/lib
git commit -m "Add lib submodule"

Adds a submodule from a remote repo into the 'libs/lib' folder and commits the change.

Process Table

Step	Command	Action	Result
1	git submodule add https://github.com/example/lib.git libs/lib	Clone submodule repo into libs/lib, update .gitmodules, and automatically stage changes	Submodule repo cloned; .gitmodules updated with submodule info; changes staged
2	git status	Check staged changes	.gitmodules and libs/lib show as staged new changes
3	git commit -m "Add lib submodule"	Commit staged changes	Commit created with submodule addition
4	git status	Verify clean working directory	No changes, working tree clean
5	git submodule status	Verify submodule status	Shows libs/lib (commit hash); submodule tracked correctly

💡 Submodule added and committed; working directory clean

Status Tracker

Variable	Start	After Step 1	After Step 3	After Step 4	Final
.gitmodules	does not exist	created with submodule info, staged	committed	committed	present in repo
libs/lib folder	does not exist	cloned submodule repo, staged	committed	committed	tracked as submodule

Key Moments - 3 Insights

Why do we need to commit after adding a submodule?

Because adding a submodule changes the .gitmodules file and adds a folder, these changes must be committed to record the submodule in the main repo (see execution_table step 3).

What does the .gitmodules file do?

It stores the URL and path info of the submodule so Git knows where to fetch it from later (see variable_tracker for .gitmodules creation at step 1).

Is the submodule content stored inside the main repo?

No, the submodule is a separate Git repo cloned inside a folder; the main repo tracks only the commit reference and path (see execution_table step 1 and variable_tracker for libs/lib folder).

Visual Quiz - 3 Questions

Look at the execution table, what happens at step 1?

A The working directory is cleaned

B The submodule is committed

C The submodule repo is cloned and .gitmodules is updated

D The submodule is removed

💡 Hint

Check the 'Action' and 'Result' columns in execution_table row 1

At which step are the submodule changes staged for commit?

A Step 4

B Step 1

C Step 3

D Step 5

💡 Hint

Check the 'Action' and 'Result' columns in execution_table row 1

If you forget to commit after adding a submodule, what will happen?

A The submodule will not be recorded in the main repo

B The submodule will be fully integrated automatically

C Git will delete the submodule folder

D The .gitmodules file will be removed

💡 Hint

Refer to key_moments about why committing is necessary

Concept Snapshot

git submodule add <repo_url> <path>
- Clones a repo inside your repo as a submodule
- Updates .gitmodules with submodule info
- Automatically stages .gitmodules and submodule folder; commit changes
- Submodule is tracked as a separate repo inside your repo

Full Transcript

Adding a submodule in Git means including another Git repository inside your main repository. You run 'git submodule add' with the repo URL and path. Git clones the submodule repo into the specified folder and updates a file called .gitmodules to record this. The changes are automatically staged. You then commit these changes to save the submodule info in your main repo. This process keeps the submodule as a separate project inside your repo, tracked by its commit reference. Remember to commit after adding, or the submodule won't be recorded properly.

Practice

1. What is the main purpose of adding a submodule in a Git project?

easy

A. To merge two Git repositories into one history

B. To create a backup of the current repository

C. To delete a folder from the Git repository

D. To include another Git repository inside your project as a separate component

Solution

1. Step 1: Understand what a submodule is

   A submodule is a way to include another Git repository inside your own project without merging histories.

2. Step 2: Identify the purpose of adding a submodule

   It allows managing related projects separately but linked inside your main project.

3. Final Answer:

   To include another Git repository inside your project as a separate component -> Option D

4. Quick Check:

   Submodule = separate included repo [OK]

Hint: Submodule means adding a separate repo inside yours [OK]

Common Mistakes:

• Thinking submodule merges histories
• Confusing submodule with backup
• Assuming submodule deletes files

2. Which of the following is the correct command to add a submodule from URL https://github.com/example/lib.git into folder lib?

easy

A. git clone submodule https://github.com/example/lib.git lib

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

C. git submodule init https://github.com/example/lib.git lib

D. git add submodule https://github.com/example/lib.git lib

Solution

1. Step 1: Recall the syntax for adding a submodule

   The correct syntax is git submodule add <url> [path].

2. Step 2: Match the command with the syntax

   git submodule add https://github.com/example/lib.git lib matches the syntax exactly with the URL and folder path.

3. Final Answer:

   git submodule add https://github.com/example/lib.git lib -> Option B

4. Quick Check:

   Use 'git submodule add URL path' [OK]

Hint: Use 'git submodule add URL path' to add submodules [OK]

Common Mistakes:

• Using 'git add submodule' instead of 'git submodule add'
• Confusing 'init' with 'add'
• Trying to clone submodule like a normal repo

3. After running git submodule add https://github.com/example/tool.git tools, what will be the output of git status?

medium

A. Shows new submodule 'tools' added and staged for commit

B. Shows new file 'tools' as untracked

C. Shows no changes

D. Shows error: submodule path 'tools' already exists

Solution

1. Step 1: Understand what happens after adding a submodule

   Adding a submodule creates a new entry in the .gitmodules file and stages the submodule folder.

2. Step 2: Check git status behavior

   Git status will show the new submodule as added and staged for commit, not untracked or error.

3. Final Answer:

   Shows new submodule 'tools' added and staged for commit -> Option A

4. Quick Check:

   Submodule add = staged submodule [OK]

Hint: After adding, submodule shows staged in git status [OK]

Common Mistakes:

• Expecting submodule folder as untracked
• Thinking no changes appear after add
• Assuming error if folder exists without checking

4. You ran git submodule add https://github.com/example/lib.git lib but got the error: fatal: destination path 'lib' already exists and is not an empty directory. What should you do to fix this?

medium

A. Use git submodule add --force to overwrite

B. Run git submodule update --init instead

C. Delete or move the existing 'lib' folder before adding the submodule

D. Rename the submodule URL to a different repository

Solution

1. Step 1: Understand the error cause

   The error means the target folder 'lib' already exists and is not empty, so Git refuses to add the submodule there.

2. Step 2: Fix by clearing the folder

   To add the submodule, you must delete or move the existing 'lib' folder so Git can create the submodule folder cleanly.

3. Final Answer:

   Delete or move the existing 'lib' folder before adding the submodule -> Option C

4. Quick Check:

   Remove existing folder to add submodule [OK]

Hint: Remove existing folder before adding submodule [OK]

Common Mistakes:

• Trying to force add without clearing folder
• Using update/init instead of add
• Changing URL instead of fixing folder

5. You want to add a submodule but keep it in a different folder name than the repository's default. Which command correctly adds the submodule from https://github.com/example/utils.git into folder tools/utils?

hard

A. git submodule add https://github.com/example/utils.git tools/utils

B. git submodule add tools/utils https://github.com/example/utils.git

C. git submodule init https://github.com/example/utils.git tools/utils

D. git clone https://github.com/example/utils.git tools/utils

Solution

1. Step 1: Recall submodule add syntax

   The syntax is git submodule add <url> [path], where path is the folder name you want.

2. Step 2: Apply to given URL and folder

   git submodule add https://github.com/example/utils.git tools/utils correctly uses the URL first, then the custom folder path 'tools/utils'.

3. Final Answer:

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

4. Quick Check:

   URL first, then folder path [OK]

Hint: URL first, then custom folder path in submodule add [OK]

Common Mistakes:

• Swapping URL and folder arguments
• Using init instead of add
• Using clone instead of submodule add