Hướng dẫn chi tiết: Làm chủ Git Submodules một cách đơn giản và hiệu quả

Bài viết được dịch và tổng hợp từ tin tức gốc. Bạn có thể đọc bài viết gốc bằng tiếng Anh tại đây.

Điểm tin nhanh:

Git Submodules thực chất là việc nhúng một repository khác vào dự án của bạn tại một đường dẫn cụ thể, được ghim vào một commit hash cố định.

Sử dụng lệnh git config --global submodule.recurse true để tự động hóa việc đồng bộ submodules trong các thao tác hàng ngày.

Các lỗi phổ biến như "thư mục trống" hoặc "CI thất bại" thường do thiếu tham số --recurse-submodules hoặc cấu hình sai trong pipeline.

Thumbnail

Git submodules thường mang tiếng là khó sử dụng, nhưng thực tế, hầu hết các rắc rối đều xuất phát từ việc thiếu một vài lệnh quan trọng hoặc một flag cấu hình mà ít người để ý. Khi được sử dụng đúng cách, chúng là giải pháp sạch sẽ để nhúng thư viện dùng chung, hệ thống thiết kế (design system) hoặc tài liệu vào dự án của bạn.

Hiểu đúng về Git Submodule

Trước khi đi vào lệnh, hãy nắm vững tư duy này: Một submodule nhúng một git repo khác vào bên trong repo của bạn tại một đường dẫn cố định, được ghim vào một commit cụ thể.

Repo chính của bạn không theo dõi các file của submodule, nó chỉ theo dõi xem submodule đang ở commit nào. Tư duy này giải thích cho hầu hết các hành vi của Git sau này.

Các thao tác cơ bản với Submodule

1. Thêm Submodule

Sử dụng lệnh sau để thêm một submodule vào dự án:

git submodule add [email protected]:org/shared-lib.git vendor/shared-lib

Lệnh này sẽ clone repo vào vendor/shared-lib, tạo file .gitmodules và stage commit hiện tại. Bạn cần commit cả file .gitmodules và thư mục submodule.

2. Clone dự án chứa Submodule

Nỗi đau lớn nhất là khi đồng nghiệp clone dự án về và thấy thư mục submodule trống rỗng. Để khắc phục, hãy sử dụng:

# Clone toàn bộ dự án bao gồm cả submodule
git clone --recurse-submodules <url-repo>

# Nếu đã clone rồi, hãy khởi tạo sau
git submodule update --init --recursive

Mẹo chuyên nghiệp: Chạy lệnh sau một lần trên máy tính của bạn để Git tự động đồng bộ submodule mỗi khi bạn pull hoặc checkout:

git config --global submodule.recurse true

Bảng so sánh các tình huống xử lý lỗi

Tình huống	Nguyên nhân	Giải pháp
Thư mục submodule trống	Thiếu flag `--recurse-submodules`	Chạy `git submodule update --init --recursive`
CI/CD thất bại	Pipeline không fetch submodule	Thêm `submodules: recursive` vào cấu hình checkout
Lỗi "Detached HEAD"	Chưa checkout branch trong submodule	Chuyển sang branch mong muốn trong thư mục submodule
Submodule không cập nhật	Chưa push commit submodule	Push submodule trước khi commit ở repo cha

Tích hợp vào CI/CD

Các hệ thống CI (như GitHub Actions) mặc định không fetch submodule. Đối với GitHub Actions, hãy thêm cấu hình sau:

- uses: actions/checkout@v4
  with:
    submodules: recursive

Cập nhật và Thay đổi Submodule

Cập nhật lên commit mới nhất

Để lấy thay đổi mới nhất từ branch được theo dõi:

git submodule update --remote vendor/shared-lib
git add vendor/shared-lib
git commit -m "chore: bump shared-lib submodule"

Làm việc bên trong Submodule

Vì submodule là một git repo độc lập, bạn có thể chỉnh sửa trực tiếp. Hãy nhớ checkout một branch trước khi sửa:

cd vendor/shared-lib
git checkout main
# thực hiện sửa đổi, commit và push
cd -
git add vendor/shared-lib && git commit -m "chore: bump submodule"

Loại bỏ Submodule

Khi không còn cần thiết, hãy dọn dẹp sạch sẽ bằng 4 bước:

git submodule deinit -f vendor/shared-lib
git rm -f vendor/shared-lib
rm -rf .git/modules/vendor/shared-lib
git commit -m "chore: remove shared-lib submodule"

Kết luận

Git submodules không hề đáng sợ nếu bạn hiểu cơ chế ghim commit của chúng. Hãy thiết lập submodule.recurse true và luôn kiểm tra cấu hình CI của bạn. Chúc bạn code vui vẻ!