How to Update Git Submodules to Latest Commits

In this tutorial, you'll learn about How to Update Git Submodules to Latest Commits. We cover key concepts, practical examples, and best practices.

The Problem

Your project uses git submodules, and the submodules point to old commits. Running git pull on the parent repository doesn't update submodules automatically. You need to fetch and update each submodule to the latest commit on its tracked branch. Submodules are pinned to specific commits — updating them requires a separate step, and forgetting to do so leads to inconsistencies between environments.

Quick Fix

1. Update all submodules to latest remote commit

git submodule update --remote

This fetches the latest commit from each submodule's default remote branch (usually main or master). The parent repo now shows modified submodule references.

2. Check what changed

git diff --submodule

Expected output:

Submodule shared-lib abc1234..def5678:
  > Add new authentication helper
  > Fix timeout in retry logic

Shows the commit range and the messages of new commits in the submodule.

3. Commit the updated submodule references

git add .
git commit -m "Update submodules to latest"
git push

The parent repository records the new submodule commit hashes. Teammates who pull will get the updated references.

4. Update a specific submodule

git submodule update --remote shared-lib

Replace shared-lib with the submodule path. This updates only that submodule instead of all of them.

5. Initialize and update submodules after cloning

git clone --recurse-submodules https://github.com/user/repo.git

If you already cloned without --recurse-submodules:

git submodule update --init --recursive

The --recursive flag handles nested submodules (submodules within submodules).

6. Set a submodule to track a specific branch

git config -f .gitmodules submodule.shared-lib.branch develop
git submodule update --remote

This tells git submodule update --remote to pull from the develop branch instead of the default.

7. Pull latest changes for parent and submodules in one step

git pull --recurse-submodules

This pulls the latest parent changes and updates submodules to the commits recorded in the pulled parent commit. To also fetch latest remote submodule changes:

git pull --recurse-submodules && git submodule update --remote

8. Update submodules recursively (nested submodules)

git submodule update --init --recursive --remote

For projects with submodules that themselves contain submodules, the --recursive flag ensures the entire tree is updated.

Prevention

• Use git clone --recurse-submodules when first cloning a repo with submodules to fetch everything in one step
• Commit submodule updates separately from code changes for clean history
• Set submodules to track specific branches so --remote behaves predictably
• Run git status after updating submodules to verify the change
• Use git submodule status to quickly see which commits each submodule points to
• Add a CI check that runs git submodule status --recursive to catch outdated submodules
• Document which submodules are used and what they provide in the project README