Một lần clone mới trên CI runner chết ngay từ đầu, chưa kịp chạy test nào:
fatal: remote error: upload-pack: not our ref b81f2aa3c47e0d9e1f62a8b5c0d47e19f3a6b2c8
fatal: Fetched in submodule path 'backend', but it did not contain b81f2aa3c47e0d9e1f62a8b5c0d47e19f3a6b2c8. Direct fetching of that commit failed.Code chẳng có lỗi gì. Chỉ là có người đã push repo cấp trên trong khi commit mà nó trỏ tới vẫn còn nằm trên laptop của họ. Máy họ chạy ngon. Máy mọi người khác thì gãy, cho tới khi họ chịu push thêm lần nữa.
Dòng lỗi đó gói gọn cả bài viết này. Git submodule là một con trỏ tới đúng một commit trong một repository khác. Mọi quy tắc trong quy trình bên dưới, kể cả quy tắc "AI agent không bao giờ đụng vào lịch sử Git", đều suy ra từ câu đó, miễn là bạn chịu hiểu nó cho đến nơi đến chốn.
Bối cảnh là một nền tảng gồm một repo backend (Nx monorepo với mười ba service NestJS), một repo frontend, và một repo mỏng ở cấp trên để buộc hai cái lại với nhau. Hệ thống vẫn đang là prototype, nên những gì dưới đây là quy trình đang có trong repository, cộng với những chỗ tôi muốn siết lại, chứ không phải chuyện chạy production.
Meta-repo là gì, và vì sao cần nó?
Repo cấp trên, gọi là meta-repo, gần như không chứa code ứng dụng. Trong đó có tài liệu kiến trúc và API, sequence diagram, Postman collection, các file rule mà AI agent đọc, và đúng hai con trỏ: một tới backend, một tới frontend.
Backend và frontend mỗi bên có repo riêng, CI riêng, merge request riêng, nhịp làm việc riêng. Bên trong backend vốn đã là một monorepo, lý do nằm ở bài về Nx monorepo. Thứ meta-repo thêm vào là câu trả lời cho một câu hỏi mà nếu không có nó thì chẳng biết đặt ở đâu: backend bản nào đi với frontend bản nào, và bộ tài liệu nào mô tả đúng cặp đó?
Đây là phép so sánh tôi sẽ dùng xuyên suốt bài: meta-repo là lockfile dành cho repository.
package.json nói "tôi cần lodash, bản 4.x nào cũng được". package-lock.json thì nói "đúng bản này, với integrity hash này". Hiếm ai sửa lockfile bằng tay. Có người chủ động bump nó, và lần bump đó hiện ra khi review. Con trỏ submodule cũng y như vậy, và cách nó hỏng cũng y như vậy.
Git submodule thực chất là gì?
Một submodule có hai nửa, và người ta thường chỉ để ý tới một nửa.
Nửa thứ nhất là .gitmodules, một file text bình thường, cho biết lấy code ở đâu:
[submodule "backend"]
path = backend
url = ../backend.git
branch = main
[submodule "frontend"]
path = frontend
url = ../frontend.git
branch = mainNửa thứ hai nằm ngay trong tree. Thử hỏi Git xem backend là gì:
git ls-tree HEAD backend frontend160000 commit 9d04e1c... backend
160000 commit 3e7a51b... frontendMode 160000 là một gitlink. Nó không phải thư mục, cũng không phải file. Nó chỉ là một commit hash. Meta-repo không hề lưu file của backend; nó chỉ lưu "tôi cần commit nào của backend".
Vì vậy dòng branch = main rất dễ gây hiểu lầm. Nó không có nghĩa là "luôn đi theo main". Meta-repo lúc nào cũng ghi một commit cụ thể, giống hệt lockfile ghi một version cụ thể dù package.json chỉ ghi ^4.17.0. Dòng branch chỉ có tác dụng khi bạn chủ động đòi bản mới nhất bằng git submodule update --remote.
Nó cũng giải thích vì sao một "thay đổi" của submodule nhìn từ trên xuống lại trông như thế này:
diff --git a/backend b/backend
index 9d04e1c..b81f2aa 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 9d04e1c...
+Subproject commit b81f2aa...Toàn bộ diff chỉ có vậy. Hai cái hash. Giữa hai hash đó đã xảy ra chuyện gì thì bạn không thấy được, trừ khi tự đi xem.
Vì sao dùng URL tương đối trong .gitmodules?
URL ở đây là ../backend.git, không phải địa chỉ đầy đủ. Git sẽ resolve nó dựa trên remote mà chính meta-repo được clone về. Dev clone qua SSH hay CI runner clone qua HTTPS đều tìm đúng repo anh em, với đúng credential mà họ đang có.
Các repository trong dự án này từng chuyển sang một group Git mới, và .gitmodules không phải sửa dòng nào. Nhưng lần chuyển đó có một chỗ dễ đứt tay, và nó lại chính là lỗi ở đầu bài: các repo submodule phải được import trước meta-repo, và mỗi repo phải có đủ mọi commit mà gitlink của meta-repo đang ghim. Con trỏ chỉ đáng tin khi commit phía sau nó tồn tại.
Đọc git submodule status thế nào?
git submodule status 9d04e1c... backend (heads/main)
+b81f2aa... frontend (heads/feat/auth/session-ui)Thông tin nằm ở ký tự đầu tiên:
- dấu cách: commit đang checkout khớp với commit meta-repo ghi lại;
+: commit đang checkout khác với commit đã ghi;-: submodule chưa được init;U: gitlink đang bị merge conflict.
Dấu + không phải lỗi. Nó là một con trỏ đã dịch chuyển trong working tree của bạn nhưng chưa được commit. Nhớ nó nhé, nó sẽ quay lại ở phần nói về agent.
Vì sao submodule luôn bắt đầu ở detached HEAD?
Vì meta-repo đòi một commit, chứ không đòi một branch. git submodule update về cơ bản là chạy git checkout <hash-đã-ghi> bên trong submodule, mà checkout một hash trần thì bạn không đứng trên branch nào cả:
git clone --recurse-submodules <meta-repo-url> platform
cd platform/backend
git status
# HEAD detached at 9d04e1cNói theo kiểu lockfile, working tree của submodule chính là node_modules: một bản cài đặt đúng y những gì lockfile ghi. Bạn sửa file trong node_modules được. Lần install sau sẽ xóa sạch.
Đây là phiên bản "xóa sạch" từng làm người ta mất cả buổi chiều. Tôi dựng lại nó trong một repo nháp với submodule.recurse bật, giống như bản clone của dự án này:
cd backend # HEAD detached at a299b93
echo fix > z && git add z
git commit -m "fix the thing" # tạo ra ddb55ad, không thuộc branch nào
cd ..
git pull # repo cấp trên pull, rồi update luôn submodule
cd backend && git status
# HEAD detached at a299b93Lệnh pull chạy thành công. Submodule quay về commit đã ghi, còn ddb55ad giờ không nằm trên branch nào. Nó vẫn tồn tại, nhưng chỉ còn reflog nhớ tới nó:
git reflog -3
# a299b93 HEAD@{0}: pull
# ddb55ad HEAD@{1}: commit: fix the thing
# a299b93 HEAD@{2}: checkout: moving from main to a299b93...
git branch rescue/fix ddb55ad # đặt tên cho nó trước khi garbage collection dọn mấtCách tránh chỉ có một dòng, và phải làm đầu tiên, trước khi sửa bất cứ thứ gì:
cd backend
git switch main && git pull
git switch -c fix/auth/session-raceBranch là thứ giữ cho commit còn sống. Khi công việc của bạn đã nằm trên một branch, repo cấp trên muốn dời HEAD của submodule bao nhiêu lần cũng được; commit của bạn vẫn còn đó.
Sửa code trong submodule theo từng bước thế nào?
Thứ tự quan trọng hơn bản thân các lệnh:
# 1. Trong submodule: đứng lên một branch thật
cd backend
git switch main && git pull
git switch -c feat/auth/logout-endpoint
# 2. Commit bên trong submodule
git add -A
git commit -m "feat(auth): add logout endpoint (Closes #43)"
# 3. Push branch, mở merge request ở repo backend, merge ở đó
git push -u origin feat/auth/logout-endpoint
# 4. Quay về repo cấp trên, sau khi đã merge: dời con trỏ rồi commit
cd ..
git submodule update --remote backend
git add backend
git commit -m "chore(meta): bump backend"Bước 4 chính là lần bump lockfile. Nó cố tình nằm cuối cùng, và nó trỏ tới một commit đã được merge trong repo riêng của submodule.
Quy tắc in trên hình là thứ chặn được lỗi ở đầu bài: chỉ bump tới commit mà remote của submodule đã có. Nói theo kiểu lockfile: đừng bao giờ lock một version chưa từng được publish lên registry. Máy bạn install được vì package nằm sẵn trong cache. Máy người khác thì không.
Làm sao để không lỡ push con trỏ tới commit chưa push?
Git kiểm tra giùm bạn được:
git config push.recurseSubmodules checkVới check, push meta-repo sẽ bị từ chối nếu trong các commit được push có gitlink trỏ tới commit không nằm trên remote nào:
The following submodule paths contain changes that can
not be found on any remote:
backend
...
fatal: Aborting.Hãy set giá trị này một cách tường minh, kể cả khi bạn nghĩ mặc định đã an toàn. Theo tài liệu của Git, khi submodule.recurse là true mà push.recurseSubmodules chưa set thì nó hành xử như on-demand. Trong repo nháp của tôi, một lệnh git push bình thường ở meta-repo in ra Pushing submodule 'backend' rồi push thẳng lên main của backend, bỏ qua luôn merge request mà bước 3 dựa vào. check thì từ chối và báo cho bạn biết. on-demand thì tự quyết thay bạn.
Thêm hai setting nữa để lần bump đọc được, thay vì chỉ là hai cái hash:
git config diff.submodule log # diff liệt kê các commit giữa hai con trỏ
git config status.submoduleSummary true # git status cũng tóm tắt các commit đóĐặt tên branch, commit và lần bump thế nào?
| Cái gì | Định dạng | Ví dụ |
|---|---|---|
| Branch, ở repo nào cũng vậy | type/domain/description |
feat/auth/logout-endpoint |
| Commit trong submodule | type(scope): mô tả (Closes #N) |
feat(auth): add logout endpoint (Closes #43) |
| Bump con trỏ ở cấp trên | chore(meta): bump <tên> |
chore(meta): bump backend |
| Tài liệu ở cấp trên | docs(khu vực): mô tả |
docs(api): update auth sequences |
Scope meta chứng minh giá trị của nó rất nhanh. Lúc viết bài này, 33 trên 77 commit của meta-repo là bump con trỏ. Không có prefix thống nhất thì lịch sử chỉ là một bức tường nhiễu. Có prefix rồi thì git log --invert-grep --grep='chore(meta)' chỉ còn lại những commit thật sự đổi tài liệu hay cấu trúc.
Còn phần thành thật: mười lần bump trong số đó ghi đúng chore(meta): bump backend, không thêm chữ nào. Dòng tiêu đề thì đúng quy ước, còn phần thân chẳng nói được gì. Một lần bump nên tự mang theo changelog của nó, mà việc đó chỉ tốn một lệnh:
git -C backend log --oneline 9d04e1c..b81f2aa # dán kết quả vào phần thân commit bumpMột merge request đóng nhiều issue bằng cách nào?
Quy ước ở đây là mỗi nhóm tính năng một branch, không phải mỗi issue một branch. Login, đăng ký và logout dùng chung schema, config và phần hash mật khẩu. Tách ba branch thì chúng chặn nhau và phải làm lại phần nền chung, nên gom thành một branch với nhiều commit:
git commit -m "chore(auth): scaffold schema and config (Refs #41, Refs #42, Refs #43)"
git commit -m "feat(auth): add login endpoint (Closes #41)"
git commit -m "feat(auth): add registration endpoint (Closes #42)"
git commit -m "feat(auth): add logout endpoint (Closes #43)"Commit scaffold liên kết cả ba issue mà không đóng cái nào. Mỗi commit tính năng đóng issue của riêng nó. Khi merge request vào default branch, GitLab đóng cả ba.
Submodule thêm vào hai chỗ cần để ý.
Thứ nhất, #43 được hiểu theo project mà commit nằm trong đó. Commit bên trong backend sẽ đóng issue 43 của project backend. Nếu issue của bạn nằm ở project của meta-repo, hãy dùng tham chiếu đầy đủ kiểu group/project#43.
Thứ hai, có ba sự kiện rất dễ bị nhầm thành một: issue đóng khi merge request ở backend được merge; cả nền tảng chỉ thật sự chứa thay đổi đó sau lần bump; và cả hai đều không chứng minh thay đổi đang chạy ở đâu cả. Rule của dự án nói thẳng: commit của submodule là một snapshot mã nguồn, không phải một bản release. Bài kiểm chứng code do AI agent viết đi sâu hơn vào chuyện tách bạch các khẳng định như vậy.
Vì sao AI agent không bao giờ được commit trong repo này?
Agent làm việc trong repository này không stage, không commit, push, amend, tag, merge, rebase, cũng không đổi branch. Agent viết commit message và tên branch dưới dạng text; người chạy lệnh là con người.
Nghe thì giống cẩn thận cho có, cho tới khi bạn đếm thử một thao tác Git tưởng vô hại có thể gây ra những gì trong meta-repo.
Một agent chạy git switch bên trong backend để đọc phiên bản cũ của một service. Repo cấp trên giờ hiện + cho submodule đó. Một lúc sau, git add -A hay git commit -a ở cấp trên sẽ stage luôn cái gitlink đã dịch chuyển, cùng với những gì agent định commit. Meta-repo giờ ghim một commit có thể đang nằm trên feature branch, hoặc chẳng nằm trên remote nào.
Một agent khác đang làm việc trên cùng bản checkout. backend của nó vừa bị đổi ngay giữa chừng, và không ai báo cho nó biết.
Một agent chạy git push khi submodule.recurse đang bật. Bạn đã thấy ở trên nó dẫn tới đâu.
Nói theo kiểu lockfile, đó là một công cụ lặng lẽ viết lại lockfile của bạn trong một thay đổi mà bạn chưa hề yêu cầu. Không ai chấp nhận chuyện đó từ package manager, và gitlink cũng xứng đáng được tôn trọng như vậy.
Thay vào đó agent làm gì?
Agent chụp lại trạng thái trước và sau khi làm, rồi so sánh:
git rev-parse HEAD # commit của repo cấp trên
git diff --cached --name-only # có gì đang stage không? phải rỗng
git status --porcelain # các path đang bẩn
git submodule status # commit đã ghi và commit đang checkout của từng submodule
git -C backend status --porcelain # phần bẩn bên trong từng submodule
git -C frontend status --porcelainDự án lưu baseline này thành một file JSON: HEAD và các path bẩn của repo cấp trên, revision đã index và revision hiện tại của từng submodule, cùng các cờ tường minh nói rằng task này không được sửa submodule, không được sửa gitlink và không được stage. Sau khi xong task, mọi khác biệt mà task không giải thích được đều là một phát hiện cần xử lý, chứ không phải chi tiết vặt.
Một dòng rule trong file markdown đã đủ chưa?
Chưa. Rule trong file markdown chỉ là lời khuyên. Trong lúc viết bài này, tôi mở file permission cục bộ của agent trên máy mình ra kiểm tra và thấy nó đang cho phép git add. Chưa có chuyện gì xảy ra. Nhưng nếu có thì cũng chẳng có gì chặn lại.
Claude Code cho phép làm ranh giới này cứng hơn bằng deny rule, và deny luôn thắng allow:
{
"permissions": {
"deny": [
"Bash(git add *)",
"Bash(git commit *)",
"Bash(git push *)",
"Bash(git switch *)",
"Bash(git checkout *)",
"Bash(git rebase *)"
]
}
}Có điều rule theo pattern vẫn bị lọt: git -C backend commit đâu có bắt đầu bằng git commit. Hãy coi nó là gờ giảm tốc, không phải bức tường. Ranh giới mà agent không thể lý lẽ để vượt qua là credential: một môi trường không có quyền push. Bài một bộ luật cho mọi AI agent bàn về việc những rule như vậy nên nằm ở đâu để công cụ nào cũng đọc cùng một bản.
Quy trình này tốn gì?
- Một thay đổi, hai lần merge. Mỗi thay đổi ở backend là một merge request trong repo backend cộng một lần bump ở meta-repo.
- Không có thay đổi atomic xuyên repo. Một contract đụng cả backend lẫn frontend sẽ thành hai lần merge và một lần bump. Ở giữa, cặp phiên bản được ghi lại không khớp nhau. Trong một monorepo ít ra commit còn atomic; ở đây đến cái đó cũng không có.
- Lịch sử nhiều nhiễu. 33 trên 77 commit ở cấp trên là bump.
- Clone nào, CI job nào cũng phải đệ quy.
git clone --recurse-submodules, hoặcgit submodule update --init --recursivesau khi clone thường. Quên bước này là bạn có những thư mục rỗng, và chúng hỏng theo những kiểu rất khó hiểu. - Ai rồi cũng gặp detached HEAD một lần. Các lớp bảo vệ ở trên làm cuộc gặp đó rẻ đi, chứ không ngăn được nó.
Khi nào không nên dùng git submodule?
- Các phần luôn thay đổi cùng nhau. Gom vào một monorepo. Bạn có commit atomic và một CI graph duy nhất.
- Bạn chỉ cần chia sẻ một thư viện. Publish thành package. Version range, changelog và registry sinh ra chính là cho việc này.
- Bạn muốn lịch sử của code kia nhập hẳn vào repo mình.
git subtreecopy nó vào và không cần kiểu clone đặc biệt nào. - Team sẽ không chịu cài các lớp bảo vệ. Không có
checkkhi push và thói quen tạo branch trước khi sửa, thì lỗi ở đầu bài chỉ là chuyện sớm hay muộn.
Submodule hợp khi các repository thật sự độc lập, có CI riêng, nhịp riêng, mà bạn vẫn cần một chỗ ghi lại "các revision này đi cùng nhau" và viết tài liệu cho đúng cặp đó.
Nếu làm lại, tôi sẽ làm khác gì?
- Đưa cấu hình Git vào repo. Một script setup nhỏ set
push.recurseSubmodules=check,diff.submodule=logvàstatus.submoduleSummary=truecùng vớisubmodule.recurse=true, thay vì trông chờ vào global config của từng người. - Kiểm tra gitlink trong CI. Một job ở meta-repo fail khi commit được ghim không nằm trên main của submodule:
git -C backend merge-base --is-ancestor <pinned> origin/main. - Lần bump nào cũng kèm log. Shortlog giữa con trỏ cũ và mới nên nằm trong phần thân commit.
- Ép ranh giới với agent ngay từ ngày đầu. Deny rule và credential không có quyền push, chứ không chỉ một câu trong file rule.
- Để bot mở lần bump. Các bot cập nhật dependency như Renovate có thể cập nhật submodule, biến lần bump thành một merge request được review thay vì một việc vặt dễ bị quên.
Tóm tắt
- Submodule là một gitlink: mode
160000, đúng một commit hash..gitmodulesnói lấy ở đâu; gitlink nói lấy cái gì. branch = mainkhông có nghĩa là "đi theo main". Meta-repo luôn ghim một commit, như lockfile vậy.- Chuyển sang một branch bên trong submodule trước khi sửa. Commit trên detached HEAD chỉ cách việc bị bỏ rơi đúng một lệnh
git pull. - Commit bên trong, push, merge ở đó, rồi mới bump. Đừng bao giờ bump tới commit mà remote chưa có, và set
push.recurseSubmodules=checkđể Git từ chối giùm bạn. - Issue được đóng, con trỏ được dời và service đang chạy là ba sự thật khác nhau.
- Agent chỉ đề xuất lệnh Git dưới dạng text. Củng cố quy tắc đó bằng deny rule và credential, rồi kiểm chứng bằng snapshot trước và sau.
Ranh giới đã rõ: Git nằm trong tay người. Tiếp theo là bộ luật mà mọi agent cùng đọc, một bộ file rule và skill cho mọi công cụ.
I love this article