Adding a submodule in Git - Commands & Configuration

Introduction

Sometimes you want to include another project inside your project, but keep it separate. Git submodules let you add one Git repository inside another, so you can work on them independently but keep them linked.

When you want to include a shared library from another project without copying its files.

When your project depends on another project that changes independently.

When you want to keep a third-party tool inside your repository but update it separately.

When you want to track a specific version of another project inside your own.

When you want to collaborate on multiple related projects but keep their histories separate.

Commands

This command adds the external repository as a submodule inside the 'libs/shared-library' folder in your project. It links the other project without copying all files directly.

Terminal

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

Expected Output

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 100 (delta 2), reused 7 (delta 1), pack-reused 90

Receiving objects: 100% (100/100), 12.34 KiB | 1.23 MiB/s, done.

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

This saves the submodule addition in your main project’s history. It records the link to the other project’s specific commit.

Terminal

git commit -m "Add shared-library submodule"

Expected Output

[main abc1234] Add shared-library submodule

 1 file changed, 1 insertion(+)

 create mode 160000 libs/shared-library

This command downloads the submodule content and sets it up. Use it after cloning a project with submodules to get all linked projects.

Terminal

git submodule update --init --recursive

Expected Output

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 100 (delta 2), reused 7 (delta 1), pack-reused 90

Receiving objects: 100% (100/100), 12.34 KiB | 1.23 MiB/s, done.

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

→

--init - Initializes and clones the submodules.

→

--recursive - Also initializes nested submodules inside submodules.

Shows the current commit checked out in each submodule and their paths. Useful to verify submodules are set up correctly.

Terminal

git submodule status

Expected Output

 1a2b3c4d5e6f7g8h9i0j libs/shared-library (heads/main)

Key Concept

If you remember nothing else from this pattern, remember: a submodule links another Git project inside yours without mixing their files or histories.

Common Mistakes

Adding submodule but forgetting to commit the change

The link to the submodule won't be saved in your project history, so others won't know about it.

Always run 'git commit' after adding a submodule to save the link.

Cloning a project with submodules but not running 'git submodule update --init --recursive'

The submodule folders will be empty or missing, so the linked projects won't be available.

After cloning, always run 'git submodule update --init --recursive' to fetch all submodules.

Trying to edit submodule files without knowing it is a separate repository

Changes in submodules are separate and need their own commits and pushes, or they won't be saved.

Make changes inside submodules carefully, commit and push there separately, then update the main project.

Summary

Use 'git submodule add' to link another Git project inside your repository.

Commit the submodule addition to save the link in your project history.

Run 'git submodule update --init --recursive' after cloning to fetch all submodules.

Use 'git submodule status' to check which commits your submodules are on.