Submodule status and sync in Git - Commands & Configuration

Introduction

When you use a project inside another project, called a submodule, you need to keep track of its exact version. Checking the submodule status and syncing it ensures your main project uses the right code from the submodule.

When you clone a project that contains submodules and want to check if they are initialized and up to date.

When you want to update your submodules to the latest commit recorded in the main project.

When you have changed the submodule commit in the main project and want to sync your local submodule to that commit.

When you want to verify if your submodules are on the correct commit or if they have local changes.

When you want to fetch and update all submodules recursively after pulling changes in the main project.

Commands

This command shows the current commit checked out in each submodule and whether it matches the commit recorded in the main project.

Terminal

git submodule status

Expected Output

 1a2b3c4d5e6f7g8h9i0jklmnopqrstuvwx submodule-folder (heads/main)

-1234567890abcdef1234567890abcdef12345678 submodule-folder2 (new commits)

This command updates the local configuration of submodules to match the URLs and paths recorded in the main project. Use it after changing submodule URLs.

Terminal

git submodule sync

Expected Output

No output (command runs silently)

This command initializes any uninitialized submodules and updates all submodules recursively to the commit recorded in the main project.

Terminal

git submodule update --init --recursive

Expected Output

Submodule 'submodule-folder' (https://github.com/example/repo.git) registered for path 'submodule-folder'

Cloning into 'submodule-folder'...

Submodule path 'submodule-folder': checked out '1a2b3c4d5e6f7g8h9i0jklmnopqrstuvwx'

→

--init - Initialize submodules that are not yet initialized

→

--recursive - Apply the update to nested submodules inside submodules

This command fetches the latest commits from the submodule remote repositories and updates the submodules to those commits.

Terminal

git submodule update --remote

Expected Output

Submodule path 'submodule-folder': checked out 'abcdef1234567890abcdef1234567890abcdef12'

→

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

Key Concept

If you remember nothing else, remember: git submodule status shows where submodules are, and git submodule update --init --recursive syncs them to the right commits.

Common Mistakes

Running git submodule update without --init after cloning a repo with submodules

The submodules are not initialized yet, so the update does nothing and submodules remain empty.

Run git submodule update --init --recursive to initialize and update all submodules.

Not running git submodule sync after changing submodule URLs in .gitmodules

Local git config still points to old URLs, so updates or clones fail or use wrong sources.

Run git submodule sync to update local config to match .gitmodules.

Ignoring submodule status output and assuming submodules are always up to date

Submodules may be on different commits or have local changes, causing build or runtime errors.

Regularly check git submodule status and update submodules as needed.

Summary

Use git submodule status to see the current commit of each submodule and if they match the main project.

Run git submodule update --init --recursive to initialize and sync submodules to the correct commits.

Use git submodule sync after changing submodule URLs to update local configuration.