Introduction

In Git, a "subproject commit" almost always means the exact submodule commit recorded by a parent repository. The parent does not store the submodule's branch history inline; it stores a pointer to one specific child commit so that every clone can reproduce the same dependency state.

Core Sections

What the parent repository actually tracks

A Git submodule is its own repository nested inside another repository. The parent project keeps two pieces of information:

• the submodule URL in .gitmodules
• the exact checked-out child commit in the Git index

That second piece is what people mean by a subproject commit. It is not "latest on main" and it is not a semantic version. It is one exact commit hash from the child repository.

git submodule add https://github.com/example/shared-lib.git vendor/shared-lib
git commit -m "Add shared library as submodule"

After that commit, the parent repository is effectively saying, "use this repository at this exact child revision."

Why Git stores a commit, not a branch

Branches move. Commits do not. If the parent tracked only a branch name, two developers could clone the same parent commit on different days and end up with different dependency code. By storing a commit hash, Git makes the dependency state reproducible.

That matters for:

• CI consistency
• release rebuilds
• debugging old production versions
• stable collaboration across machines

This is why submodules behave more like pinned snapshots than floating dependencies.

How the pointer changes

Suppose you update the submodule itself:

1cd vendor/shared-lib
2git checkout main
3git pull
4git commit --allow-empty -m "Example submodule change"
5cd ../..
6git status

At that point, the parent repository notices that vendor/shared-lib now points at a different child commit. Nothing is recorded in the parent until you stage and commit that changed pointer.

git add vendor/shared-lib
git commit -m "Update shared-lib submodule pointer"

So the workflow is always two-layered:

1. commit in the submodule if the child code changed
2. commit in the parent to record the new subproject commit

Cloning and checking out subproject commits

When someone clones the parent repository, Git can also initialize the submodules at the recorded commits:

git clone https://github.com/example/app.git
cd app
git submodule update --init --recursive

Later, after pulling parent changes, the same command updates submodules to the exact commits expected by the parent:

git pull
git submodule update --init --recursive

That is why a submodule often appears in detached HEAD state. Git is checking out the precise commit the parent recorded, not automatically moving the submodule to a branch tip.

Detached HEAD is expected, not a bug

Many people think they broke the submodule when they see detached HEAD. In most cases that is normal. Detached HEAD just means the submodule is sitting at an exact commit rather than on a local branch.

If you want to edit the submodule, switch to a branch explicitly before making real changes:

cd vendor/shared-lib
git checkout main

Then commit your changes there, return to the parent, and commit the updated pointer.

Why teams use subproject commits

Subproject commits are mostly about controlled reproducibility. They let a team say, "this application build uses that dependency at exactly this revision." That is especially useful when the child repo is internal, not versioned through a package manager, or needs to be developed in parallel with the parent project.

The tradeoff is that submodules add workflow overhead. You have to remember that updating the dependency means updating and committing the parent pointer too.

Common Pitfalls

• Committing inside the submodule and forgetting to commit the new pointer in the parent repository.
• Assuming git pull in the parent automatically updates the working tree of every submodule.
• Treating detached HEAD inside a submodule as an error instead of expected pinned-commit behavior.
• Making changes in a detached HEAD submodule and then losing track of where those commits belong.
• Expecting a submodule to behave like a package manager dependency that floats to the newest branch tip.

Summary

• A subproject commit is the specific submodule commit recorded by the parent repository.
• The parent tracks an exact child revision, not a moving branch reference.
• Updating a submodule usually requires one commit in the child repo and another in the parent repo.
• 'git submodule update --init --recursive checks out the recorded submodule state.'
• Detached HEAD inside a submodule is normal because Git is pinning the dependency to one exact commit.