Introduction to Git Submodules
Understand what Git submodules are, their use cases, and when they are a suitable solution for managing dependencies.
Introduction to Git Submodules is a free Git Advanced: Monorepo, Submodules & Workflows lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Git Advanced: Monorepo, Submodules & Workflows learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Welcome to Submodules
What are Git Submodules? They let you embed one Git repository inside another as a sub-directory. It's like having a separate project living inside your main project, but still managed independently.
Why Use Submodules?
Imagine your project needs a specific library or component that's developed and maintained separately. Instead of copying its code, you can use a submodule.
- Vendor Code: Include third-party libraries.
- Shared Components: Reusable code across multiple projects.
- Plugin Systems: Modularize parts of a larger application.
A Repo within a Repo
A submodule isn't just a folder of files. It's a pointer to a specific commit in another Git repository. Your main project tracks which commit of the submodule it should use.
This means your main project doesn't directly manage the submodule's content, but rather its reference.
How Git Tracks Submodules
Git stores submodules as a special entry in your main repository's index. It records the submodule's path, the URL of its remote repository, and the specific commit hash it currently points to.
When you clone a project with submodules, you'll initially see empty directories until you initialize and update them.
Submodule's Independent Life
Each submodule is its own standalone Git repository. You can clone it, switch branches, commit changes, and push them, all independently of the parent repository.
This isolation is key to managing external dependencies without merging their history into your main project.
Common Use Cases
Submodules are excellent for:
- Stable Dependencies: When you need a specific version of an external library and don't want it to change unexpectedly.
- Large Components: Breaking down a monolithic project into smaller, manageable, independently versioned parts.
- Open-Source Contributions: Integrating external tools or frameworks without maintaining their source directly.
When Submodules Shine
They are particularly useful when:
- You need to track a specific version of a dependency, not just the latest.
- The dependency is managed by a different team or project.
- You want to keep the dependency's history separate from your main project's history.
The .gitmodules File
When you add a submodule, Git creates a special configuration file at the root of your main repository: .gitmodules.
This file stores the mapping between the submodule's local path and its remote URL. It's version-controlled, so everyone cloning your project knows about its submodules.
[submodule "library"]
path = lib/my-library
url = https://github.com/user/my-library.gitSubtree vs. Submodule (Brief)
While submodules are great, they have alternatives. One notable option is Git Subtree.
Submodules keep the dependency's history separate, while Git Subtree integrates the dependency's history directly into your main repository. We'll explore Subtree in a later lesson!
Quick Check on Submodules
Let's check your understanding of Git submodules.
Recap: Intro to Submodules
We've introduced Git submodules, understanding them as a way to embed independent Git repositories within your main project.
- They track specific commits of external repos.
- They solve problems of shared code and stable dependencies.
- They are configured via the
.gitmodulesfile.
Next, we'll learn how to add and clone submodules.
Frequently asked questions
Is the “Introduction to Git Submodules” lesson free?
Yes — the full text of “Introduction to Git Submodules” is free to read here on the web, and the Git Advanced: Monorepo, Submodules & Workflows course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Git Advanced: Monorepo, Submodules & Workflows course, upgrade to CoddyKit PRO.
What will I learn in “Introduction to Git Submodules”?
Understand what Git submodules are, their use cases, and when they are a suitable solution for managing dependencies. You practise Git Advanced: Monorepo, Submodules & Workflows with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Git Advanced: Monorepo, Submodules & Workflows?
No prior experience is required. Git Advanced: Monorepo, Submodules & Workflows on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Introduction to Git Submodules” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Git Advanced: Monorepo, Submodules & Workflows lesson?
Yes. Every Git Advanced: Monorepo, Submodules & Workflows lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Introduction to Git Submodules
- Adding and Cloning Submodules
- Updating and Synchronizing Submodules
- Removing and Deinitializing Submodules