Git archive: Đóng gói mã nguồn đúng phiên bản

Khi cần bàn giao mã nguồn của một phiên bản, nén cả thư mục đang làm việc dễ mang theo file tạm, cấu hình cá nhân hoặc những thay đổi chưa duyệt. Git archive giúp xuất cây mã nguồn đã chọn thành gói riêng. Tuy nhiên, một file ZIP tạo thành công chưa có nghĩa là bộ cài đặt hoàn chỉnh hoặc bản sao lưu repository.

1. Xác định thứ cần bàn giao

Hãy phân biệt ba sản phẩm: snapshot mã nguồn để đọc hoặc build, artifact đã build để triển khai, và bản sao lưu lịch sử để phục hồi. Bài này tập trung vào sản phẩm đầu tiên. Người nhận vẫn có thể cần runtime, dependency, cấu hình và dữ liệu để chạy ứng dụng.

Trước khi thao tác, thống nhất phiên bản, người nhận và phạm vi file. Với hợp đồng bàn giao, nên có một danh sách kiểm tra riêng: tài liệu khởi động, giấy phép, lockfile, mã nguồn và hướng dẫn cấu hình mẫu. Không dùng việc “đã gửi ZIP” thay cho kiểm tra người nhận có thể sử dụng gói đó.

2. Kiểm tra phiên bản trước khi xuất

Chạy tại thư mục gốc repository. Ví dụ giả định tag v1.4.0 đã tồn tại; thay bằng tag đã được nhóm xác nhận, không tự tạo tag chỉ để lệnh chạy qua.

git status --short
git rev-parse --verify "v1.4.0^{commit}"
git show --no-patch --format=fuller v1.4.0

Ghi lại mã commit đầy đủ trả về. Dùng mã đó trong hồ sơ bàn giao để tránh chỉ dựa vào tên tag có thể bị di chuyển. Nếu quy trình yêu cầu xác minh chữ ký release, hoàn tất bước đó theo chính sách của nhóm trước khi đóng gói.

3. Tạo ZIP với thư mục bao ngoài

git archive --format=zip --prefix=app-v1.4.0/ --output=../app-v1.4.0-source.zip v1.4.0

Theo tài liệu git archive, lệnh tạo archive từ tree được chỉ định; --prefix thêm tiền tố đường dẫn và --output chọn file đích. Ví dụ này lấy nội dung phiên bản đã commit, không lấy các sửa đổi chưa commit trong working tree. Chọn tên đầu ra chưa tồn tại để tránh ghi đè gói cũ.

Thư mục bao ngoài giúp người nhận giải nén mà không làm lẫn file vào thư mục hiện tại. Dùng tên đơn giản, không có đường dẫn tuyệt đối hoặc thành phần .. trong prefix. Đặt đầu ra bên ngoài repository giúp khu vực mã nguồn dễ kiểm tra hơn.

4. Loại file bằng export-ignore

Nếu nhóm quyết định không gửi cấu hình CI và ghi chú nội bộ, có thể thêm vào .gitattributes:

/.github export-ignore
/internal-notes export-ignore

export-ignore loại các đường dẫn được đánh dấu khỏi archive. Mặc định, thuộc tính được đọc từ cây đang xuất; chỉnh file local sau khi tạo tag không tự thay đổi quy tắc của tag đó. Vì vậy, review và commit quy tắc trước khi chốt phiên bản. --worktree-attributes là lựa chọn có chủ đích cho quy tắc local, không nên âm thầm thêm vào quy trình bàn giao.

Không loại tests hoặc tài liệu chỉ để gói nhỏ hơn nếu người nhận cần chúng để xác minh sản phẩm. Đưa danh sách loại trừ vào review như một thay đổi của quy trình phát hành.

5. Ghi dấu nguồn gốc trong gói

Một file VERSION.txt được commit có thể chứa:

commit=$Format:%H$

Đánh dấu trong .gitattributes:

/VERSION.txt export-subst

Khi xuất từ commit hoặc tag có thể xác định commit, Git thay placeholder bằng thông tin tương ứng. Đây là dấu vết tiện tra cứu, không phải chữ ký bảo đảm gói không bị sửa. Sau khi tạo gói, vẫn cần lưu checksum tại kênh bàn giao đáng tin cậy.

6. Kiểm tra gói như người nhận

1. Liệt kê nội dung ZIP bằng công cụ giải nén, kiểm tra đúng thư mục bao ngoài và file bắt buộc.
2. Giải nén vào thư mục kiểm thử mới, không đè lên checkout đang làm việc.
3. Đọc VERSION.txt, đối chiếu mã commit với hồ sơ đã ghi.
4. Chạy quy trình cài đặt và kiểm thử trong môi trường cô lập, không dùng credential production.
5. Kiểm tra riêng dự án dùng submodule hoặc Git LFS; không giả định ZIP đã có đầy đủ nội dung phụ thuộc hoặc binary thật.
6. Rà soát secret và tài liệu nội bộ trong chính gói cuối, sau mọi bước bổ sung file.

Trên PowerShell, có thể tính checksum sau khi kiểm tra:

Get-FileHash -Algorithm SHA256 ../app-v1.4.0-source.zip

Gửi kèm tên gói, commit, checksum, yêu cầu runtime và kết quả kiểm thử. Nếu bổ sung file hoặc tạo lại ZIP, tính lại checksum; đừng tiếp tục dùng mã của gói trước.

7. Những giới hạn cần nhớ

Archive không thay thế backup lịch sử Git. Quy tắc loại trừ cũng không xử lý một secret đã từng bị công khai: khi phát hiện lộ khóa, cần thu hồi hoặc luân chuyển khóa theo quy trình ứng phó. Với triển khai production, nên dùng pipeline tạo artifact, kiểm thử và phê duyệt riêng thay vì mặc định mọi ZIP nguồn đều sẵn sàng chạy.

Một lần bàn giao tốt kết thúc khi người nhận xác định được nguồn gốc và kiểm tra được gói, chứ không chỉ khi lệnh nén trả về thành công.

Tài liệu tham khảo

Git archive và Git attributes.