Hướng dẫn · 17/10/2026

Git bundle: Sao lưu và chuyển repository khi không có mạng

Khi cần mang repository sang máy không có mạng hoặc giữ một bản lịch sử mã nguồn độc lập với dịch vụ hosting, Git bundle là lựa chọn gọn: đóng gói các Git object cùng reference vào một file, rồi dùng file đó làm nguồn clone hoặc fetch.

Bài hướng dẫn đi từ tạo bundle đến phục hồi thử. Các ví dụ giả định repository đầy đủ, có branch main, không phải shallow/partial clone. Thay tên branch và đường dẫn theo dự án; các thư mục đích phải được chuẩn bị trước.

1. Xác định phần dữ liệu cần giữ

Một kế hoạch sao lưu repository nên liệt kê riêng lịch sử commit, công việc chưa commit, cấu hình máy và dữ liệu ngoài Git. Bundle phục vụ phần object/reference được chọn; nó không phải ảnh chụp toàn bộ thư mục làm việc.

git status --short
git branch --all
git tag --list
git rev-parse --is-shallow-repository

Nếu còn thay đổi chưa commit, hãy quyết định lưu riêng hay tạo commit có chọn lọc. Không chạy git add . chỉ để làm sạch trạng thái: file cấu hình bí mật có thể bị đưa vào lịch sử. Với repository shallow hoặc partial, chuẩn bị một bản có đủ lịch sử/object cần chuyển và thử phục hồi offline trước khi tin vào bản sao.

2. Tạo bundle và kiểm tra reference

git bundle create ../project-full.bundle --all
git bundle verify ../project-full.bundle
git bundle list-heads ../project-full.bundle

--all chọn toàn bộ refs trong repository hiện tại. Nó không tự cập nhật nội dung mới trên hosting. Nếu mục tiêu là sao lưu trạng thái remote, đồng bộ theo quy trình của nhóm trước khi tạo gói. Kiểm tra danh sách reference để biết những branch/tag nào thực sự được chuyển.

Lưu file bundle ngoài thư mục nguồn giúp tránh đưa chính bản sao vào commit sau. Dùng tên có thời điểm hoặc mã phiên bản khi lưu nhiều bản, thay vì liên tục ghi đè một file duy nhất.

3. Phục hồi vào thư mục mới

git clone --branch main ../project-full.bundle ../project-restore
git -C ../project-restore log -5 --oneline
git -C ../project-restore branch --all
git -C ../project-restore fsck --full

git rev-parse main
git -C ../project-restore rev-parse main

Hai mã commit của main cần trùng nếu nguồn chưa thay đổi sau lúc tạo bundle. Clone thông thường tạo branch làm việc được chọn và các remote-tracking branch; nó không biến mọi branch của nguồn thành local branch đang dùng. Tham số --branch main làm rõ nhánh cần checkout.

git fsck --full kiểm tra tính hợp lệ và liên kết object. Nó không chứng minh ứng dụng build được. Sau bước kiểm tra Git, chạy build/test với dependency và cấu hình phù hợp, rồi mở các file quan trọng. Bản phục hồi chỉ hữu ích khi nhóm thực sự dùng được nó.

4. Khi cần lưu đúng toàn bộ refs

Để lưu trữ dạng mirror, dùng một thư mục mới riêng:

git clone --mirror ../project-full.bundle ../project-archive.git
git -C ../project-archive.git show-ref
git -C ../project-archive.git fsck --full

Mirror là bare repository, không có working tree để sửa code trực tiếp. Nó phù hợp cho kho lưu refs, còn clone thông thường phù hợp để mở dự án và làm việc. Đừng dùng đích mirror này thay cho một thư mục đang chứa công việc chưa sao lưu.

5. Chuyển phần lịch sử bổ sung

Nếu máy nhận đã có mốc v1.0 cùng lịch sử cần thiết, có thể tạo gói tăng dần cho main:

git bundle create ../project-update.bundle v1.0..main

Gói này cần prerequisite nên không thay thế bản full ban đầu. Tại máy nhận, đặt bundle cạnh thư mục repository rồi chạy:

git -C ../project-restore bundle verify ../project-update.bundle
git -C ../project-restore fetch ../project-update.bundle main:refs/remotes/offline/main
git -C ../project-restore log --oneline main..refs/remotes/offline/main
git -C ../project-restore diff main...refs/remotes/offline/main

Fetch ở đây cập nhật một remote-tracking ref riêng, giúp review trước khi tích hợp. Sau khi kiểm tra working tree sạch và chọn đúng branch, có thể dùng quy trình merge của nhóm; git merge --ff-only refs/remotes/offline/main trên main sẽ từ chối nếu lịch sử đã phân kỳ. Không ép ghi đè local branch để che lỗi thiếu prerequisite hoặc phân kỳ.

6. Git LFS và submodule cần phương án riêng

Git LFS lưu pointer trong Git, còn nội dung file lớn nằm trong kho LFS. Bundle có pointer không có nghĩa máy offline đã có ảnh, video hoặc dataset thực. Hãy kiểm kê LFS, chuẩn bị chuyển object tương ứng và kiểm tra checkout khi ngắt mạng. Cách lấy/chuyển LFS phụ thuộc hệ thống lưu trữ và quyền truy cập của nhóm.

Submodule là repository riêng; superproject lưu commit được tham chiếu và thông tin cấu hình. Chuẩn bị bundle hoặc bản sao riêng cho mỗi submodule, kể cả submodule lồng nhau. Sau phục hồi, đối chiếu commit của submodule với commit mà superproject yêu cầu.

7. Quản lý bản sao như tài sản mã nguồn

Bundle có thể chứa dữ liệu nhạy cảm từng được commit trong quá khứ. Giới hạn người đọc, dùng nơi lưu phù hợp và không gửi bản full ra ngoài chỉ vì file hiện tại trông sạch. Mã băm file giúp phát hiện thay đổi khi đối chiếu qua kênh tin cậy; tự nó không xác minh danh tính người gửi.

Manifest đi kèm nên ghi thời điểm tạo, phiên bản Git, branch/commit mục tiêu, checksum, prerequisite của bản tăng dần, vị trí dữ liệu LFS/submodule và kết quả phục hồi thử. Đây là đề xuất vận hành để người khác có thể khôi phục mà không cần hỏi người tạo gói.