Introduction

Sometimes you want to include one project inside another but keep them separate. Git submodules help by linking a nested repository inside a main repository, so you can work on both without mixing their files or histories.

When you want to include a shared library project inside your main project without copying its files.

When your project depends on another project that is developed separately and updated independently.

When you want to keep the history of the nested project separate but still track its version inside your main project.

When you want to clone a big project but only update parts of it selectively.

When you want to contribute to both the main project and the nested project but keep their codebases cleanly separated.

Commands

This command adds the shared-library repository as a submodule inside the libs/shared-library folder of your main project. It links the nested repo without copying all files directly.

Terminal

git submodule add https://github.com/example/shared-library.git libs/shared-library

Expected OutputExpected

Cloning into 'libs/shared-library'... remote: Enumerating objects: 10, done. remote: Counting objects: 100% (10/10), done. remote: Compressing objects: 100% (8/8), done. remote: Total 10 (delta 1), reused 10 (delta 1), pack-reused 0 Receiving objects: 100% (10/10), done. Resolving deltas: 100% (1/1), done.

This commits the change to your main project, recording the submodule link and the specific commit of the nested repo it points to.

Terminal

git commit -m "Add shared-library submodule"

Expected OutputExpected

[main abc1234] Add shared-library submodule 1 file changed, 1 insertion(+) create mode 160000 libs/shared-library

When cloning a project with submodules, this command clones the main project and automatically fetches all submodules so you get the full nested repos ready to use.

Terminal

git clone --recurse-submodules https://github.com/example/main-project.git

Expected OutputExpected

Cloning into 'main-project'... remote: Enumerating objects: 50, done. remote: Counting objects: 100% (50/50), done. remote: Compressing objects: 100% (30/30), done. remote: Total 50 (delta 10), reused 40 (delta 5), pack-reused 0 Receiving objects: 100% (50/50), done. Resolving deltas: 100% (10/10), done. Submodule 'libs/shared-library' (https://github.com/example/shared-library.git) registered for path 'libs/shared-library' Cloning into 'libs/shared-library'... remote: Enumerating objects: 10, done. remote: Counting objects: 100% (10/10), done. remote: Compressing objects: 100% (8/8), done. remote: Total 10 (delta 1), reused 10 (delta 1), pack-reused 0 Receiving objects: 100% (10/10), done. Resolving deltas: 100% (1/1), done.

→

--recurse-submodules - Fetch all submodules automatically when cloning

This command updates the submodules to the latest commit from their remote repositories, so you can keep nested repos current without mixing their code into the main project.

Terminal

git submodule update --remote

Expected OutputExpected

Submodule path 'libs/shared-library': checked out 'def5678'

→

--remote - Fetch latest commits from the submodule's remote repository

Key Concept

Git submodules let you include and track separate projects inside a main project without mixing their files or histories.

Common Mistakes

Cloning a repo with submodules without using --recurse-submodules

The nested repositories will not be cloned automatically, leaving empty folders or missing code.

Always clone with git clone --recurse-submodules to get all nested repos.

Editing files inside a submodule folder and committing only in the main repo

Changes inside the submodule are not tracked by the main repo and can be lost or cause confusion.

Commit changes inside the submodule repo separately, then update the main repo to point to the new submodule commit.

Deleting submodule folders manually without removing the submodule config

Git still tracks the submodule and can cause errors or confusion in the main repo.

Use git submodule deinit and remove the submodule entry properly before deleting files.

Summary

Use git submodule add to link a nested repository inside your main project without copying files.

Commit the submodule link in your main repo to track the specific version of the nested repo.

Clone projects with submodules using --recurse-submodules to get all nested repos automatically.

Update submodules separately to keep nested projects current without mixing their code.