Git sparse-checkout: Làm việc gọn hơn trong monorepo

Một monorepo có hàng chục ứng dụng nhưng công việc hôm nay chỉ cần một service và thư viện dùng chung. Git sparse-checkout giúp giới hạn các file tracked xuất hiện trong working tree, giảm phần mã phải mở và lập chỉ mục trong IDE mà vẫn làm việc trên cùng repository.

1. Ba khái niệm giải quyết ba vấn đề

Sparse checkout tự nó không bảo đảm giảm lượng tải ban đầu hoặc dung lượng object trong .git. Nó cũng không phải phân quyền: file không hiện trong working tree không có nghĩa người dùng bị cấm đọc nội dung đó. Chọn cơ chế theo mục tiêu dung lượng, mạng hay tốc độ thao tác.

2. Chọn thư mục trên repository hiện có

Ví dụ repository có services/billing, services/catalog, packages/shared và docs. Chạy tại thư mục gốc, sau khi đã lưu công việc và kiểm tra trạng thái sạch:

git --version
git status --short
git sparse-checkout set --cone services/billing packages/shared
git sparse-checkout list
git status --short

Cone mode nhận tên thư mục. Ngoài toàn bộ nội dung trong các thư mục được chọn, nó còn giữ các file trực tiếp ở thư mục gốc và các thư mục tổ tiên liên quan. Vì vậy README hoặc file cấu hình ở gốc vẫn hiện là hành vi bình thường.

Việc các file ngoài phạm vi biến mất khỏi working tree không phải một commit xóa chúng. Đừng tạo thao tác xóa thủ công để làm cây thư mục “đúng hình” nếu Git báo không thể thu gọn vì file đang sửa hoặc conflict.

3. Bắt đầu từ clone mới

Thay URL minh họa bằng repository được phép truy cập và chọn thư mục đích chưa tồn tại:

git clone --sparse https://example.com/team/monorepo.git monorepo-focus
cd monorepo-focus
git sparse-checkout set --cone services/billing packages/shared

--sparse bắt đầu với các file ở cấp gốc. Nếu server hỗ trợ partial clone và cần giảm tải blob ban đầu, có thể kết hợp ngay từ lệnh clone:

git clone --filter=blob:none --sparse https://example.com/team/monorepo.git monorepo-partial

Git có thể cần mạng khi thao tác chạm đến object chưa tải. Một lần clone nhanh không chứng minh mọi công việc sau đó đều chạy offline. Kiểm tra hỗ trợ của server, thông báo khi clone và thử các thao tác thực tế của nhóm trước khi áp dụng rộng.

4. Mở rộng hoặc thay phạm vi

git sparse-checkout add docs
git sparse-checkout list

git sparse-checkout set --cone services/catalog packages/shared docs

add bổ sung vào phạm vi đang có; set thay danh sách lựa chọn. Trong ví dụ cuối, billing không còn nằm trong danh sách. Kiểm tra status trước khi đổi phạm vi, rồi build/test phần ứng dụng mới để phát hiện dependency chưa được checkout.

5. Chọn đủ dependency cho công việc

Chỉ lấy thư mục service thường chưa đủ. Build có thể cần script chung, cấu hình test, schema, mã sinh hoặc package nội bộ khác. Đọc manifest và lỗi build trước khi mở rộng phạm vi; nếu workspace của package manager yêu cầu nhiều project cùng hiện diện, cấu hình sparse phải tôn trọng yêu cầu đó.

Một cách làm thực dụng là ghi danh sách thư mục cần cho từng công việc vào tài liệu onboarding. Đo thời gian IDE sẵn sàng, thời gian status và thời gian build trước/sau; không suy ra lợi ích chỉ từ số thư mục biến mất.

6. Sau merge hoặc rebase

Git có thể đưa file ngoài phạm vi ra working tree để xử lý conflict. Hoàn thành giải quyết conflict và lưu các thay đổi cần giữ, sau đó áp dụng lại quy tắc:

git status --short
git sparse-checkout reapply
git status --short

Nếu vẫn có file ngoài phạm vi, đọc thông báo và kiểm tra file có được sửa hoặc chưa được track không. Không dùng lệnh dọn file hàng loạt chỉ để đạt trạng thái sparse; nội dung local có thể là công việc cần giữ.

7. Sparse index là tùy chọn riêng

git sparse-checkout reapply --sparse-index

Sparse index có thể giảm kích thước index và tăng tốc một số thao tác, nhưng cần thử với IDE, plugin và phiên bản Git của nhóm. Khi gặp vấn đề tương thích, có thể giữ sparse checkout và trở về index đầy đủ:

git sparse-checkout reapply --no-sparse-index

Tài liệu Git vẫn đánh dấu sparse checkout và một số hành vi liên quan là experimental. Dùng phiên bản Git đã được nhóm kiểm thử và đọc tài liệu tương ứng khi nâng cấp.

8. Khôi phục working tree đầy đủ

git status --short
git sparse-checkout disable
git status --short

Lệnh disable đưa các file tracked của checkout hiện tại trở lại. Với partial clone, quá trình có thể cần tải thêm object và tốn dung lượng. Nó không mở rộng lịch sử shallow hoặc tự khởi tạo mọi submodule; những phần đó có quy trình riêng.

Trước khi bàn giao quy trình cho nhóm, hãy thử một vòng: chọn service, build/test, thêm dependency, chuyển nhánh, xử lý tình huống file ngoài phạm vi và disable. Một cấu hình sparse hữu ích phải giảm chi phí thao tác mà vẫn giữ công việc hằng ngày dễ hiểu và có thể quay lại trạng thái đầy đủ.

Tài liệu tham khảo

git sparse-checkout, git clone và Partial clone design.