Cloning with submodules in Git - Commands & Configuration

Introduction

Sometimes a project uses other projects inside it, called submodules. Cloning with submodules means copying the main project and also getting these smaller projects automatically. This saves time and keeps everything working together.

When you want to copy a project that includes other projects inside it.

When you need to work on a project that depends on specific versions of other projects.

When you want to keep the main project and its submodules in sync.

When you want to avoid manually downloading each submodule separately.

When you want to ensure your project builds correctly with all its parts.

Commands

This command clones the main project and automatically downloads all its submodules. It saves you from running extra commands later.

Terminal

git clone --recurse-submodules https://github.com/example-user/example-repo.git

Expected Output

Cloning into 'example-repo'...

remote: Enumerating objects: 100, done.

remote: Counting objects: 100% (100/100), done.

remote: Compressing objects: 100% (80/80), done.

remote: Total 100 (delta 20), reused 90 (delta 10), pack-reused 0

Receiving objects: 100% (100/100), 1.2 MiB | 1.0 MiB/s, done.

Resolving deltas: 100% (20/20), done.

Submodule 'libs/lib1' (https://github.com/example-user/lib1.git) registered for path 'libs/lib1'

Submodule 'libs/lib2' (https://github.com/example-user/lib2.git) registered for path 'libs/lib2'

Cloning into 'libs/lib1'...

Cloning into 'libs/lib2'...

→

--recurse-submodules - Clones the main repo and all its submodules in one step

Change directory into the cloned project folder to work inside it.

Terminal

cd example-repo

Expected Output

No output (command runs silently)

If you cloned without --recurse-submodules, this command downloads and initializes all submodules manually.

Terminal

git submodule update --init --recursive

Expected Output

Submodule 'libs/lib1' (https://github.com/example-user/lib1.git) registered for path 'libs/lib1'

Cloning into 'libs/lib1'...

Submodule 'libs/lib2' (https://github.com/example-user/lib2.git) registered for path 'libs/lib2'

Cloning into 'libs/lib2'...

→

--init - Initializes submodules that are not yet cloned

→

--recursive - Also updates submodules inside submodules

Shows the current commit checked out for each submodule to verify they are present and correct.

Terminal

git submodule status

Expected Output

 1a2b3c4d5e6f7g8h9i0j libs/lib1 (heads/main)

 0j9i8h7g6f5e4d3c2b1a libs/lib2 (heads/main)

Key Concept

If you remember nothing else from this pattern, remember: use --recurse-submodules when cloning to get all parts of the project at once.

Common Mistakes

Cloning a repo with submodules without --recurse-submodules and not running git submodule update later.

The submodules folders will be empty or missing code, causing build or runtime errors.

Always clone with --recurse-submodules or run git submodule update --init --recursive after cloning.

Forgetting to update submodules after switching branches or pulling changes.

Submodules may point to old commits, causing mismatches and bugs.

Run git submodule update --recursive after changing branches or pulling.

Summary

Use git clone --recurse-submodules to clone a project and all its submodules in one step.

If you forget the flag, run git submodule update --init --recursive to get submodules later.

Check submodule status with git submodule status to confirm they are correctly set up.

Practice

1. What does the command git clone --recurse-submodules <repo_url> do?

easy

A. Clones the main repository and all its submodules in one step

B. Clones only the main repository without any submodules

C. Updates submodules after cloning the main repository

D. Removes submodules from the cloned repository

Solution

1. Step 1: Understand the purpose of --recurse-submodules

   The option tells Git to clone the main repo and all submodules recursively in one command.

2. Step 2: Compare with cloning without this option

   Without it, only the main repo is cloned; submodules need separate commands to fetch.

3. Final Answer:

   Clones the main repository and all its submodules in one step -> Option A

4. Quick Check:

   --recurse-submodules = clone main + submodules [OK]

Hint: Use --recurse-submodules to clone all at once [OK]

Common Mistakes:

• Thinking it clones only the main repo
• Confusing update with clone
• Assuming it removes submodules

2. Which of the following is the correct command to clone a repository along with its submodules?

easy

A. git clone --update-submodules https://example.com/repo.git

B. git clone --init-submodules https://example.com/repo.git

C. git clone --recurse-submodules https://example.com/repo.git

D. git clone --submodule-update https://example.com/repo.git

Solution

1. Step 1: Identify the correct flag for cloning with submodules

   The correct flag is --recurse-submodules to clone main repo and submodules together.

2. Step 2: Check other options for validity

   Options --init-submodules, --update-submodules, and --submodule-update are not valid git clone flags.

3. Final Answer:

   git clone --recurse-submodules https://example.com/repo.git -> Option C

4. Quick Check:

   --recurse-submodules is the correct clone flag [OK]

Hint: Remember: clone with --recurse-submodules for submodules [OK]

Common Mistakes:

• Using non-existent flags like --init-submodules
• Mixing update commands with clone
• Misspelling the flag

3. After cloning a repository without --recurse-submodules, you run git submodule update --init --recursive. What is the expected result?

medium

A. Submodules are initialized and updated to the correct commit

B. The main repository is recloned

C. Submodules are deleted from the repository

D. Nothing happens because submodules are not cloned

Solution

1. Step 1: Understand the command purpose

   The command initializes submodules and updates them recursively to the commit recorded in the main repo.

2. Step 2: Clarify what happens after cloning without submodules

   Submodules are present as empty folders; this command fetches their content properly.

3. Final Answer:

   Submodules are initialized and updated to the correct commit -> Option A

4. Quick Check:

   git submodule update --init --recursive = fetch submodules [OK]

Hint: Use update --init --recursive to fetch missing submodules [OK]

Common Mistakes:

• Thinking it reclones the main repo
• Assuming submodules get deleted
• Believing nothing happens without --recurse-submodules

4. You cloned a repository with submodules but forgot to use --recurse-submodules. Running git submodule update --init gives an error. What is the most likely cause?

medium

A. The main repository was cloned with --recurse-submodules

B. The submodule URLs are missing or incorrect in .gitmodules

C. You need to delete the main repository and reclone

D. Submodules cannot be initialized after cloning

Solution

1. Step 1: Analyze the error cause

   If submodule URLs in .gitmodules are missing or wrong, update --init fails to fetch them.

2. Step 2: Check other options for correctness

   The main repository was cloned with --recurse-submodules is false because main repo was cloned without --recurse-submodules; C and D are incorrect as recloning or inability to init is not required.

3. Final Answer:

   The submodule URLs are missing or incorrect in .gitmodules -> Option B

4. Quick Check:

   Missing or wrong URLs cause submodule init errors [OK]

Hint: Check .gitmodules URLs if submodule update fails [OK]

Common Mistakes:

• Assuming recloning is always needed
• Thinking submodules can't be initialized later
• Ignoring .gitmodules configuration

5. You cloned a repository with nested submodules but only ran git submodule update --init. What is the best command to ensure all nested submodules are also initialized and updated?

hard

A. git submodule update --recursive

B. git submodule init --recursive

C. git clone --recurse-submodules

D. git submodule update --init --recursive

Solution

1. Step 1: Understand nested submodules

   Nested submodules require recursive initialization and update to fetch all levels.

2. Step 2: Identify the correct command

   The command with both --init and --recursive flags initializes and updates all nested submodules properly.

3. Step 3: Check other options

   git submodule update --recursive misses --init, C is for cloning not updating, D is invalid syntax.

4. Final Answer:

   git submodule update --init --recursive -> Option D

5. Quick Check:

   Use --init --recursive to update nested submodules [OK]

Hint: Add --init --recursive to update all nested submodules [OK]

Common Mistakes:

• Forgetting --init when updating submodules
• Using clone commands after cloning
• Using invalid flags like --recursive with init only