How to fix fatal: Needed a single revision in Git

First, inspect your .gitmodules file to see the branch configuration:

cat .gitmodules

Look for entries like:

[submodule "path/to/submodule"]
    path = path/to/submodule
    url = [email protected]:org/repo.git
    branch = master

If branch = master but the remote now uses main, this is likely your issue.

If the branch name has changed (e.g., master to main), update .gitmodules:

git config -f .gitmodules submodule.path/to/submodule.branch main

Or edit .gitmodules directly and change branch = master to branch = main.

After updating, sync the configuration:

git submodule sync
git submodule update --init --recursive

The --remote flag tells Git to fetch the latest commit from the configured branch, which requires a valid branch configuration. If you just want to checkout the commit recorded in the parent repository:

# Instead of:
git submodule update --init --remote

# Use:
git submodule update --init --recursive

This checks out the exact commit the parent repository expects, without needing branch configuration.

If your repository was cloned with --depth, submodules may be restricted to fetching only specific branches. Check and fix the fetch configuration:

# Check current fetch configuration
git submodule foreach git config --get remote.origin.fetch

# Fix to fetch all branches
git submodule foreach git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'

# Now update submodules
git submodule update --init --recursive

If the submodule is in a corrupted state (empty directory, incomplete checkout), remove it completely and start fresh:

# Remove the submodule directory
rm -rf path/to/submodule

# Remove the submodule's Git data
rm -rf .git/modules/path/to/submodule

# Reinitialize
git submodule update --init --recursive

This forces a clean checkout of the submodule.

Git may fail silently if it cannot verify the SSH host key for the submodule's server. Test connectivity manually:

# For GitHub
ssh -T [email protected]

# For GitLab
ssh -T [email protected]

# For custom servers
ssh -T [email protected]

Accept the host key when prompted, then retry the submodule update.

Sometimes running a manual pull inside the submodule can unblock the situation:

cd path/to/submodule
git fetch origin
git checkout main  # or the correct branch name
git pull origin main
cd ..

# Now try the submodule update again
git submodule update --init --recursive

Some older Git versions have bugs with submodule handling. Updating Git has resolved this issue for many users:

# Ubuntu/Debian
sudo apt update && sudo apt install git

# macOS with Homebrew
brew upgrade git

# Windows - download latest from git-scm.com

# Verify version
git --version

Git 2.38+ has significant improvements to submodule handling.