Add and clone

bash
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.

bash
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 --recursive updates the recorded URLs in .gitmodules after a URL change.
  • A submodule showing as modified usually means HEAD moved but the parent was not committed.
  • git submodule status shows 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.

bash
git submodule deinit -f vendor/lib
git rm -f vendor/lib
git commit -m "remove lib submodule"
rm -rf .git/modules/vendor/lib