Bài toán chia sẻ code giữa nhiều dự án
Làm việc từ 2 dự án trở lên, bạn sẽ sớm gặp tình huống này: một module xác thực (auth) hay bộ thư viện UI dùng chung cần xuất hiện ở cả web app lẫn CMS quản trị. Phản xạ đầu tiên của nhiều lập trình viên là copy-paste nguyên thư mục code từ dự án A sang dự án B.
Cách này giải quyết xong việc trong 5 phút. Nhưng rắc rối sẽ ập đến ngay sau đó.
Thử tưởng tượng thư viện auth phát sinh một lỗi bảo mật nghiêm trọng. Bạn sửa lỗi ở repo chính, rồi phải mở tiếp 3 repo khác để copy đè file bằng tay và commit lại từng nơi.
Quên một chỗ là xong: các dự án chạy các bản code lệch nhau, sinh lỗi ngầm cực kỳ khó debug. Đóng gói thành package đẩy lên private npm hay pip registry là lựa chọn chuẩn chỉnh, nhưng nếu thư viện đang trong giai đoạn phát triển nóng và sửa đổi hàng chục commit mỗi ngày, việc bump version liên tục sẽ ngốn của bạn cả tiếng đồng hồ chờ build và deploy.
Git Submodule sinh ra để xử lý đúng điểm nghẽn này: nhúng trực tiếp một Git repository vào bên trong một Git repository khác mà vẫn giữ trọn lịch sử commit riêng biệt của cả hai.
Bản chất: Git Submodule thực sự hoạt động ra sao?
Nhiều anh em thường nghĩ Git Submodule sẽ tải toàn bộ commit của repo con rồi gộp chung vào repo cha. Thực tế không phải vậy.
Về bản chất, Git Submodule chỉ hoạt động như một con trỏ (pointer). Repo cha không hề lưu từng file hay từng dòng code của repo con. Thay vào đó, nó chỉ ghi lại đúng hai mẩu dữ liệu:
- Đường dẫn URL của repo con (được khai báo trong file
.gitmodules). - Mã commit hash cụ thể (SHA-1 hoặc SHA-256) mà thư mục con đang dừng lại tại thời điểm bạn commit ở repo cha.
Tệp .gitmodules nằm ngay thư mục gốc của repo cha, có nội dung trực quan như sau:
[submodule "libs/shared-auth"]
path = libs/shared-auth
url = [email protected]:my-company/shared-auth.git
Nhờ cơ chế con trỏ này, hai repo có vòng đời phát triển hoàn toàn tách biệt. Bạn thoải mái commit, tạo nhánh trên repo con mà không làm rác commit history của dự án chính. Repo cha chỉ trỏ sang commit mới khi team đã kiểm thử tương thích xong xuôi.
Thực hành: Thêm, clone và đồng bộ Git Submodule
1. Nhúng repo con vào dự án chính
Đứng tại thư mục gốc của dự án chính, bạn chạy lệnh sau để nhúng repo shared-auth vào thư mục libs/shared-auth:
git submodule add [email protected]:my-company/shared-auth.git libs/shared-auth
Git sẽ tự động clone mã nguồn repo con về đúng thư mục chỉ định, đồng thời tạo ra file .gitmodules. Gõ git status, bạn sẽ thấy xuất hiện file cấu hình mới và một entry thư mục con với chế độ đặc biệt (gitlink mode 160000). Bây giờ, hãy lưu thay đổi này vào repo cha:
git commit -am "feat: tich hop submodule shared-auth"
git push origin main
2. Clone dự án chứa submodule không bị rỗng thư mục
Cứ 10 người mới tiếp cận submodule thì có tới 9 người dính quả này: clone repo cha về bằng lệnh git clone quen thuộc, mở thư mục submodule ra thì thấy trống trơn.
Lý do rất đơn giản: Git mặc định không tự tải nội dung repo phụ thuộc để tiết kiệm băng thông. Để kéo đầy đủ cả dự án cha lẫn các repo con ngay từ đầu, bạn chỉ cần thêm cờ --recurse-submodules:
git clone --recurse-submodules [email protected]:my-company/main-project.git
Nếu lỡ tay clone theo cách thông thường từ trước, bạn đừng xóa đi làm lại. Hãy chạy lệnh sau để kéo code về bù:
git submodule update --init --recursive
3. Cập nhật submodule lên bản mới nhất
Khi đồng đội vừa push một bản vá lên repo con, dự án cha của bạn sẽ không tự cập nhật theo. Để kéo commit mới nhất trên remote tracking branch về máy, bạn dùng lệnh:
git submodule update --remote --merge
Chạy git diff tại repo cha, bạn sẽ thấy con trỏ commit của submodule đã thay đổi. Bước cuối cùng là commit lại hash mới này lên repo cha để toàn bộ team cùng nhận được bản cập nhật:
git add libs/shared-auth
git commit -m "chore: update shared-auth submodule to latest commit"
git push origin main
4. Gỡ lỗi thực tế: Thoát bẫy Detached HEAD
Trạng thái HEAD detached at <commit-hash> là cơn đau đầu kinh điển nhất khi làm việc với submodule. Nó xảy ra vì lệnh git submodule update trỏ trực tiếp HEAD vào một commit hash cụ thể, chứ không checkout vào tên branch nào cả.
Nếu tiện tay sửa code và commit luôn lúc này, commit đó sẽ mồ côi (không gắn với branch nào). Khi người khác chạy lệnh update, commit của bạn rất dễ bị lạc trôi và mất dấu trong Git reflog.
Tại dự án thực tế với team 6 lập trình viên backend, chúng tôi quy ước rõ: tuyệt đối không commit thẳng khi đang detached HEAD. Nếu cần sửa gấp một lỗi logic ngay trong repo con, hãy đi từng bước sau:
# 1. Chuyen vao thu muc con
cd libs/shared-auth
# 2. Checkout sang branch lam viec cu the
git checkout main
git pull origin main
# 3. Sua code, commit va push len remote cua repo con TRUOC
git commit -am "fix: sua loi xac thuc token JWT"
git push origin main
# 4. Quay lai thu muc goc cua repo cha de luu commit hash moi
cd ../..
git add libs/shared-auth
git commit -m "fix: cap nhat submodule shared-auth voi ban va JWT"
git push origin main
Đẩy code lên remote của repo con trước rồi mới update hash ở repo cha là nguyên tắc sống còn. Quy tắc này đảm bảo đồng đội khi pull repo cha về sẽ luôn tìm thấy commit tương ứng trên remote, tránh hoàn toàn lỗi fatal: reference is not a tree gây gián đoạn pipeline CI/CD.
Tóm lại
Git Submodule đòi hỏi bạn phải nhớ thêm vài cờ lệnh khi clone và update. Bù lại, đây là giải pháp sạch sẽ nhất để chia sẻ code nội bộ mà không cần dựng hệ thống private package phức tạp. Chỉ cần nắm vững nguyên lý con trỏ commit, luôn clone kèm --recurse-submodules và nhớ checkout branch trước khi sửa code, bạn sẽ kiểm soát cấu trúc đa repo trơn tru mà không lo mất mát dữ liệu.
