Introduction

Committing changes in a Git submodule is a two-repository workflow, not a single commit operation. You make a normal commit inside the submodule repository first, then you commit the updated submodule pointer in the parent repository. Most confusion comes from forgetting that the parent repo does not store the submodule’s files directly; it stores a reference to a specific submodule commit.

Understand What The Parent Repo Tracks

A submodule in the parent repository is tracked as a commit pointer, not as a copied working tree snapshot. That means changing files inside the submodule is not enough. The parent repository only notices that the submodule now points at a different commit.

So the full workflow is:

1. commit inside the submodule,
2. push the submodule branch if needed,
3. go back to the parent repo,
4. commit the updated submodule reference there.

Step 1: Enter The Submodule And Check The Branch

A common issue is that submodules are often checked out in detached HEAD state.

cd path/to/submodule
git status
git branch

If you want to commit on the submodule’s master branch, check it out explicitly.

git checkout master

If master should track the remote branch, make sure it is set up correctly before you start editing.

Step 2: Commit Inside The Submodule

Now treat the submodule like a normal Git repository.

git add .
git commit -m "Fix shared parsing logic"
git push origin master

At this point, the new submodule commit exists in the submodule repository. The parent repository still points to the old commit until you update and commit that pointer.

Step 3: Commit The Updated Pointer In The Parent Repo

Return to the parent repository and inspect its status.

cd ..
git status

You will typically see the submodule path reported as modified. That means the parent repo noticed the referenced submodule commit changed.

Commit that change like any other tracked update.

git add path/to/submodule
git commit -m "Update submodule to latest master"
git push origin main

Now collaborators pulling the parent repository will receive the updated submodule reference.

What Happens If You Skip The Parent Commit

If you only commit inside the submodule and forget the parent repository commit, your local checkout points at the new submodule revision, but the parent repository history does not record that dependency update. Other developers will not automatically land on the same submodule commit.

That is one of the most common submodule mistakes.

Detached HEAD Is The Common Trap

A lot of “why did my submodule commit disappear?” stories come from committing while the submodule is detached instead of on a normal branch.

Check before committing:

git rev-parse --abbrev-ref HEAD

If the result is HEAD, you are detached. Switch to the intended branch first unless you know exactly why detached work is acceptable.

Keep Branch Strategy Explicit

If several parent repositories share the same submodule, agreeing on branch policy matters.

For example:

• submodule development happens on its own master or main,
• parent repos pin specific tested commits,
• updating the parent pointer is a deliberate dependency upgrade.

This is safer than assuming the submodule should magically follow the latest branch tip at all times.

Common Pitfalls

• Committing inside the submodule but forgetting to commit the updated pointer in the parent repo.
• Working in a detached submodule HEAD and then being surprised by later branch confusion.
• Assuming the parent repo stores submodule file diffs directly instead of a commit reference.
• Pushing the parent repo update before the referenced submodule commit has been pushed to its remote.
• Treating submodules like ordinary directories rather than nested repositories with separate history.

Summary

• A submodule commit is a normal commit inside the submodule repository.
• The parent repository must also commit the updated submodule pointer.
• Check that the submodule is on the intended branch before committing.
• Push the submodule commit before publishing the parent repo update.
• Think of submodules as separate repositories whose versions are pinned by the parent project.