Git Submodule Update: 2 Proven Steps For A Smooth Workflow (2025 Guide)

Q: What’s the difference between git submodule update and git pull --recurse-submodules?

pull --recurse-submodules fetches/merges the parent and attempts to update submodules accordingly. git submodule update explicitly aligns submodules to the parent’s recorded commits (or advances them with --remote).

Q: How do I switch a submodule to HTTPS (or SSH) everywhere?

Edit .gitmodules, run git submodule sync --recursive, then run a fresh Submodule Update. Update developer credentials if moving to SSH to avoid authentication errors.

Q: Is there a way to update all nested submodules at once?

Use --recursive with your update submodules commands, or run git submodule foreach --recursive '' to iterate through the entire tree.

If you’ve ever pulled the latest code only to find your dependencies are mysteriously out of sync, you’ve felt the pain that Git Submodule Update is designed to solve. Submodules allow you to pin one repository inside another at a specific commit. That precision is powerful—but it also means you must consciously update them when you want newer code.

In this guide, we’ll demystify the update of Git Submodule, show real-world workflows, explain the knobs and switches that matter, and share troubleshooting tactics so your team can collaborate without surprises.

TL;DR: A submodule is a repo inside your repo—submodule workflow update moves that embedded pointer forward (or realigns your working tree) so you stay in lockstep with upstream changes.

Table of Contents

What exactly is a submodule?

A submodule is an embedded Git repository referenced by your parent project at a specific commit. The parent repo stores:

A .gitmodules file (human-readable mapping of name → path → URL).
A special “gitlink” entry that points at a SHA in the submodule.

Because a submodule is pinned to a commit, you control precisely which version of a dependency your app uses. That’s awesome for reproducibility, but it means “latest” isn’t automatic—you run submodule synchronization when you want to align your working copy with what the parent expects or to advance the pointer to a newer upstream commit.

```ini
[submodule "ui-library"]
  path = libs/ui-library
  url  = https://github.com/acme/ui-library.git
```

Submodule basics: clone, init, and the first Submodule Update

If you’re new to a project with submodules:

Clone with recursion git clone --recurse-submodules <repo-url> This initializes and checks out all submodules right away. If you’ve already cloned: git submodule init git submodule update That Submodule Update aligns each submodule’s working tree to the commit expected by the parent.
Verify status git submodule status A - prefix usually means the submodule isn’t initialized; a + indicates your working tree differs from the recorded commit; and a space means it matches.
Pulling changes in the parent
If teammates update submodule pointers and push the parent repo, a normal git pull may leave your submodules outdated. Either run: git submodule update --init --recursive or pull with recursion: git pull --recurse-submodules Following up with Submodule Update ensures your tree matches the parent precisely.

(Want a refresher on fetch vs. pull and why recursion matters? See this clear comparison of Git Fetch vs Git Pull on The Code Mood for practical context.)

Two modes you’ll use with Git Submodule Update

There are two very different “update” intents:

Match the parent’s recorded commit (the default)

Running:

git submodule update

checks out the exact commit the parent repo has recorded. This is reproducibility mode: everyone builds against the same submodule version; CI stays deterministic; releases are predictable.

Track and fetch the latest from the submodule’s remote (`--remote`)

When you want to move forward to the newest code on a branch that your submodule tracks:

git submodule update --remote

Now refreshing submodules will fetch the submodule’s upstream and check out the tip of the configured branch (often main or master). After verifying that things still work, commit the new submodule SHA in the parent:

git add path/to/submodule
git commit -m "Advance submodule to latest on <branch>"
git push

This is an upgrade mode: you choose when to adopt changes, and your parent repository records that decision.

(If you’re doing this frequently, consider --remote --merge or --remote --rebase to pull in changes without losing local edits.)

Configure which branch `--remote` tracks

git config -f .gitmodules submodule.ui-library.branch main
git submodule sync --recursive

From now on, update submodules with --remote knows which branch to follow. This keeps your policy self-documenting inside the repo.

Everyday workflows that actually work

Locked dependency, occasional upgrades

Teammate bumps the submodule to a tested commit.
You pull, then run Submodule Update to match exactly: git pull --recurse-submodules git submodule update --init --recursive
Everyone builds the same artifact. Reproducibility wins.

Actively tracking upstream changes

You regularly run: git submodule update --remote --recursive
You verify the app still compiles and tests pass.
You commit the new SHA in the parent and push.

(Branch hygiene helps here—if you’re juggling multiple streams of work, Git Worktree can make managing parallel branches painless.)

Real-world example: advancing a submodule safely

Let’s say your repo has a submodule at libs/ui-library and you want the latest main.

# Start clean
git status
git submodule status

# Make sure the submodule is initialized and updated
git submodule update --init --recursive

# Advance to the newest commit on the tracked branch
git submodule update --remote libs/ui-library

# Run your build/tests here...

# Record the new submodule commit in the parent
git add libs/ui-library
git commit -m "Git Submodule Update: track latest ui-library on main"
git push

That commit you push updates the parent’s pointer so your whole team converges on the same version next pull.

Handling local changes inside a submodule

You’re in a submodule and you’ve made edits. Now what?

Commit in the submodule itself cd libs/ui-library git checkout -b fix/avatar-contrast # make changes git commit -m "Improve avatar contrast" git push origin fix/avatar-contrast
Update the parent to point to your new commit
Back at the parent: git add libs/ui-library git commit -m "Git Submodule Update: point to avatar contrast fix" git push

If you accidentally accumulate untracked files that block updates, a careful clean helps. (Here’s a guide to the Git Clean command for safely removing untracked files when a submodule refuses to update cleanly.)

Detached HEADs and other “gotchas”

Submodules often land in a detached HEAD when matching a specific commit. That’s normal. If you need to develop inside the submodule, create a branch:

cd libs/ui-library
git checkout -b feature/better-inputs

If you ever need to retarget a submodule to a different branch—or rename a branch you’re tracking—do it explicitly in .gitmodules and sync. (If branch names need changing in your workflow, here’s how to rename a Git branch safely without breaking remotes.)

Syncing URL or branch changes across machines

If the submodule’s remote URL or branch changes (say, you move from SSH to HTTPS), update .gitmodules and run:

git submodule sync --recursive
git submodule update --init --recursive

If your team runs into SSH key issues during an update, this walkthrough on fixing GitHub’s “Permission denied (publickey)” error can save time.

Undoing/redoing an update to submodules

Move the parent’s pointer back if a new version breaks your build:

# Check out an earlier parent commit that had the old submodule SHA
git checkout <good-parent-commit>

# Or hard-reset the parent pointer to a previous state (with care)
git reset --hard <good-parent-commit>

When you reset or re-point a submodule, you’re really just changing which commit the parent references. If you want a refresher on the implications, this guide to Git reset: hard vs soft clarifies what changes in your index vs working tree.

Got halfway through an upgrade and need to park changes? Naming stashes—even inside submodules—keeps things tidy; see how to use git stash list effectively when juggling updates.

CI/CD: pin, verify, promote

A robust pipeline for submodules usually:

Pins submodules at known commits in main for reproducible builds.
Uses a scheduled job that runs git submodule update --remote on a temporary branch, runs tests, and opens a PR.
Promotes the submodule bump by merging the PR once green.

This removes the human error from manual upgrades and keeps the submodule workflow update a deliberate, auditable step.

Advanced flags that matter

--init — Initialize uninitialized submodules before updating. Handy after fresh clones.
--recursive — descend into nested submodules.
--remote — fetch and check out the tip of the tracked branch.
--merge/--rebase — If you have local edits in a submodule, try to integrate remote updates without discarding work.
--jobs <n> — parallelize updates for faster CI.

You can also run commands across all submodules:

git submodule foreach --recursive 'git status'

This is useful before and after a Submodule Update to confirm there’s no stray state.

Submodule vs subtree (and when to pick each)

Submodule: You want a dependency at an exact commit, updated only when you choose. Clean separation, separate history, super reproducible. Updating submodules is the lever to advance.
Subtree: You want code copied into your repo, merged like normal changes. Easier for teams unfamiliar with submodules, but heavier history in the parent.

Neither is “better” universally; submodules shine for library-style dependencies with distinct lifecycle/release cadence.

Practical troubleshooting checklist

If the submodule workflow update fails or leaves you puzzled:

Is it initialized?
git submodule init then git submodule update --recursive.
Dirty working tree inside submodule?
Commit or stash local changes; then re-run the update. If untracked files block you, the Git Clean guide shows safe cleanups.
Wrong URL or branch?
Fix .gitmodules, run git submodule sync --recursive.
Permissions?
If you see SSH key errors, resolve the public key problem before retrying.
Need to move changes across branches?
When a submodule bump landed on the wrong branch in the parent, moving that commit is straightforward—here’s how to move a commit to another branch without losing work.

With these in your toolkit, refreshing submodules becomes routine rather than risky.

Putting it all together

The fastest path to confidence is repetition:

Clone with --recurse-submodules.
Use Git Submodule Update to match what the parent expects.
When ready, use --remote it to bring in the newest upstream commits, test, and record the new SHA.
Keep .gitmodules accurate, sync often, and automate upgrades via CI.

Treat refreshing submodules as a conscious, reviewable change—not a mystery byproduct of pull—and your entire team will enjoy reliable builds, consistent deployments, and dependencies that behave exactly as you expect.

FAQ

Because the parent pins a specific commit. That commit may not correspond to a branch tip. Create a new branch inside the submodule if you need to develop there.

Yes—advancing to a new commit changes the submodule pointer in the parent. Stage the submodule path and commit so teammates get the same version.

pull --recurse-submodules fetches/merges the parent and attempts to update submodules accordingly. git submodule update explicitly aligns submodules to the parent’s recorded commits (or advances them with --remote).

Edit .gitmodules, run git submodule sync --recursive, then run a fresh Submodule Update. Update developer credentials if moving to SSH to avoid authentication errors.

Yes—check out the desired tag in the submodule, then commit the resulting SHA in the parent. The parent always records a commit; tags simply help you choose which commit.

Use --recursive with your update submodules commands, or run git submodule foreach --recursive '<command>' to iterate through the entire tree.