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.