Vấn đềBạn vừa clone một kho lưu trữ Git mới và mọi thứ có vẻ ổn cho đến khi bạn truy cập vào một thư mục con cụ thể. Thay vì thư viện hoặc thành phần dùng chung mà bạn mong đợi, thư mục đó lại hoàn toàn trống rỗng. Khi bạn cố gắng biên dịch mã nguồn hoặc chạy script build, Git sẽ dừng quá trình với một thông báo lỗi gây khó chịu:
Submodule path 'folder_name' not initialized. Use 'git submodule update --init' to fix it.
Điều này xảy ra vì lệnh git clone tiêu chuẩn chỉ lấy các tệp của dự án chính. Git coi các submodule là những thực thể riêng biệt. Nó để lại các thư mục đó như những khung xương trống cho đến khi bạn yêu cầu nội dung một cách cụ thể.
Tại sao Git để trống các SubmoduleHãy coi submodule như một dấu trang (bookmark). Kho lưu trữ chính (superproject) thực tế không lưu trữ các tệp của submodule. Thay vào đó, nó lưu trữ một con trỏ nhỏ—một mã băm commit (commit hash) cụ thể dài 40 ký tự—để cho Git biết phiên bản nào của kho lưu trữ bên ngoài cần được sử dụng. Khi bạn clone kho lưu trữ chính, Git nhìn thấy con trỏ này nhưng sẽ đợi lệnh của bạn trước khi tải xuống hàng trăm MB dữ liệu thư viện bên ngoài.
Giải pháp 1: Khắc phục kho lưu trữ đã được cloneNếu bạn đã clone dự án và đang đối mặt với các thư mục trống, bạn có thể khắc phục trong vài giây. Hãy chạy các lệnh này từ thư mục gốc của dự án.
Bước 1: Đăng ký các SubmoduleĐầu tiên, bạn cần yêu cầu Git kiểm tra tệp .gitmodules và thiết lập cấu hình cục bộ của bạn.
git submodule init
Bước 2: Tải dữ liệuBây giờ, hãy yêu cầu Git thực sự kết nối với máy chủ từ xa và tải các tệp xuống. Lệnh này sẽ checkout mã băm commit cụ thể được ghi lại trong dự án chính của bạn.
git submodule update
Cách làm tắt chuyên nghiệpHầu hết các lập trình viên thường kết hợp chúng thành một lệnh duy nhất. Cách này nhanh hơn và xử lý được cả các submodule lồng nhau (submodule bên trong submodule) mà nếu không làm vậy sẽ vẫn bị trống.
git submodule update --init --recursive
Hãy sử dụng flag --recursive mọi lúc. Nó giúp bạn tránh khỏi việc phải khắc phục lỗi thủ công nếu cấu trúc dự án phức tạp.
Giải pháp 2: Ngăn chặn lỗi ngay khi clone lần đầuBạn có thể tránh toàn bộ rắc rối này bằng cách tải xuống mọi thứ cùng lúc. Khi clone một dự án mới, hãy thêm một flag vào lệnh của bạn:
git clone --recurse-submodules https://github.com/username/repository.git
Nếu bạn đang sử dụng phiên bản Git cũ hơn 2.13, bạn có thể cần sử dụng --recursive thay thế. Các phiên bản hiện đại (2.13 trở lên) ưu tiên dùng --recurse-submodules, nhưng cả hai thường mang lại kết quả như nhau.
Cách xác minh kết quảSau khi các lệnh chạy xong, bạn sẽ thấy các tệp xuất hiện trong thư mục. Tuy nhiên, tốt hơn hết là hãy để Git xác nhận trạng thái cho bạn.
1. Liệt kê các tệpKiểm tra kích thước thư mục hoặc liệt kê các tệp ẩn để đảm bảo tệp .git tồn tại bên trong submodule:
ls -la folder_name/
2. Kiểm tra trạng thái nội bộ của GitChạy lệnh trạng thái submodule để xem chính xác Git đánh giá các tệp cục bộ của bạn như thế nào:
git submodule status
Hãy nhìn vào ký tự tiền tố. Dấu - nghĩa là submodule vẫn chưa được khởi tạo. Dấu + nghĩa là các tệp đã có ở đó, nhưng phiên bản bạn đã checkout không khớp với những gì kho lưu trữ chính mong đợi. Một khoảng trắng (không có tiền tố) nghĩa là mọi thứ đã hoàn hảo.
Khắc phục các lỗi thường gặp### Thiếu tệp .gitmodulesNếu lệnh git submodule init không có phản hồi, hãy kiểm tra thư mục gốc của dự án để tìm tệp .gitmodules. Tệp văn bản này đóng vai trò như một bản đồ. Nếu nó bị thiếu, Git sẽ không biết submodule nằm ở đâu. Một tệp chuẩn sẽ trông như thế này:
[submodule "folder_name"]
path = folder_name
url = https://github.com/example/library.git
Lỗi xác thựcCập nhật submodule thường thất bại nếu submodule đó là một kho lưu trữ riêng tư (private). Nếu kho lưu trữ chính sử dụng HTTPS nhưng submodule sử dụng SSH, Git có thể yêu cầu các khóa (keys) mà bạn chưa thiết lập. Hãy đảm bảo bạn có quyền truy cập độc lập vào URL của submodule trước khi chạy lệnh cập nhật.
Trạng thái Detached HEADSau khi chạy git submodule update, submodule của bạn sẽ ở trạng thái 'Detached HEAD'. Đừng lo lắng; điều này là bình thường. Git đang trỏ đến một commit cụ thể, không phải một tên nhánh. Nếu bạn cần viết code bên trong submodule đó, hãy chuyển sang một nhánh trước bằng cách chạy git checkout main bên trong thư mục cụ thể đó.
Bắt buộc làm mới hoàn toànĐôi khi việc cập nhật submodule thất bại vì bạn vô tình thay đổi một tệp bên trong thư mục đó. Nếu bạn chỉ muốn xóa bỏ những thay đổi đó và lấy về các tệp chính xác, hãy thêm flag force:
git submodule update --init --recursive --force