Add and clone
git submodule add https://github.com/org/lib.git vendor/lib
git commit -m "add lib submodule"
# cloning a repo that uses submodules
git clone --recursive https://github.com/org/app.git
# already cloned without --recursive
git submodule update --init --recursive
Update behavior
git submodule update checks out the commit recorded in the parent repository, not the latest commit on the submodule's branch. That is intentional: builds are reproducible. To move the pointer, enter the submodule, check out the desired commit, and commit the change in the parent.
cd vendor/lib
git fetch
git checkout v2.1.0
cd ../..
git add vendor/lib
git commit -m "bump lib to v2.1.0"
Sync and troubleshoot
git submodule sync --recursiveupdates the recorded URLs in.gitmodulesafter a URL change.- A submodule showing as modified usually means HEAD moved but the parent was not committed.
git submodule statusshows the pinned commit and a+when it differs from the index.- CI must run
--init --recursive; a plain clone leaves submodule directories empty.
Authentication for private submodules is separate from the parent. CI needs credentials for each submodule URL, or a relative URL that resolves against the parent remote.
Removing a submodule
Removal is multi-step because the metadata lives in three places: .gitmodules, the index, and .git/modules. Skipping a step leaves a broken entry that breaks future clones.
git submodule deinit -f vendor/lib
git rm -f vendor/lib
git commit -m "remove lib submodule"
rm -rf .git/modules/vendor/lib