Skip to content

Submodule

In one line

A submodule is a repository embedded inside another repository — it lets you include a foreign repo as a subdirectory while keeping it as its own repo.

In simple words

A Git submodule is a repository nested inside another repository. The parent repo stores a reference to a specific commit of the submodule, not the submodule's full history. This lets you include external projects (libraries, shared components) as subdirectories.

Submodules are useful for sharing code between projects without duplicating it. However, they are notoriously tricky to work with: cloning a repo with submodules requires --recursive, updating submodules requires specific commands, and team members must coordinate submodule versions.

Alternatives to submodules include package managers (npm, pip) for language-specific dependencies, or Git subtrees (which copy the content into the parent repo). Consider whether a submodule is truly necessary before using one.

Example

bash
# Add a submodule
git submodule add https://github.com/user/library.git lib

# Clone a repo with submodules
git clone --recursive https://github.com/user/project.git

# Update all submodules
git submodule update --remote

Submodules embed repos inside repos. Use --recursive when cloning.

Related terms

Related Resources

Related Lessons

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to glossary