Updating submodules in Git - Commands & Configuration

Introduction

Sometimes a project uses other projects inside it, called submodules. Updating submodules means getting the latest changes from those smaller projects so your main project stays current.

When you clone a project that contains submodules and want to get their content.

When the submodule projects have new updates and you want to include them in your main project.

When you switch branches and the submodules need to update to match the branch.

When you want to check if submodules are out of date compared to their remote repositories.

Commands

This command initializes and fetches all submodules for the first time, including nested ones, so you have their files locally.

Terminal

git submodule update --init --recursive

Expected Output

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

Cloning into 'libs/example-lib'...

Submodule path 'libs/example-lib': checked out 'a1b2c3d4e5f6g7h8i9j0'

→

--init - Initializes submodules that are not yet initialized

→

--recursive - Also updates nested submodules inside submodules

This command fetches the latest commits from the remote repositories of all submodules and updates them to those commits.

Terminal

git submodule update --remote

Expected Output

Fetching submodule libs/example-lib

Submodule path 'libs/example-lib': checked out 'f1e2d3c4b5a697887766'

→

--remote - Updates submodules to the latest commit on their remote tracking branch

Check if the submodule update changed anything in your main project, so you can commit the updated submodule references.

Terminal

git status

Expected Output

On branch main

Changes not staged for commit:

  modified:   libs/example-lib (new commits)



no changes added to commit (use "git add" and/or "git commit -a")

Stage the updated submodule so you can commit the new submodule version in your main project.

Terminal

git add libs/example-lib

Expected Output

No output (command runs silently)

Commit the updated submodule reference to your main project repository.

Terminal

git commit -m "Update submodule libs/example-lib to latest"

Expected Output

[main abcdef1] Update submodule libs/example-lib to latest

 1 file changed, 1 insertion(+), 1 deletion(-)

Key Concept

If you remember nothing else from this pattern, remember: submodules are separate projects inside your project and need their own update commands to stay current.

Common Mistakes

Running 'git pull' only on the main project without updating submodules

This does not update the submodules to their latest commits, so your submodules stay outdated.

After pulling, run 'git submodule update --remote' to fetch and update submodules.

Forgetting to initialize submodules after cloning

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

Run 'git submodule update --init --recursive' right after cloning to get all submodule content.

Not committing the updated submodule references after updating

Your main project will not record the new submodule versions, causing confusion for others or on other machines.

Stage and commit the submodule changes with 'git add' and 'git commit' after updating.

Summary

Use 'git submodule update --init --recursive' to get submodules after cloning.

Use 'git submodule update --remote' to fetch and update submodules to their latest commits.

Always check 'git status' and commit updated submodule references to keep your main project consistent.