Home / Git Tutorials / Git Advanced / Git Submodules

Git Submodules: Managing Nested Repositories

20 min read
Git Expert
Updated: Jan 2026

What are Git Submodules?

Git submodules allow you to include and manage external Git repositories within your main repository. They're perfect for managing dependencies, sharing code across multiple projects, or including third-party libraries while maintaining their independent version history.

Simple Analogy: Think of submodules like bookmarks in a library. Your main project is a research paper, and submodules are references to specific books (other repositories) that you need. You don't copy the entire book into your paper—you just reference which edition (commit) to use.

Main Project Repository
/home/projects/main-app
src/
docs/
libs/
shared-ui/ ← Submodule
auth-library/ ← Submodule
README.md
.gitmodules
Shared UI Library (Submodule)
github.com/company/shared-ui @ commit: a1b2c3d
# .gitmodules file content:
[submodule "libs/shared-ui"]
  path = libs/shared-ui
  url = https://github.com/company/shared-ui.git
  branch = main

When to Use Submodules

  • Shared components: Reusable UI libraries, utility functions
  • Third-party dependencies: Include open-source libraries with custom modifications
  • Monorepo alternative: When you need separate version control per component
  • Documentation/examples: Include sample code from separate repositories
  • Plugin systems: Include optional components as submodules

Warning: Submodules add complexity to your workflow. Consider alternatives like package managers (npm, pip) or monorepos before deciding on submodules.

Submodules vs Alternatives

Approach Pros Cons Best For
Git Submodules Exact version control, direct Git access, separate histories Complex workflow, manual updates, learning curve Teams needing precise control over dependencies
Package Managers
(npm, pip, etc.)		 Automatic dependency resolution, version ranges, large ecosystems Less control, can't modify source easily, version conflicts Most web projects, open-source dependencies
Git Subtrees Single repository, simpler workflow, no extra files Merged history, harder to update dependencies When you want to include code but don't need separate history
Monorepo Single source of truth, shared tooling, easy refactoring Large repo size, permission management, tooling complexity Large organizations with many interconnected projects

Basic Submodule Workflow

1

Add a Submodule

Add an external repository as a submodule:

# Add submodule to your project
git submodule add https://github.com/user/repo.git path/to/submodule

# Example: Add a shared UI library
git submodule add https://github.com/company/shared-ui.git libs/ui

# This creates:
# 1. .gitmodules file (configuration)
# 2. The submodule directory (empty until initialized)
# 3. Records the specific commit in main repo
2

Clone a Repository with Submodules

When cloning a repository that has submodules:

# Method 1: Clone with submodules immediately
git clone --recurse-submodules https://github.com/user/project.git

# Method 2: Clone then init submodules
git clone https://github.com/user/project.git
cd project
git submodule update --init --recursive

# Method 3: Initialize after clone
git submodule init
git submodule update
3

Update Submodules

Update submodules to latest or specific versions:

# Update all submodules to latest commits
git submodule update --remote --merge

# Update specific submodule
git submodule update --remote path/to/submodule

# Pull changes for all submodules
git submodule foreach 'git pull origin main'

# Commit the updated submodule references
git commit -am "Update submodules to latest versions"
4

Work Within Submodules

Make changes inside a submodule:

# Enter the submodule directory
cd path/to/submodule

# Check status (you're now in submodule's own repo)
git status

# Make changes and commit
git add .
git commit -m "Fix bug in submodule"
git push origin main

# Return to main project and update reference
cd ..
git add path/to/submodule
git commit -m "Update submodule reference"

Advanced Submodule Operations

Recursive Operations

Work with nested submodules (submodules within submodules):

# Clone with all nested submodules
git clone --recursive-submodules repo-url

# Update all submodules recursively
git submodule update --init --recursive

# Pull changes recursively
git submodule foreach --recursive 'git pull'

# Status of all submodules
git submodule status --recursive

Branch Management

Handle submodules on specific branches:

# Checkout specific branch in submodule
cd submodule
git checkout feature-branch
git pull origin feature-branch
cd ..
git add submodule

# Configure submodule to track branch
# In .gitmodules:
[submodule "libs/ui"]
  path = libs/ui
  url = https://github.com/company/ui.git
  branch = develop

Bulk Operations

Execute commands across all submodules:

# Run any command in all submodules
git submodule foreach 'git status'

# Pull latest changes in all submodules
git submodule foreach 'git pull origin main'

# Checkout specific commit in all submodules
git submodule foreach 'git checkout abc1234'

# Clean all submodules
git submodule foreach 'git clean -fd'

Interactive Submodule Demo

Try It: Manage Submodules

Simulate managing submodules in a project:

Demo Project
Status: Ready
Submodules: 0
Uncommitted changes: 0
Git commands executed: 0

Real-World Scenarios

1. Shared Component Library

Situation: Multiple projects need the same UI components.

# Project A adds the shared library
git submodule add https://github.com/company/ui-components.git shared/ui
git commit -m "Add shared UI components as submodule"

# Project B adds the same library
git submodule add https://github.com/company/ui-components.git libs/ui

# Update the library in both projects
cd shared/ui
git pull origin main
cd ../..
git add shared/ui
git commit -m "Update UI components to latest"

2. Third-Party Library with Custom Patches

Situation: Need a modified version of an open-source library.

# Fork the original repository
# Add your fork as submodule
git submodule add https://github.com/yourname/library.git vendor/library

# Make custom modifications
cd vendor/library
git checkout -b custom-patches
# Make changes...
git commit -am "Add custom feature"
git push origin custom-patches

# Update from upstream (original)
git remote add upstream https://github.com/original/library.git
git fetch upstream
git merge upstream/main

3. Documentation with Examples

Situation: Documentation repository needs example code from separate repos.

# Documentation repo structure
docs/
├── README.md
├── examples/ ← Submodules here
│ ├── basic-demo/ ← Submodule 1
│ ├── advanced-demo/ ← Submodule 2
│ └── tutorial/ ← Submodule 3
└── .gitmodules

# Add example repositories
git submodule add https://github.com/company/basic-demo.git examples/basic-demo
git submodule add https://github.com/company/advanced-demo.git examples/advanced-demo

# Clone documentation with examples
git clone --recurse-submodules https://github.com/company/docs.git

Command Reference

Basic Submodule Commands

# Add a submodule
git submodule add [url] [path]

# Initialize submodules
git submodule init

# Update submodules
git submodule update

# Clone with submodules
git clone --recurse-submodules [url]

# Show submodule status
git submodule status

Advanced Operations

# Update submodules to latest remote
git submodule update --remote

# Run command in all submodules
git submodule foreach '[command]'

# Sync submodule URL changes
git submodule sync

# Deinitialize a submodule
git submodule deinit [path]

# Remove a submodule
git rm [path] # Removes from working tree and index

Recursive Operations

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

# Status recursively
git submodule status --recursive

# Foreach recursively
git submodule foreach --recursive '[command]'

# Pull all submodules recursively
git pull --recurse-submodules

Best Practices

Documentation

  • Document submodule usage in README
  • Include setup instructions for new developers
  • Document submodule update procedures
  • Keep .gitmodules file well-commented
  • Document known issues with specific versions

Team Workflow

  • Establish clear submodule update policies
  • Use CI to verify submodule states
  • Regularly update submodule references
  • Coordinate submodule changes across teams
  • Consider using a submodule manager script

Troubleshooting

  • Always use --recurse-submodules when cloning
  • Check submodule status before pulling/pushing
  • Handle merge conflicts in .gitmodules carefully
  • Keep submodules at reasonable depth
  • Have a rollback plan for submodule updates

Frequently Asked Questions

What's the difference between git submodule and git subtree?

Both allow including external repositories, but with different approaches:

Aspect git submodule git subtree
Repository Structure Separate repositories linked together Single repository with merged history
Working Directory Submodule files in separate directories All files in same directory tree
Git Operations Need to manage each repo separately All operations in main repo
Clone Complexity Need --recurse-submodules flag Normal clone works
Best For Independent components with own release cycles When you want to "vendor" dependencies

Example use cases:

  • Use submodule: Shared UI library used by multiple projects that needs independent updates
  • Use subtree: Including a modified version of an open-source library that you don't need to update often

Conversion: You can convert between them using git subtree split and git submodule add.

How do I fix "fatal: reference is not a tree" error?

This error occurs when Git can't find the commit referenced by a submodule. Common causes and solutions:

  1. Submodule repository was force-pushed:
    # Update submodule to new commit
    cd path/to/submodule
    git fetch origin
    git checkout origin/main
    cd ../..
    git add path/to/submodule
    git commit -m "Update submodule reference"
  2. Submodule commit was deleted:
    # Find an alternative commit
    cd path/to/submodule
    git log --oneline -10
    git checkout [working-commit]
    # Update main repository reference
  3. .gitmodules file is corrupted:
    # Check .gitmodules file
    cat .gitmodules
    # Ensure URLs and paths are correct
    # Fix if necessary and commit
  4. Prevention: Avoid force-pushing to repositories used as submodules. Use tags for important commits.

Recovery script:

#!/bin/bash
# Fix all broken submodules
git submodule foreach --recursive 'git fetch origin && git reset --hard origin/$(git rev-parse --abbrev-ref HEAD)'
How do I change a submodule's URL?

There are several ways to change a submodule's URL:

  1. Using git command:
    git submodule set-url path/to/submodule new-url
    # Example: Change from HTTPS to SSH
    git submodule set-url libs/ui git@github.com:company/ui.git
    git commit -am "Update submodule URL"
  2. Manual edit of .gitmodules:
    # Edit .gitmodules file
    vim .gitmodules
    # Change the URL, then sync:
    git submodule sync
    git submodule update --init
    git commit -am "Update submodule URL"
  3. Using config command:
    # Update git config
    git config -f .gitmodules submodule.path/to/submodule.url new-url
    git submodule sync

Important considerations:

  • Make sure the new repository has the same commit history (or at least the referenced commit)
  • Notify team members about the URL change
  • Update CI/CD configuration if needed
  • Test that cloning with new URL works

Common reasons for URL changes:

  • Switching from HTTPS to SSH authentication
  • Moving repository to different hosting service
  • Changing organization name
  • Using a fork instead of upstream
Can I have submodules within submodules?

Yes, Git supports nested submodules (submodules within submodules). This is called recursive submodules.

Main Project
Contains: UI Library → Icons Submodule
UI Library (Submodule)
Contains: Icons Library Submodule
Icons Library (Nested Submodule)
Deep nesting: 2 levels

Working with recursive submodules:

# Clone with all nested submodules
git clone --recursive-submodules project-url

# Update all nested submodules
git submodule update --init --recursive

# Pull changes in all nested submodules
git submodule foreach --recursive 'git pull'

# Status of all nested submodules
git submodule status --recursive

Best practices for nested submodules:

  • Keep nesting shallow (2-3 levels maximum)
  • Document the nested structure clearly
  • Use consistent update procedures
  • Consider if flattening the structure would be better
  • Test cloning and updating thoroughly

Warning: Deeply nested submodules can become difficult to manage and slow to clone/update.

How do I completely remove a submodule?

Removing a submodule requires several steps to clean it up completely:

  1. Deinitialize the submodule:
    git submodule deinit path/to/submodule
    # Removes submodule from .git/config
  2. Remove from working tree and index:
    git rm path/to/submodule
    # Removes the directory and updates .gitmodules
  3. Remove .gitmodules entry (if not done automatically):
    # Edit .gitmodules file
    vim .gitmodules
    # Remove the submodule section
    [submodule "path/to/submodule"]
      path = path/to/submodule
      url = https://...
    # Save and commit
  4. Commit the changes:
    git commit -m "Remove submodule: name"
    git push origin main
  5. Clean up locally (optional):
    # Remove the directory if still exists
    rm -rf path/to/submodule

    # Clean git cache
    git config --remove-section submodule.path/to/submodule 2>/dev/null

One-liner for removal:

git submodule deinit -f path/to/submodule && \
git rm -f path/to/submodule && \
rm -rf .git/modules/path/to/submodule

After removal:

  • Notify team members to run git submodule sync
  • Update documentation
  • Remove any CI/CD references to the submodule
  • Consider if you need to keep a local backup of the submodule code
Previous: Git Bisect for Debugging Next: Git Worktrees

Master Advanced Git Features