How to clone repository with submodules in Git
Łukasz Holeczek
Follow Łukasz Holeczek on GitHub
Connect with Łukasz Holeczek on LinkedIn
Follow Łukasz Holeczek on X (Twitter)
Cloning repositories that contain Git submodules requires special handling to also clone the nested repositories.
As the creator of CoreUI with over 25 years of version control experience since 2000, I’ve managed projects with complex submodule structures and understand the importance of proper cloning.
The most efficient approach uses git clone --recurse-submodules to clone the main repository and all submodules in a single command.
This ensures the complete project structure is ready immediately without additional commands.
Use git clone --recurse-submodules to clone a repository with all its submodules.
git clone --recurse-submodules https://github.com/username/repository.git
The --recurse-submodules flag tells Git to initialize and clone all submodules recursively. This works even for nested submodules (submodules within submodules). The cloned repository is immediately ready to use with all dependencies in place.
Cloning and Initializing Submodules Separately
If you already cloned without submodules, initialize them after cloning.
# Clone the repository
git clone https://github.com/username/repository.git
cd repository
# Initialize and clone all submodules
git submodule update --init --recursive
The git submodule update --init initializes and clones all submodules. The --recursive flag handles nested submodules. This two-step approach is useful when you forgot the --recurse-submodules flag during initial cloning.
Cloning Specific Submodules
Clone only selected submodules instead of all of them.
# Clone the repository
git clone https://github.com/username/repository.git
cd repository
# Initialize and clone specific submodule
git submodule update --init libs/library1
# Initialize multiple specific submodules
git submodule update --init libs/library1 libs/library2
The git submodule update --init with specific paths clones only those submodules. This is useful for large repositories where you don’t need all dependencies. Specify multiple paths to clone several submodules at once.
Cloning with Parallel Submodule Fetching
Speed up cloning by fetching submodules in parallel.
git clone --recurse-submodules --jobs 8 https://github.com/username/repository.git
The --jobs flag specifies how many submodules to fetch simultaneously. Using 8 jobs significantly speeds up cloning for repositories with many submodules. Adjust the number based on your network connection and CPU cores.
Cloning to Specific Branch with Submodules
Clone a specific branch and its submodules in one command.
git clone --recurse-submodules --branch develop https://github.com/username/repository.git
The --branch flag checks out the specified branch after cloning. The --recurse-submodules still initializes submodules. This is useful for starting work on a feature branch immediately without switching branches after cloning.
Updating Submodules After Pulling Changes
After pulling changes, update submodules to match the new references.
# Pull changes from remote
git pull
# Update all submodules to match the commit references
git submodule update --recursive
# Or combine both operations
git pull --recurse-submodules
The git submodule update moves submodules to the commits referenced by the main repository. The git pull --recurse-submodules pulls changes in the main repository and updates submodules in one command. This keeps everything synchronized.
Checking Submodule Status
Verify that all submodules are properly cloned and on correct commits.
# Show submodule status
git submodule status
# Show detailed submodule information
git submodule foreach 'git status'
# Check if submodules are initialized
git submodule
The git submodule status displays the current commit of each submodule. A - prefix indicates uninitialized submodules. A + indicates the submodule is on a different commit than referenced. The foreach command runs a Git command in each submodule directory.
Setting Default Behavior for Submodules
Configure Git to always fetch submodules automatically.
# Set global configuration
git config --global submodule.recurse true
# Set configuration for specific repository
git config submodule.recurse true
This configuration makes all Git commands that work with submodules automatically include the --recurse-submodules flag. After setting this, commands like git pull, git checkout, and git status automatically handle submodules without extra flags.
Best Practice Note
This is the same submodule cloning process we recommend for CoreUI projects that include external dependencies as submodules. Always use --recurse-submodules when cloning to avoid incomplete checkouts. For teams, document the correct clone command in the README to prevent confusion. Consider setting submodule.recurse true in team coding standards to make submodule handling automatic. If you’re starting a new project, evaluate whether submodules are necessary - npm packages or monorepos often provide simpler dependency management. For more about managing submodules, see our guide on how to remove submodules in Git.
