Vấn đề: Git Push bị từ chối do kích thước file quá lớn
Bạn đang cố gắng đẩy những thay đổi mới nhất của mình lên GitHub, có thể đã muộn rồi, và đột nhiên Git báo lỗi từ chối. Bạn sẽ thấy thông báo tương tự như sau:
remote: error: File path/to/file.bin is 150.00 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.
to github.com/your-org/your-repo.git
! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to 'github.com/your-org/your-repo.git'
Thông báo này cho bạn biết chính xác vấn đề là gì: bạn có một file trong repository của mình lớn hơn giới hạn kích thước file cá nhân của GitHub, là 100MB.
Tại sao điều này xảy ra
GitHub có giới hạn cứng là 100MB cho các file riêng lẻ trong một Git repository. Mặc dù tổng kích thước repository có thể lên tới 5GB (hoặc hơn đối với các gói trả phí), nhưng không một file nào được vượt quá 100MB. Điều này không chỉ áp dụng cho các file hiện có trong working directory của bạn; mà còn cho bất kỳ file nào đã từng được commit vào lịch sử của repository.
Git theo dõi mọi phiên bản của mọi file. Nếu bạn commit một file lớn (như video, file nén lớn, bản sao lưu cơ sở dữ liệu hoặc file nhị phân đã biên dịch), ngay cả khi bạn xóa nó sau đó bằng git rm, sự hiện diện của nó vẫn còn trong lịch sử của repository. Khi bạn push, pre-receive hooks của GitHub sẽ quét toàn bộ lịch sử của các commit đến. Nếu nó tìm thấy một blob (nội dung của một file) lớn hơn 100MB ở bất kỳ đâu trong lịch sử đó, nó sẽ từ chối push.
Phân tích: Xác định thủ phạm
Thông báo lỗi thường chỉ thẳng đến file gây ra vấn đề (ví dụ: path/to/file.bin). Nếu bạn cần tìm các file lớn khác hoặc điều tra thêm, bạn có thể sử dụng các công cụ như git rev-list và git ls-tree, nhưng cách đơn giản nhất, đặc biệt khi chuẩn bị cho việc sửa lỗi, là để một công cụ như git filter-repo phân tích lịch sử của bạn.
Giải pháp tức thì: Viết lại lịch sử với git filter-repo
Để khắc phục điều này, bạn cần xóa (các) file lớn khỏi lịch sử của repository. Điều này có nghĩa là viết lại lịch sử, một thao tác rất mạnh mẽ. Điều quan trọng là phải hiểu rõ các tác động của nó, đặc biệt nếu bạn đang làm việc trong một shared repository.
CẢNH BÁO: Viết lại lịch sử là một thao tác phá hủy. Nó thay đổi các SHA của commit. Nếu những người khác đã clone repository của bạn, họ sẽ cần re-clone hoặc thực hiện các lệnh Git cụ thể để đồng bộ hóa với lịch sử mới. Chỉ tiếp tục nếu bạn hiểu điều này hoặc đang làm việc trên một fresh clone / personal branch.
Bước 1: Cài đặt git filter-repo
git filter-repo là công cụ được khuyến nghị để viết lại lịch sử Git, thay thế git filter-branch cũ hơn, chậm hơn và phức tạp hơn. Nó là một script Python.
Trên macOS (với Homebrew):
brew install git-filter-repo
Trên Linux (với pip):
pip3 install git-filter-repo
Hoặc cài đặt từ mã nguồn nếu bạn muốn: https://github.com/newren/git-filter-repo
Bước 2: Tạo một fresh clone (Bước an toàn quan trọng)
Trước khi bạn can thiệp vào lịch sử, hãy luôn làm việc trên một fresh clone. Bằng cách này, nếu có gì đó không ổn, bạn sẽ không làm hỏng bản sao làm việc chính của mình.
cd ..
git clone git@github.com:your-org/your-repo.git your-repo-cleaned
cd your-repo-cleaned
Bước 3: Chạy git filter-repo để loại bỏ các blob lớn
Lệnh này sẽ viết lại lịch sử của repository, loại bỏ bất kỳ file nào lớn hơn 100MB. Nó đủ thông minh để xóa chúng khỏi tất cả các commit mà chúng đã từng tồn tại.
git filter-repo --strip-blobs-bigger-than 100M
git filter-repo sẽ chạy và hiển thị tiến trình. Có thể mất một thời gian đối với các repository lớn. Sau khi hoàn tất, lịch sử của local repository của bạn được viết lại và (các) file lớn đã biến mất.
Bước 4: Force Push lên GitHub
Vì bạn đã viết lại lịch sử, một git push thông thường sẽ bị từ chối vì lịch sử local của bạn khác với remote. Bạn cần force push.
Sử dụng --force-with-lease để đảm bảo an toàn, đặc biệt trong các shared repository, vì nó ngăn chặn việc ghi đè các thay đổi trên remote nếu người khác đã push trong thời gian đó.
git push --force-with-lease origin <your-branch-name>
Thay thế <your-branch-name> bằng tên branch bạn đang push (ví dụ: main hoặc master).
Bước 5: Thông báo cho đội của bạn (Bắt buộc đối với Shared Repositories)
Nếu đây là một shared repository, bạn PHẢI thông báo cho đội của mình ngay lập tức. Mọi người khác sẽ cần rebase công việc của họ hoặc re-clone repository để đồng bộ hóa với lịch sử mới. Cách dễ nhất cho họ thường là xóa bản sao local của họ và re-clone.
Ngăn chặn các vấn đề trong tương lai: Quản lý các file lớn bằng Git LFS
Sau khi bạn đã dọn dẹp lịch sử của mình, bạn vẫn cần một chiến lược để xử lý các file lớn một cách đúng đắn. Đây là lúc Git Large File Storage (Git LFS) phát huy tác dụng.
Git LFS thay thế các file lớn trong Git repository của bạn bằng các text pointer nhỏ. Nội dung file thực tế được lưu trữ trên một LFS server từ xa (như LFS server của GitHub). Khi bạn clone hoặc checkout một branch, Git LFS sẽ tải xuống các file lớn thực tế. Điều này giữ cho Git repository của bạn nhẹ và tránh giới hạn 100MB.
Bước 1: Cài đặt Git LFS
Đầu tiên, hãy đảm bảo Git LFS đã được cài đặt trên hệ thống của bạn.
Trên macOS (với Homebrew):
brew install git-lfs
Trên Linux (Debian/Ubuntu):
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs
Trên Windows, bạn có thể tải trình cài đặt từ git-lfs.github.com hoặc sử dụng Chocolatey:
choco install git-lfs
Bước 2: Thiết lập LFS cho Repository của bạn
Điều hướng đến repository của bạn (bản gốc, đã được làm sạch, hoặc bản your-repo-cleaned nếu bạn muốn tiếp tục làm việc ở đó) và khởi tạo Git LFS:
git lfs install
Lệnh này thiết lập Git LFS hooks trong local repository của bạn.
Bước 3: Theo dõi các loại file
Cho Git LFS biết những loại file nào cần theo dõi. Sử dụng wildcards cho các phần mở rộng file lớn phổ biến. Điều này thêm các mục vào file .gitattributes của bạn.
git lfs track "*.bin"
git lfs track "*.zip"
git lfs track "*.mp4"
git lfs track "*.psd"
Sau khi theo dõi, bạn cần commit file .gitattributes:
git add .gitattributes
git commit -m "Configure Git LFS to track large files"
Bước 4: Thêm và commit các file lớn như bình thường
Bây giờ, bất kỳ file mới nào (hoặc các file hiện có chưa được commit) khớp với các pattern đã theo dõi sẽ được LFS xử lý. Thêm chúng và commit bình thường:
git add path/to/another_large_file.bin
git commit -m "Add another large binary file via LFS"
git push origin <your-branch-name>
Bạn sẽ thấy output của Git LFS trong quá trình push, cho biết nó đang tải các file lớn lên LFS server.
Các bước xác minh
Sau khi thực hiện sửa lỗi và thiết lập LFS:
- Xác nhận Push thành công: Lệnh
git pushcủa bạn giờ đây sẽ hoàn tất mà không gặp lỗi remote rejection. - Kiểm tra kích thước GitHub Repository: Vào cài đặt repository của bạn trên GitHub. Kích thước được báo cáo có thể mất một chút thời gian để cập nhật, nhưng cuối cùng nó sẽ phản ánh việc loại bỏ các file lớn khỏi lịch sử.
- Xác minh LFS Tracking: Nếu bạn đã thiết lập Git LFS, hãy kiểm tra một file đáng lẽ phải được theo dõi. Trong local repository của bạn, nếu bạn mở một file lớn được LFS-tracked, bạn sẽ thấy một text pointer nhỏ thay vì nội dung file thực tế. Nội dung thực tế sẽ được tải xuống khi Git LFS hoạt động.
Với các bước này, repository của bạn đã sạch, push của bạn không còn bị chặn, và bạn có một chiến lược vững chắc để quản lý các file lớn trong tương lai.