1. Home
  2. Blog
  3. DevOps

DevOps

Git Submodule Explained: Add, Clone, Update and Remove Safely

A git submodule embeds one Git repository inside another at a fixed commit, which is how projects share libraries, themes or vendor code without copying them. Submodules are also famous for confusing people. We walked through the full life cycle in a test repository: adding one, cloning a project that uses it, updating it, the detached HEAD trap, and removing it cleanly.

9 min read
Git submodule explained: add, clone, update and remove safely

Key takeaways

  • A git submodule records a path, a URL in .gitmodules and one exact commit of the other repository.
  • A plain git clone left the submodule folder empty until we ran git submodule update --init --recursive.
  • When the library gained a new commit, the parent stayed on the old one until git submodule update --remote and a new commit in the parent.
  • Submodule checkouts sat on a detached HEAD, and git rm left a copy of the submodule repository behind in .git/modules.

Sometimes one repository needs another: an application uses a shared library, a website uses a theme, a firmware build includes a vendor SDK. Copying the code loses its history and makes updates painful. A git submodule keeps the other project as its own repository inside yours, pinned to a specific commit, so everyone builds against exactly the same version.

We built a small library repository and an application that uses it, then ran every step on Git 2.56.0. Paths in the output are shortened to /work.

What is a git submodule?

A submodule is a pointer from the parent repository (the superproject) to a commit in another repository. The parent does not store the submodule’s files; it stores the path, the URL and the commit ID. When you check out the submodule, Git clones the other repository into that path and checks out exactly that commit.

Our test setup

lib.git    a bare repository holding util.py with VERSION = '1.0'
app        the application repository, which will use lib as a submodule

Adding a submodule

git submodule add ../lib.git vendor/lib
Cloning into '/work/app/vendor/lib'
done.

cat .gitmodules
[submodule "vendor/lib"]
	path = vendor/lib
	url = ../lib.git

git status --short
A  .gitmodules
A  vendor/lib

git submodule add URL PATH clones the repository into the path, creates or updates .gitmodules, and stages both. You then commit as usual. We used a relative URL, which resolves against the parent’s own remote; in real projects this is usually an HTTPS or SSH URL, configured like any git remote.

What the parent actually stores

git submodule status
 9f851faf41b201abc77cc98459a8a0f75459cef1 vendor/lib (heads/main)

git ls-tree HEAD vendor/lib
160000 commit 9f851faf41b201abc77cc98459a8a0f75459cef1	vendor/lib

The parent’s tree contains a special entry with mode 160000 and type commit: a single commit ID, not files. That is the whole trick. The superproject says “use lib at commit 9f851fa”, and nothing changes until someone commits a different ID.

The empty folder after a normal clone

git clone app.git clone1
ls clone1/vendor/lib          # []  empty

git submodule status
-9f851faf41b201abc77cc98459a8a0f75459cef1 vendor/lib

This is the most common submodule surprise. A normal clone created the vendor/lib folder but left it empty, and builds that need the library fail with “file not found”. The minus sign in git submodule status means “not initialised”.

Filling it: update –init –recursive

git submodule update --init --recursive
Submodule 'vendor/lib' (/work/lib.git) registered for path 'vendor/lib'
Cloning into '/work/clone1/vendor/lib'
done.
Submodule path 'vendor/lib': checked out '9f851faf41b201abc77cc98459a8a0f75459cef1'

ls clone1/vendor/lib          # ['.git', 'util.py']

--init copies the submodule settings from .gitmodules into your local configuration, and update clones and checks out the pinned commit. --recursive does the same for submodules inside submodules. This one command is worth putting in your project’s setup instructions and CI scripts.

Cloning with submodules in one step

git clone --recurse-submodules app.git clone2
# clone2/vendor/lib/util.py exists: True

Adding --recurse-submodules to the clone fills every submodule straight away. Hosted CI systems usually have a checkout option for the same thing, for example the submodules setting of the checkout action in our GitHub Actions guide.

Submodules are pinned, not live

# the library gets a new commit upstream: "lib v1.1"
git submodule status          # in clone1
 9f851faf41b201abc77cc98459a8a0f75459cef1 vendor/lib (heads/main)   still the old commit

After the library moved forward, the application still used the old commit. This is deliberate: a change in the library cannot break the application until someone chooses to update. It is also why a submodule can quietly fall far behind, so schedule updates rather than forgetting them.

Updating a submodule to the latest commit

git submodule update --remote
From /work/lib
   9f851fa..84addbb  main       -> origin/main
Submodule path 'vendor/lib': checked out '84addbb2ff27bd2e8daa037abce418ee8888619d'

git status --short
 M vendor/lib

git diff --submodule=log
Submodule vendor/lib 9f851fa..84addbb:
  > lib v1.1

git commit -am "bump lib to v1.1"

--remote fetches the submodule’s remote and checks out the latest commit of its tracked branch (the default branch, unless branch is set in .gitmodules). The parent now shows the submodule as modified, and git diff --submodule=log lists the library commits you are pulling in, which is exactly what a reviewer needs to see. Committing records the new pointer; until then, teammates still get the old version. After a teammate pulls that commit, they run git submodule update to move their checkout, or use git pull --recurse-submodules.

The detached HEAD trap

cd clone2/vendor/lib
git status --short --branch
## HEAD (no branch)

Submodules are checked out at a specific commit, not on a branch, so they are in a detached HEAD state. If you edit and commit inside the submodule now, the commit belongs to no branch and is easy to lose on the next update. Before changing code inside a submodule, run git switch main (or create a branch) in the submodule, commit and push there first, then commit the new pointer in the parent. Our git branch guide explains detached HEAD in more detail.

Tip: push the submodule’s commits before pushing the parent. If the parent points at a commit that only exists on your machine, everyone else’s update fails.

Running a command in every submodule

git submodule foreach git log --oneline -1
Entering 'vendor/lib'
84addbb lib v1.1

foreach runs any shell command inside each checked-out submodule, useful for status reports, pulling, or cleaning. Add --recursive to include nested submodules.

Removing a submodule cleanly

git submodule deinit -f vendor/lib
Cleared directory 'vendor/lib'
Submodule 'vendor/lib' (../lib.git) unregistered for path 'vendor/lib'

git rm vendor/lib
git status --short
M  .gitmodules
D  vendor/lib

# .gitmodules is now empty
# .git/modules/vendor/lib still exists: True

deinit removes the working files and the local configuration, and git rm deletes the pointer and its entry in .gitmodules. Commit the result. One thing is left behind: Git keeps the submodule’s own repository in .git/modules/vendor/lib, so re-adding it later is fast. Delete that folder manually if you want the space back or plan to add a different repository at the same path. Leftover files outside Git’s tracking can be checked with git clean, which skips nested repositories unless forced twice.

The “transport ‘file’ not allowed” error

git submodule add ../lib.git vendor/lib2
fatal: transport 'file' not allowed
fatal: clone of '/work/lib.git' into submodule path '/work/app/vendor/lib2' failed

Since Git 2.38.1, cloning submodules from local file paths is blocked by default, a security fix against malicious repositories. Real projects use network URLs and are unaffected. For local experiments like ours, Git must be told to allow the file protocol for that command, which is how we ran the rest of this walkthrough; do not enable it globally on machines that clone untrusted repositories.

Alternatives to submodules

  • Package managers (pip, npm, Maven, Go modules): usually the best choice for libraries with versioned releases.
  • git subtree: copies another repository’s history into a folder of yours; no extra commands for people who clone, but updates are more manual.
  • Monorepo: keep related projects in one repository with shared tooling.
  • Submodules fit best when you need an exact commit of a repository that is not packaged, such as firmware SDKs, shared configuration or themes.

For working on two versions side by side instead, see git worktree; for everyday commands, our Git cheat sheet.

Final thoughts

A git submodule is simply a pointer to one commit of another repository. Most problems come from forgetting that: a fresh clone needs update --init --recursive, upstream changes arrive only after update --remote and a commit in the parent, and submodule checkouts sit on a detached HEAD until you switch to a branch. Push submodule commits before the parent, review updates with diff --submodule=log, and remove submodules with deinit plus rm. Follow that routine and submodules become predictable rather than painful.

Frequently asked questions

What is a git submodule?

A reference from one Git repository to a specific commit of another repository, checked out into a folder. The parent stores only the path, URL and commit ID, not the files.

Why is my submodule folder empty after cloning?

A normal clone does not fetch submodules. Run git submodule update with the init and recursive options, or clone with the recurse submodules option next time.

How do I update a submodule to the latest version?

Run git submodule update with the remote option to check out the newest commit of the tracked branch, then commit the changed submodule pointer in the parent repository.

Why is my submodule in detached HEAD state?

Submodules are checked out at the exact commit the parent records, not on a branch. Switch to a branch inside the submodule before making commits there.

How do I remove a git submodule?

Run git submodule deinit on the path, then git rm on the path, and commit. Optionally delete the leftover copy inside the git modules folder of the parent repository.

Keep learning

Work with Stack Quora

Need help with testing, WordPress or SEO?

We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.

Keep reading

More guides on testing, AI & modern development

Enjoyed this article? Pick a topic and jump straight into our newest tutorials.

Artificial Intelligence

Confusion Matrix Explained: Precision, Recall, F1 and Thresholds in Python

Confusion matrix explained with Python: TP, FP, FN, TN, precision, recall, F1, the accuracy trap, threshold choice by cost and…

Read article →
Software Development

API Pagination: Offset vs Cursor vs Keyset, Tested on 1 Million Rows

API pagination explained: offset vs keyset and cursor pagination timed on 1 million rows, duplicates when data changes, the ties…

Read article →
DevOps

Git Submodule Explained: Add, Clone, Update and Remove Safely

Git submodule explained: add, clone, update –init, update –remote, the detached HEAD trap, foreach and clean removal, tested step by…

Read article →
Test Automation

Pytest tmp path Explained: tmp_path, tmp_path_factory and Temp Files

Pytest tmp_path explained: per-test temporary folders, tmp_path_factory for shared files, monkeypatch.chdir, legacy tmpdir, retention and basetemp.

Read article →
Software Testing

Test Case Prioritization: 6 Techniques Compared With APFD

Test case prioritization compared: risk, coverage, cost, history and random orders scored with APFD and time to find all faults…

Read article →
Databases & SQL

Full Text Search in SQL: FTS5, Ranking, Phrases and Speed

Full text search in SQL with SQLite FTS5: MATCH queries, phrases, prefixes, NEAR, stemming, BM25 ranking, snippets, two gotchas and…

Read article →
Databases & SQL

Generated Columns in SQL: Virtual vs Stored, Indexes and Limits

Generated columns in SQL explained: virtual vs stored, automatic updates, write errors, storage cost, indexing, JSON fields and support in…

Read article →
Software Development

Object Freeze in JavaScript: Shallow vs Deep, Seal and const

Object freeze in JavaScript explained: freeze vs seal vs const, strict mode errors, shallow vs deep freeze, frozen arrays, Map…

Read article →
Software Development

Python hashlib: SHA-256, File Hashes, HMAC and Password Hashing

Python hashlib explained: SHA-256 for strings and files, algorithm speeds, why passwords need PBKDF2 or scrypt, safe verification and HMAC…

Read article →
Software Development

Python UUID Explained: uuid1, uuid4, uuid5, uuid7 and Database Keys

Python UUID explained: uuid4, uuid5, uuid1 privacy, time-ordered uuid7, parsing, storage formats and UUIDs as database keys, tested on Python…

Read article →
Artificial Intelligence

Random Forest in Python: Bagging, Feature Sampling and OOB From Scratch

Random forest in Python from scratch: bootstrap sampling, feature sampling, number of trees, out-of-bag evaluation and impurity vs permutation importance.

Read article →
Software Development

MIME Types Explained: Content-Type, nosniff and a Common Types List

MIME types explained and tested in a browser: Content-Type, nosniff, scripts and stylesheets with wrong types, a common MIME types…

Read article →
DevOps

Git Clean Explained: Remove Untracked Files Without Regret

Git clean explained with dry runs: -n, -f, -d, -x, -X, exclusions, paths, nested repositories and interactive mode, plus a…

Read article →
Test Automation

Pytest approx: Comparing Floats With rel, abs and Collections

Pytest approx explained: default tolerances, the near-zero trap, rel and abs, lists and dicts, NaN, NumPy, and how it differs…

Read article →
Software Testing

Accessibility Testing: WCAG Checklist, Automated Tools and Manual Checks

Accessibility testing explained: WCAG basics, an axe-core scan of a broken and a fixed page, what automation missed, contrast checks…

Read article →
Databases & SQL

SQL UNPIVOT: Turn Columns Into Rows, 4 Ways Tested

SQL UNPIVOT explained: turn columns into rows with UNION ALL, CROSS JOIN with CASE, JSON functions or native UNPIVOT, with…

Read article →
Software Development

Intl NumberFormat in JavaScript: Currency, Compact, Percent and Units

Intl.NumberFormat in JavaScript: locales, currency, compact notation, percent, units, rounding, formatToParts, the non-breaking space trap and formatter reuse.

Read article →
Databases & SQL

SQL EXPLAIN Plan: How to Read Query Plans and Fix Slow Queries

SQL EXPLAIN plan explained: read scans, index searches, covering indexes and temporary sorts, with before and after timings for five…

Read article →
Artificial Intelligence

Decision Tree in Python: Gini, Entropy and Overfitting From Scratch

Decision tree in Python from scratch: Gini impurity, entropy, information gain, best splits, readable rules, and how depth and leaf…

Read article →
DevOps

Git Blame Explained: Find Who Changed a Line, and Why

Git blame explained with a real repository: ignore whitespace, line ranges and functions, ignore-revs files for formatting commits, moved code…

Read article →
Test Automation

Pytest Benchmark: Measure Speed and Catch Performance Regressions

Pytest benchmark tutorial: the benchmark fixture, reading results, parametrized and pedantic benchmarks, saving baselines and failing the build on regressions.

Read article →
Software Testing

Defect Density: Formula, Worked Examples and How to Use It

Defect density explained: the formula, a five-module worked example, per KLOC vs per function point, severity weighting, defect removal efficiency…

Read article →
Databases & SQL

Case Insensitive Search in SQL: LOWER, LIKE, COLLATE and Indexes

Case insensitive search in SQL: LOWER, LIKE, COLLATE NOCASE and expression indexes compared with query plans, plus accented letters and…

Read article →
Databases & SQL

ON DELETE CASCADE in SQL: CASCADE vs SET NULL vs RESTRICT

ON DELETE CASCADE in SQL tested: CASCADE vs SET NULL vs RESTRICT, multi-level cascades, the SQLite foreign key pragma, row…

Read article →
Artificial Intelligence

Logistic Regression in Python: Sigmoid, Log Loss and Gradient Descent From Scratch

Logistic regression in Python from scratch: sigmoid, log loss, gradient descent, odds ratios, thresholds, sigmoid overflow and separable data, tested…

Read article →
DevOps

Git Worktree Explained: Work on Two Branches at Once

Git worktree explained: add, list, remove, prune, lock and detached worktrees, a hotfix workflow, and the errors you will hit,…

Read article →
Test Automation

Pytest ini Explained: addopts, markers, testpaths and Precedence

Pytest ini explained: testpaths, addopts, strict markers, xfail_strict, filterwarnings, minversion, config file precedence and command-line overrides, tested.

Read article →
Software Testing

Test Estimation Techniques: WBS, Three Point PERT and Monte Carlo

Test estimation techniques worked through: WBS, three point PERT, total uncertainty, a Monte Carlo check, percentage rules and Wideband Delphi.

Read article →
Artificial Intelligence

Linear Regression in Python: Least Squares From Scratch, With R Squared

Linear regression in Python from scratch: closed form, NumPy least squares and gradient descent, R squared, RMSE, outliers and curved…

Read article →
DevOps

Git Remote Explained: Add, Set-URL, Rename, Remove and Push URLs

Git remote explained: add, set-url, separate push URLs, rename, remove and prune, plus how to avoid leaking tokens in remote…

Read article →
Test Automation

Pytest Mock: mocker.patch, spy, side_effect and autospec Explained

Pytest mock explained: mocker.patch, return_value, side_effect, spy, autospec and PropertyMock, with tested examples for APIs, clocks and retries.

Read article →
Software Testing

System Testing Explained: Types, Process and a Real End-to-End Example

System testing explained: types, entry and exit criteria, the process, and a real end-to-end test suite run against a small…

Read article →
Artificial Intelligence

Naive Bayes Classifier Explained: Build a Spam Filter in Python

Naive Bayes classifier explained by building a spam filter in Python: Bayes rule, the naive assumption, Laplace smoothing, log probabilities…

Read article →
DevOps

Git Branch Explained: Create, Switch, Rename, Delete and Recover

Git branch explained with tested commands: list, create, switch, rename, delete, merged checks, recovering deleted branches, remote tracking and naming.

Read article →
Test Automation

Pytest raises: Testing Exceptions, match and excinfo

Pytest raises explained with tested examples: match regexes, excinfo, custom and chained exceptions, parametrized error cases, pytest.warns and common mistakes.

Read article →
Software Testing

Non Functional Testing: Types, Metrics and a Real Load Test

Non functional testing explained: 10 key types, measurable requirements, latency percentiles and what a small real load test revealed about…

Read article →