Himanshu SharmaSoftware engineer
Let’s talk

Git and GitHub · Lesson 26 of 30

Submodules: a repository inside a repository

Learn what Git submodules are, how to add, clone and update one, how the parent records an exact commit, and why many teams prefer other ways to share code.

13 minPower toolsUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonAdd a submodule, clone a project that has one, update the submodule to a newer commit, and explain the main pitfalls briefly.

What you can do after this lesson

You will be able to recognise a submodule when you meet one, add one, clone a project that uses them, and update them without confusing yourself. This is a brief look at an advanced feature. Many projects never need submodules, and the lesson ends with alternatives you may prefer. The commands here were run in a temporary folder using local bare repositories; paths in the output are generic.

The idea

Sometimes your project depends on code that lives in another Git repository, such as a shared widget library, and you want to keep it separate but pinned to a known version. A submodule does that. In your repository there is a folder, say vendor/widgets, which is a full clone of the other repository. Your repository does not copy the other repository's files into its history. It records one thing: "this folder is repository X at commit Y".

Adding a submodule

We set up a fictional widgets repository and an app repository that depends on it. Inside app:

bash
git -c protocol.file.allow=always submodule add ../widgets.git vendor/widgets
git status -s
text
Cloning into '/home/you/sm/app/vendor/widgets'...
done.
A  .gitmodules
A  vendor/widgets

(The -c protocol.file.allow=always option is needed here only because the example uses a local path as the source. Git blocks local file paths for submodules by default as a safety measure. With an https:// or SSH address you do not need it, and you should not enable it globally.)

Two things were staged: a new .gitmodules file and an entry for the submodule path. Look at the file:

bash
cat .gitmodules
text
[submodule "vendor/widgets"]
	path = vendor/widgets
	url = ../widgets.git

Commit them like any change. Then examine what the parent really stores:

bash
git commit -m "Add widgets submodule"
git ls-files -s vendor/widgets
text
[main 6e6e2a7] Add widgets submodule
 2 files changed, 4 insertions(+)
 create mode 100644 .gitmodules
 create mode 160000 vendor/widgets
160000 68d1c3ae3201f7e1b84406463400a5f7f7267320 0	vendor/widgets

The mode 160000 is Git's marker for "this is a commit in another repository", and the hash is the exact widgets commit the parent points at. Hashes differ in your own run.

Cloning a project that has submodules

When someone else clones app, the submodule folder arrives empty:

bash
git clone app app-clone
ls app-clone/vendor/widgets

The listing prints nothing because the folder exists but has no files. Fetch them with:

bash
git submodule update --init
ls vendor/widgets
git submodule status
text
Submodule 'vendor/widgets' (/home/you/sm/widgets.git) registered for path 'vendor/widgets'
Cloning into '/home/you/sm/app-clone/vendor/widgets'...
done.
Submodule path 'vendor/widgets': checked out '68d1c3ae3201f7e1b84406463400a5f7f7267320'
widget.txt
 68d1c3ae3201f7e1b84406463400a5f7f7267320 vendor/widgets (heads/main)

(In the practice run the clone needed the same -c protocol.file.allow=always option because of the local path.) To do everything in one step, clone with git clone --recurse-submodules <url>. A teammate who forgets either of these will see an empty folder and wonder why the build is missing files.

Updating a submodule

Say the widgets project publishes a new commit. The submodule folder is a normal repository, so you move it forward inside:

bash
cd vendor/widgets
git pull origin main
cd ../..
git status -s
text
Updating 68d1c3a..858ebbb
Fast-forward
 widget.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
 M vendor/widgets

The parent now reports M vendor/widgets: the pointer is out of date compared with what is checked out. Record the new version in the parent so teammates get it:

bash
git add vendor/widgets
git commit -m "Update widgets to v2"
git submodule status
text
 858ebbb37c3ba7346034484ab9fb3b348c507fa3 vendor/widgets (heads/main)

Teammates then run git pull followed by git submodule update to move their copy to the new commit. A shortcut for pulling new upstream commits in all submodules is git submodule update --remote, which follows the branch configured for the submodule.

Pitfalls

  • Detached HEAD inside the submodule. After git submodule update the submodule is checked out at a specific commit, not on a branch. If you edit there and commit, create a branch first, or the commit is easy to lose.
  • Forgetting to push the submodule. If you commit in the submodule and update the parent pointer but never push the submodule's own commits, teammates cannot fetch that commit.
  • Forgetting to commit the pointer. Updating the submodule is invisible to others until the parent records it.
  • Empty folders after clone. Remember --recurse-submodules or submodule update --init.
  • Removing one. Deleting a submodule has several steps (deinit, remove the entry and the .gitmodules lines); follow git help submodule rather than deleting the folder by hand.

Alternatives

Before adding a submodule, consider whether something simpler fits:

  • A package manager (Composer for PHP, npm for JavaScript) records versions of libraries in a lock file, with no extra Git concepts.
  • Copying the files in, if they rarely change and the licence allows it.
  • A monorepo, one repository containing both projects.
  • A subtree merge, an alternative Git feature that copies another project's history in; its documentation is in the Git manual.

Submodules suit cases where you need an exact pinned commit of an external repository, perhaps your own shared code that is developed separately.

Common mistakes

  • Assuming a normal clone gets submodule files. It does not.
  • Editing inside the submodule without a branch. Work can be lost.
  • Changing the submodule but not committing the pointer. The parent thinks nothing changed.
  • Using local path URLs in a shared project. Use a URL others can reach.
  • Adding submodules casually. The team pays the cost every day.

Exercise

  1. Create a bare repository lib.git with one commit, and a separate repository app.
  2. Add lib.git to app as a submodule (you will need the protocol.file.allow option for a local path), and commit.
  3. Clone app and fill the submodule folder.
  4. Commit a change in lib.git, update the submodule in app, and commit the new pointer.
Show one possible answer
bash
git -c protocol.file.allow=always submodule add ../lib.git vendor/lib
git commit -m "Add lib submodule"
git -c protocol.file.allow=always clone app app-clone
cd app-clone && git -c protocol.file.allow=always submodule update --init
cd ../app/vendor/lib && git pull origin main
cd ../.. && git add vendor/lib && git commit -m "Update lib"

git submodule status shows the new commit hash after each step.

Next: Git hooks: running scripts at commit time.

Key points

  • A submodule embeds another repository inside yours at a fixed path, pinned to one specific commit.
  • The parent stores the submodule's URL in .gitmodules and its commit hash in the tree; it does not store the submodule's files.
  • A plain git clone leaves submodule folders empty; run git submodule update --init (or clone with --recurse-submodules).
  • To update a submodule, move it to a newer commit inside its folder, then commit the new pointer in the parent.
  • Submodules add complexity; consider a package manager or a plain copy first, and use them when you really need a pinned external repository.

Check yourself

1. What does the parent repository record about a submodule?
2. You cloned a project with a submodule and the submodule folder is empty. What do you run?
3. You pulled newer commits inside the submodule folder. What must you do in the parent for teammates to get them?
4. Which statement about submodules is fair?