Pinning and updating Git submodules safely

A submodule bump is the least reviewable change in Git. The diff is two hexadecimal strings; the actual change — a security patch, a rewrite, a new transitive dependency — is in another repository that the reviewer probably has not cloned. That asymmetry is why dependency updates get approved unread, and it is entirely fixable with configuration and a short habit. This recipe is the day-to-day practice behind Submodule & Dependency Integrity.

When to use this approach

  • Your repository has submodules and their bumps are currently approved without discussion.
  • A dependency update has landed unnoticed inside an unrelated pull request.
  • You need an audit trail of which upstream version was in use when, and why it changed.
  • The dependency is signed upstream, so verification is available and should be enforced — see Commit Verification Gates.
  • If instead the dependency is vendored rather than a submodule, the equivalent discipline is a recorded digest and drift check.

Step 1 — Make submodule changes visible

Two configuration keys change what a reviewer and a committer actually see. Set them in the repository so everyone gets them.

# Show upstream commit subjects in diffs instead of raw SHAs
git config diff.submodule log

# Surface submodule state in ordinary status output
git config status.submoduleSummary true

# Commit them so the whole team benefits
git config -f .gitconfig-shared diff.submodule log

What changed: git diff on a pin bump now prints the upstream commit subjects between the two SHAs, and git status mentions a submodule whose HEAD has moved before you commit it by accident.

# See the difference immediately
git -C vendor/libfoo checkout HEAD~3
git diff                 # now lists the three upstream commits by subject
git submodule update     # put it back
The same bump, before and after diff.submodule=logWith the default setting a pin bump shows only the old and new subproject SHAs, which tells a reviewer nothing. With diff.submodule set to log, the same change lists the upstream commit subjects in the range, so a security fix is distinguishable from an unrelated refactor.default — diff.submodule = short-Subproject commit b2c3d4e5f6a7…+Subproject commit 9a8b7c6d5e4f…nothing here distinguishes a CVE fixfrom a six-month jump across a rewritediff.submodule = logSubmodule vendor/libfoo b2c3d4e..9a8b7c6:> fix: reject oversized frame headers> chore: bump minimum toolchain> feat: add streaming decoder… 2 morea reviewer can now ask a real questionone config line; it changes dependency review from a rubber stamp into a decision

Step 2 — Fetch and read the upstream range

Never move the pin and read the change in the same motion. Fetch first, read, then decide.

# 1. Bring upstream history in without touching the pin
git -C vendor/libfoo fetch origin --tags

# 2. What exactly would change?
git -C vendor/libfoo log --oneline HEAD..origin/main
git -C vendor/libfoo diff --stat HEAD..origin/main

# 3. Anything security-relevant in the range?
git -C vendor/libfoo log HEAD..origin/main --grep='CVE\|security\|overflow' -i

What changed: nothing in your repository — the pin is untouched. You now know what adopting the new tip would mean.

# Confirm the pin has not moved while you were reading
git status --short vendor/libfoo   # expect no output

Step 3 — Move the pin in a commit that does nothing else 

# 1. Choose an explicit target — a tag, not a branch tip
git -C vendor/libfoo checkout v3.3.0

# 2. Verify it before adopting it
git -C vendor/libfoo verify-tag v3.3.0
git -C vendor/libfoo log -1 --format='%G? %GS'      # expect: G <trusted signer>

# 3. Stage only the gitlink
git add vendor/libfoo
git status --short                                   # expect exactly one changed path

# 4. Record the provenance the diff cannot carry
git commit -m "deps: bump libfoo to v3.3.0

Range:  b2c3d4e..9a8b7c6 (5 commits)
Notable: fix for oversized frame headers (upstream #482)
Tag:    v3.3.0, signature verified against allowed_signers
Risk:   streaming decoder is new but not enabled by our config"

What changed: the superproject now points at a verified upstream release, and the commit message contains everything a reviewer — or someone reading git log in two years — needs.

git show --stat HEAD          # exactly one path changed: the gitlink
git rev-parse HEAD:vendor/libfoo    # matches the SHA of v3.3.0

SAFETY WARNING — never bundle a dependency bump with feature work. If the bump introduces a regression, reverting a mixed commit means reverting the feature too, and the bisect that finds the regression will land on a commit that changed twenty files. A pin bump should be a one-path commit that can be reverted in isolation, which is the same argument that governs revert versus reset.

Step 4 — Block accidental pin moves in CI

The most common bad submodule change is not a considered upgrade — it is an unnoticed one, where somebody ran a command inside the submodule and committed everything.

A gate that distinguishes a deliberate bump from an accidentThe check looks at whether the pull request changes a gitlink. If not, it passes. If it does, it requires the commit to touch only that path and to document the upstream range, which an accidental pin move never does.pull requestgitlink changed?nocheck passesyesapply the bump rulesonly the gitlink changed,message documents the rangemixed with other files, orno range in the message → fail 
#!/bin/sh
# ci/check-submodule-bump.sh — run on every pull request
set -eu
base="${1:-origin/main}"

# Which gitlinks changed?
links=$(git diff --diff-filter=M --name-only "$base"...HEAD -- '*' \
        | while read -r p; do
            git ls-tree HEAD -- "$p" | grep -q '^160000' && echo "$p"
          done)

[ -n "$links" ] || exit 0     # no dependency change: nothing to enforce

# A bump must be its own commit
changed=$(git diff --name-only "$base"...HEAD | wc -l)
[ "$changed" -eq "$(printf '%s\n' "$links" | wc -l)" ] || {
  echo "dependency bump is mixed with other changes — split it out" >&2
  exit 1
}

# ...and must document the upstream range
git log "$base"..HEAD --format=%B | grep -qi '^range:' || {
  echo "dependency bump must record the upstream range in the commit message" >&2
  exit 1
}
# Verify the gate behaves on both paths
sh ci/check-submodule-bump.sh origin/main; echo "exit=$?"
The five stages of a reviewable bumpFetch brings upstream history without changing anything. Reading the range establishes what would change. Verification establishes whether to trust it. The commit records the reasoning. The CI gate ensures the previous four actually happened.1fetchpin untouched2read the rangewhat would change3verifywhether to trust it4commitrecord the reasoning5gateenforce 1–4skipping straight to step 4 is what "submodule update --remote" does — and why its diffs get approved unread

Validation checklist

Frequently Asked Questions

Why does my checkout keep showing the submodule as modified?

Because the submodule’s HEAD is not at the SHA the superproject records — usually because a command inside it moved HEAD, or because a branch switch in the superproject changed the expected pin without updating the submodule working tree. Run git submodule update to return it to the recorded SHA, and check what moved it before assuming the pin is wrong.

Should the .gitmodules branch field be set?

Set it only if you intend to use --remote updates, because that is the only thing it affects. The build always uses the gitlink SHA regardless. Leaving it unset makes the pin’s authority obvious to anyone reading the file, which is often the clearer choice for a dependency you upgrade deliberately a few times a year.

How do I pin to a tag rather than a commit?

You cannot — a gitlink stores a commit SHA and nothing else. Check out the tag inside the submodule and commit the resulting SHA, then record the tag name in the commit message so humans know what it corresponds to. That distinction matters because a tag can be moved upstream while the SHA you recorded cannot.