تثبيت الوحدات الفرعية على وسوم والتزامات محددة

A common misconception: a submodule tracks a branch. In reality, the superproject records a specific commit SHA for each submodule. Branches only matter when you choose to update.

This pinning is what makes submodule-based builds reproducible across machines and time.

See exactly which commit each submodule is locked to with git submodule status. The leading SHA is the recorded pin.

• (space) — submodule is at the pinned commit
• + — checked-out commit differs from the pin
• - — submodule is not initialized
• U — merge conflicts in the submodule

To pin to a released tag, enter the submodule, check out the tag, then commit the new pointer in the superproject.

Sometimes you need a commit between releases. Check out the exact SHA inside the submodule, then record it in the superproject.

Checking out a tag or SHA puts the submodule in detached HEAD. That is expected and correct for pinning. You only attach to a branch when you intend to develop inside the submodule.

You can record a preferred branch in .gitmodules so git submodule update --remote knows what to follow. The pin still wins until you explicitly update.

To advance a submodule to the latest of its tracked branch, use --remote. Review the diff before committing the new pin so the bump is deliberate.

Builds should fail if a submodule drifts from its pin. A CI guard checks that the checked-out SHA matches the recorded one.

Accidental submodule bumps are a frequent source of mysterious build breaks. Treating each pin change as a reviewable, intentional commit keeps your dependency surface predictable and auditable.

If a pin update breaks the build, revert it like any other change: the superproject commit that moved the pointer can be undone, snapping the submodule back to its previous SHA.

Test your understanding of submodule pinning.

You learned that submodules pin commit SHAs, how to read git submodule status prefixes, how to pin to a tag or exact SHA, why detached HEAD is normal, optional branch tracking, controlled --remote updates, and CI drift enforcement. Deliberate pinning keeps advanced submodule setups reproducible.