Git submodules allow you to include and manage external Git repositories as dependencies within your main project. They're useful when you want to include another project inside yours while keeping both projects separate.

What is a Git Submodule?

A submodule is a reference to a specific commit in another Git repository. It lets you:

• Include external code in your project
• Keep the external code's history separate
• Track specific versions of the external code
• Update the external code when needed

How to use a Submodule

Adding a Submodule

# Add a submodule to your project
git submodule add https://github.com/username/repository.git path/to/submodule

This:

• Clones the repository into the specified path.
• Creates a .gitmodules file in your main project.
• Adds the submodule information to your project's index.

Cloning a Project with Submodules

When you clone a project that has submodules:

# Clone the main project
git clone https://github.com/username/main-project.git

# Initialize and update submodules
cd main-project
git submodule update --init --recursive

Or do it in one command:

git clone --recurse-submodules https://github.com/username/main-project.git

Updating Submodules

cd path/to/submodule
git fetch
git checkout main  # or a specific commit hash
git pull origin main
cd ..
git add lib/repo
git commit -m "Updated submodule to latest version"

When you update a submodule, you're changing which commit of the submodule's repository your main project is pointing to. Remember:

• Submodules are fixed references to specific commits (like bookmarks)
• They don't automatically track branches or latest changes
• Updating means moving that reference to a newer/different commit

Practical Examples

Third Party Themes

Scenario: Let's say you're building a website and want to use a third-party theme:

# Add the theme as a submodule
git submodule add https://github.com/example/awesome-theme.git themes/awesome-theme

# Commit the submodule addition
git commit -m "Added awesome-theme as submodule"

Now your project structure looks like:

my-website/
├── .gitmodules
├── themes/
│   └── awesome-theme/  # This is the submodule
└── (your other files)

Monorepo Component Sharing

Scenario: A company has multiple projects sharing common components

# Shared UI components across web/mobile apps
git submodule add git@internal.company.com:shared/ui-components.git shared/ui

Why submodules?

• Design system updates propagate to all projects
• Each project can upgrade components independently
• Avoids duplicate code maintenance

Documentation in Sync with Code

Scenario: Keep docs versioned with specific code releases

# Separate docs repo embedded in project
git submodule add git@github.com:myproject/docs.git docs

Tips and Tricks

• Always commit after adding a submodule - The submodule addition needs to be committed like any other change.
• Track specific versions - Submodules point to specific commits, not branches. Update them intentionally.
• Recursive cloning - Use --recurse-submodules when cloning to get all nested dependencies.
• Submodule status - Check submodule status with:

git submodule status

• Update all submodules:

git submodule foreach git pull origin main

• Remove a submodule (it's a multi-step process):

# Remove the submodule entry from .git/config
git submodule deinit -f path/to/submodule

# Remove the submodule directory
rm -rf .git/modules/path/to/submodule

# Remove the entry from .gitmodules and remove the directory
git rm -f path/to/submodule

Common Pitfalls

• Forgetting to initialize submodules - After cloning, you must initialize them.
• Uncommitted changes in submodules - Changes in submodules aren't automatically part of the main project's commits.
• Detached HEAD state - Submodules are in a "detached HEAD" state pointing to a specific commit, not a branch.
• Nested submodules - Some projects have submodules within submodules. Use --recursive to get them all.

When to Use Submodules

• When you need to include another project but want to maintain its history separately
• When you want to track specific versions of dependencies
• When the external code changes independently of your main project

Alternatives to Submodules

For simpler dependency management, consider:

• Package managers (npm, pip, etc.)
• Git subtrees (submodules but with merged history)
• Copying the code directly (for very small dependencies)

Conclusion

Git submodules are a powerful way to manage dependencies in your projects while keeping repositories clean and modular. Whether you're sharing components across teams, versioning assets, or integrating third-party code, submodules help maintain organised and efficient workflows.

By mastering submodules, you can:
✅ Simplify dependency management
✅ Keep projects modular and scalable
✅ Track exact versions of external code

Up next: git blame -L – See who changed a specific line in a file

Daily advance GIT tips in your inbox—worth starting? Respond to my poll here🚀
For more useful and innovative tips and tricks, Let's connect on Medium