How to Use Git Submodule: Add and Manage Submodules Easily

Use git submodule add <repository-url> <path> to add a submodule to your project. Then use git submodule update --init --recursive to initialize and fetch the submodule content.

Syntax

The main commands to work with git submodules are:

• git submodule add <repository-url> <path>: Adds a new submodule at the specified path.
• git submodule update --init --recursive: Initializes and fetches all submodules recursively.
• git submodule status: Shows the current commit of each submodule.
• git submodule foreach <command>: Runs a command in each submodule.

bash

git submodule add <repository-url> <path>
git submodule update --init --recursive
git submodule status
git submodule foreach <command>

Example

This example shows how to add a submodule, initialize it, and check its status.

bash

git init myproject
cd myproject
git submodule add https://github.com/example/library.git libs/library
git submodule update --init --recursive
git submodule status

Output

 1a2b3c4d5e6f7g8h9i0j libs/library (heads/main)

Common Pitfalls

Common mistakes include:

• Not running git submodule update --init --recursive after cloning a repo with submodules, so submodules remain empty.
• Forgetting to commit the .gitmodules file and submodule changes, causing others to miss submodules.
• Trying to edit submodule files without committing inside the submodule repository first.

bash

## Wrong: Cloning repo but not initializing submodules

git clone https://github.com/user/project.git
cd project
ls libs/library
# Directory is empty

## Right: Initialize submodules after cloning

git clone https://github.com/user/project.git
cd project
git submodule update --init --recursive
ls libs/library
# Files are present

Quick Reference

Command	Description
git submodule add	Add a new submodule
git submodule update --init --recursive	Initialize and fetch submodules
git submodule status	Show submodule commit status
git submodule foreach	Run command in all submodules
git submodule deinit	Remove submodule from working tree

Key Takeaways

Always run 'git submodule update --init --recursive' after cloning to fetch submodules.

Commit the .gitmodules file and submodule changes to share submodules with others.

Use 'git submodule add' to include external repositories inside your project.

Manage submodules carefully to avoid confusion with nested repositories.

Use 'git submodule foreach' to run commands across all submodules easily.