2nd/10_Wiki/Topics/Frontend/Submodules.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-submodules	Submodules	10_Wiki/Topics	verified	self	Git Submodules git submodule	none	A	0.9	applied	git submodules monorepo vendoring		2026-05-10	pending	language framework bash git

Submodules

매 한 줄

"매 repo-in-repo with pinned commit". Git submodule 매 외부 repository 의 specific commit 의 reference 의 host repo 안 의 nest. 매 2026 perspective: monorepo / package manager (pnpm workspaces, npm workspaces) 의 대부분 의 use case 의 replace, 매 vendoring binary asset, plugin SDK, firmware blob 의 niche 의 survive.

매 핵심

매 동작 model

• 매 host repo 의 .gitmodules file 의 url + path 의 list.
• 매 host repo 의 tree object 의 submodule path 의 gitlink (commit SHA) 의 store — 매 file 의 X.
• 매 git clone 의 default 의 submodule 의 fetch X — 매 --recursive 또는 git submodule update --init.
• 매 detached HEAD state 의 submodule 의 default — 매 branch tracking 의 explicit opt-in.

매 typical pitfall

• 매 host commit 의 update X 의 submodule pointer 의 stale.
• 매 force-push 의 submodule remote 의 host 의 SHA 의 missing — fetch fail.
• 매 nested submodule 의 --recurse-submodules 의 forget 의 partial checkout.
• 매 CI 의 shallow clone 의 submodule 의 not 의 init.

매 응용

1. Vendoring third-party C/C++ library (FFmpeg, OpenSSL).
2. Sharing firmware blob 의 multiple device repo.
3. Plugin / theme SDK 의 host application 의 embed.
4. Documentation site 의 example code 의 separate repo 의 pin.

💻 패턴

Add submodule

git submodule add https://github.com/org/lib.git vendor/lib
git commit -m "Add vendor/lib submodule"

Clone with submodules

git clone --recurse-submodules https://github.com/org/host.git
# 또는 매 already-cloned repo
git submodule update --init --recursive

Update submodule to latest

cd vendor/lib
git fetch && git checkout v2.5.0
cd ../..
git add vendor/lib
git commit -m "Bump vendor/lib to v2.5.0"

Pull host + sync submodule pointers

git pull --recurse-submodules
git submodule update --init --recursive

Track branch (not detached)

git submodule add -b main https://github.com/org/lib.git vendor/lib
git config -f .gitmodules submodule.vendor/lib.update merge
git submodule update --remote --merge

Remove submodule (2026 way)

git submodule deinit -f vendor/lib
git rm -f vendor/lib
rm -rf .git/modules/vendor/lib
git commit -m "Remove vendor/lib submodule"

Foreach run command across all

git submodule foreach --recursive 'git status'
git submodule foreach 'git checkout main && git pull'

CI shallow + submodule

# GitHub Actions 매 example
- uses: actions/checkout@v4
  with:
    submodules: recursive
    fetch-depth: 0

매 결정 기준

상황	Approach
JS/TS shared lib	pnpm workspace 또는 npm workspace
Polyglot monorepo 의 source share	git subtree (history merged)
Binary asset 의 pin (firmware, large model)	submodule
Third-party C/C++ vendoring	submodule 또는 vcpkg/Conan
Plugin SDK 의 host 의 embed	submodule (pinned SHA)
Multi-language CI 의 partial checkout	sparse-checkout + submodule

기본값: 매 JS/TS 의 monorepo 의 workspaces 의 use, 매 submodule 의 binary / cross-ecosystem vendoring 의 reserve.

🔗 Graph

• 부모: Version Control
• 변형: Monorepo

🤖 LLM 활용

언제: 매 binary asset 또는 cross-language vendor lib 의 pin 의 specific upstream commit 의 reproducibility 의 require. 언제 X: 매 JS/TS 의 shared package — 매 workspace 의 strictly superior. 매 frequently-edited shared code — 매 subtree 또는 monorepo 의 prefer.

❌ 안티패턴

• Submodule 의 active dev: 매 submodule 안 의 daily edit 의 host pointer 의 forever-out-of-date — 매 monorepo 의 promote.
• Force-push 의 upstream: 매 host repo 의 referenced SHA 의 lose — 매 fetch fail forever.
• git submodule update 의 forget: 매 host pull 후 의 stale submodule 의 confusing diff.
• Nested submodule 의 5+ level: 매 cognitive overhead 의 explode — 매 flatten 의 prefer.
• Submodule 의 source-of-truth treat: 매 fork 의 publish 의 X 의 host-only patch 의 lose.

🧪 검증 / 중복

• Verified (Git docs git-submodule(1), Pro Git Book Ch. 7.11).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — submodule lifecycle, CI, anti-patterns