Introduction

Managing large codebases or integrating third-party compoinents into your project can quickly become a challenge. Git submodules offer a powerful solution for keeping your main repository lightweight while maintaining strong links to external code.

In this guide, you'll learn how to add a specific branch of another repository as a submodule, why you should never delete the submodule folder before pushing, and best practices for a clean, efficient workflow.

Why Use Git Submodules ?

Submodules let you include another Git repository inside your project as a reference, not as a full copy. This is perfect for:

• Integrating shared libraries or tools
• Keeping your repository size manageable
• Ensuring all collaborators use the same version of a dependency

Step-by-Step: Adding a Submodule on a Specific Branch

Scenario

You have a main repository (repo1), lets say you are working on (branch0) and you want to add the the branch (branch1) of another repo (repo2)as a submodule under folder1 (repo1/folder1)

Step 1: Navigate to Your Main Repo or Clone

# git clone -b branch1 <url of repo1>
cd repo1

Step 2: Switch to the Correct Branch

git checkout branch0

Step 3: Add the Submodule

git submodule add -b branch1 <url of repo2> folder1/repo2

Step 4: Initialize and Update the Submodule

git submodule update --init --recursive

Step 5: Commit and Push Changes

cd /path/to/repo1
git add .
git commit -m "Added repo2 as a submodule under folder1"
git push

Daily Usage:

Clean Clone:

git clone --recurse-submodule -b branch0 <url of repo1>

Pre-Cloned:

cd /path/to/repo1
git submodule update --init --recursive

F.A.Q

Should You Delete the Submodule Folder before Pushing ?

NO!

Deleting the submodule folder before pushing will remove the submodule from your project.

Why ?

• Git only stores a reference (pointer) to the submodule, not the full code.
• Your main repository remains lightweight by design.
• Deleting the folder removes the reference, breaking the link for your collaborators.

Best Practices for Submodules

• Always commit and push both the .gitmodules file and the submodule reference
• Use --recurse-submodules flag when cloning to ensure all submodules are fetched.
• Run git submodule update --init --recursive after cloning if needed.
• Never delete the submodule folder after adding it (Let Git manage the reference for you).

Conclusion

Git submodules are a robust way to manage dependencies and shared code in large projects. By following these best practices, you can keep you main repository clean, lightweight, and easy for collaborators to use.

Happy Coding ! :D