How to Update Git Submodule When Standard Command Fails

When git submodule update doesn’t fetch the latest commits from your SSH URL submodule, you need to manually fetch the changes in the submodule directory and then update the reference in your main repository. The standard update command only checks out the commit that’s already recorded in the parent repository, it doesn’t automatically fetch new commits from the remote.

Contents

• Understanding Why Submodule Update Fails
• SSH URL Specific Issues
• Manual Update Methods
• URL Management Solutions
• Automation Approaches

Understanding Why Submodule Update Fails

The git submodule update command has inherent limitations that cause it to not fetch latest commits automatically. According to the Git documentation, the update command “doesn’t fetch new objects from the remote site” by default and only “checkout the commit recorded in the superproject on a detached HEAD in the submodule.”

This means:

• git submodule update only checks out the commit already referenced in your main repository
• It doesn’t fetch new commits from the remote origin
• It doesn’t update the submodule reference to point to newer commits
• You need to fetch the changes separately before updating

As one Stack Overflow answer explains: “It does NOT pull the latest commits for each submodule. git submodule foreach git pull origin master is what you want if you intend to update each submodule to the latest from their origin repositories.”

SSH URL Specific Issues

SSH URLs in submodules can present unique challenges. Research shows several common SSH-related problems:

SSH Access Issues

Some users report that while they can clone repositories directly via SSH without problems, submodules fail with SSH URLs. One user noted: “I want to re-iterate that I definitely have access to the repository and am able to clone the repository via ssh without any problems. This ONLY happens when the repository is included as a submodule in another project.”

SSH URL Format Problems

SSH URLs in .gitmodules files sometimes omit the ssh:// prefix, which can cause parsing issues. According to GitHub issue #12295: “Git SSH submodules that omit ‘ssh://’ no longer work” and “Any parsing of a Git submodule URL should allow the protocol to be omitted.”

SSH Configuration Requirements

SSH-based URLs in .gitmodules work best when they don’t include a username, allowing each user to configure their own server username in .ssh/config if it differs from their local username.

Manual Update Methods

When the standard update commands fail, you need to manually update the submodule. Here are the most effective approaches:

Method 1: Direct Submodule Update

For updating a specific submodule from commit A to commit B:

# Navigate to the submodule directory
cd path/to/submodule

# Fetch all changes from origin
git fetch origin

# Checkout to the specific commit or branch you want
git checkout main  # or the specific commit hash
git pull origin main

# Go back to the main repository
cd ..

# Update the parent repository to reference the new commit
git add path/to/submodule
git commit -m "Update submodule to latest commit"

Method 2: Update All Submodules

To update all submodules to their latest commits:

git submodule foreach 'git fetch origin --tags; git checkout main; git pull origin main'

Method 3: Recursive Update with Fetch

For nested submodules or comprehensive updates:

git submodule foreach 'git fetch origin --tags'
git submodule foreach 'git checkout main'
git submodule update --init --recursive

As explained in the GeeksforGeeks guide: “Fetch the latest changes and update the submodule. Change back to the root directory of your main repository. Update the main repository to point to the new commit in the submodule.”

URL Management Solutions

Switching Between SSH and HTTPS

If SSH URLs are problematic, you can switch to HTTPS in your .gitmodules and .git/config files:

# Change URL in .gitmodules
git config -f .gitmodules submodule.your-submodule.url https://github.com/user/repo.git

# Sync the changes
git submodule sync

# Update the submodule
git submodule update --init --recursive

Using Relative URLs

According to Damir’s Corner: “I would recommend using relative submodule URLs whenever possible. They don’t force all developers to use HTTPS or SSH leaving them the freedom of choice.”

Setting URLs Programmatically

You can set URLs directly:

git submodule set-url submodule-name ssh://user@server/path/to/repo

Automation Approaches

One-Liner for HTTPS Conversion

For CI/CD environments where SSH authentication is problematic, you can convert HTTPS URLs to SSH:

# Replace HTTPS with SSH in .gitmodules
sed -i 's|https://|git@|g; s|/|:|g; s|\.git$||g' .gitmodules

# Sync and update
git submodule sync
git submodule update --init --recursive

Comprehensive Update Script

For regular maintenance of submodules:

#!/bin/bash
# Fetch latest changes for all submodules
git submodule foreach 'git fetch origin --tags'

# Update each submodule to latest commit
git submodule foreach 'git checkout main && git pull origin main'

# Update parent repository references
git submodule update --init --recursive
git add .
git commit -m "Update all submodules to latest commits"

Sources

1. Update Git submodule to latest commit on origin - Stack Overflow
2. Changing URLs of Git submodules - Damir’s Corner
3. Git submodule documentation
4. How to update Git submodule to latest commit on origin - GeeksforGeeks
5. Git submodules and SSH access - Stack Overflow
6. One-liner to replace HTTPS into SSH url in .gitmodules
7. Use HTTPS instead of SSH when cloning git submodules

Conclusion

When git submodule update fails to fetch the latest commits from your SSH URL submodule, remember these key solutions:

1. Manual intervention is required - The standard update command only checks out already recorded commits, it doesn’t fetch new ones
2. Use git fetch in the submodule directory - Always fetch the latest changes before attempting to update
3. Switch protocols if needed - Convert between SSH and HTTPS URLs using git config and git submodule sync
4. Update parent repository references - After modifying the submodule, run git add and git commit in the main repository
5. Consider automation scripts - For regular maintenance, create scripts that fetch, checkout, and update all submodules systematically

The most reliable approach for updating from commit A to commit B is to manually enter the submodule, fetch all changes, checkout to the desired commit or branch, then update the parent repository reference. This ensures you have full control over which commit the submodule points to and avoids the limitations of automated update commands.