gotchagitMajor

Git submodules: initialization and update gotchas

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

submodule initsubmodule updateempty submodulerecurse submodulesnested repository

Error Messages

fatal: not a git repository: 'vendor/lib/.git'

warning: LF will be replaced by CRLF

Submodule 'vendor/lib' (https://...) registered for path 'vendor/lib'

Problem

After cloning a repo with submodules, the submodule directories are empty. After a teammate adds a new submodule, existing clones don't get the submodule content automatically.

Solution

Initialize and populate submodules after cloning:

git submodule update --init --recursive

Or clone with submodules from the start:
git clone --recurse-submodules <url>

After a teammate adds a new submodule:
git pull
git submodule update --init --recursive

Update a submodule to its latest remote commit:
git submodule update --remote --merge

Why

Submodules store only a pointer (commit SHA) to another repo. The actual submodule content is not part of the parent repo and must be fetched separately.

Gotchas

A submodule pointer commit SHA in the parent repo does NOT automatically update when the submodule repo gets new commits
Detached HEAD inside a submodule is normal and expected — commits must be made on a branch inside the submodule first
git status shows 'modified content' for submodules when their HEAD differs from the recorded SHA

Code Snippets

Essential submodule commands

# Clone with submodules populated
git clone --recurse-submodules https://github.com/org/repo.git

# Initialize submodules in an existing clone
git submodule update --init --recursive

# Update submodule to latest commit on its tracked branch
git submodule update --remote --merge

# Check submodule status
git submodule status

Context

Working with repos that use git submodules for dependency management

Revisions (0)

No revisions yet.