Git Submodules & Monorepo Alternatives

Also Known As

TL;DR

Explanation

Git submodules: a repository nested inside another, pinned to a specific commit. Common problems: easy to forget to commit submodule updates, new contributors miss git submodule update --init, detached HEAD confusion, and complex CI setup. Alternatives: git subtree (merges subtree history into main repo, no nested .git), monorepo (all code in one repo with build tool), Composer packages (proper versioning + dependency resolution). For PHP: Composer with a private Packagist is almost always better than submodules.

Common Misconception

Why It Matters

Common Mistakes

• Committing changes to submodule without updating the parent repo's pointer
• Forgetting git submodule update --init on fresh clone — builds fail
• Using submodules for external dependencies — use Composer/npm instead
• No --recursive flag in CI clone — submodules are empty

Code Examples

# Developer updates submodule, forgets to update parent:
git -C shared-lib commit -m 'Add feature'
# Forgets: cd .. && git add shared-lib && git commit
# Other developers: still get old version

# New clone:
git clone repo && ls shared-lib/ # Empty! Forgot --recursive

# Composer private package instead:
# composer.json:
# {"require": {"company/shared-lib": "^1.3"}}

# Developer A releases update:
# git tag v1.3.0 && git push --tags
# Consumer updates:
# composer update company/shared-lib
# Explicit version, CHANGELOG, proper dep resolution

References

• ↗ https://git-scm.com/book/en/v2/Git-Tools-Submodules

Tags

Related Terms