Git ls-files: Kiểm kê file được theo dõi, chưa theo dõi và bị bỏ qua

File có trên máy nhưng đồng nghiệp clone dự án lại không thấy; hoặc một file cấu hình đã thêm vào .gitignore vẫn xuất hiện trong repository. Trước khi sửa quy tắc hay thêm toàn bộ file vào Git, hãy kiểm kê đúng nhóm dữ liệu. Git ls-files giúp trả lời câu hỏi về index và file chưa được theo dõi mà không cần thay đổi nội dung.

1. File trên ổ đĩa không đồng nghĩa với file trong Git

Hãy phân biệt ba nhóm: đường dẫn có trong index, file chưa được theo dõi không bị ignore và file chưa được theo dõi bị ignore. Index là vùng chuẩn bị cho commit; có tên trong index chưa chứng minh file đã được commit hoặc push lên remote.

Các ví dụ dưới đây chạy từ thư mục gốc của repository thông thường, không đang giải quyết merge conflict. Với submodule hoặc sparse checkout, cần kiểm tra thêm cơ chế riêng thay vì coi danh sách này là toàn bộ cây thư mục trên máy.

2. Liệt kê đường dẫn trong index

git ls-files --cached
git ls-files --cached -- src/

Theo tài liệu git ls-files, --cached liệt kê các file trong index. Đường dẫn sau dấu -- giới hạn phạm vi; thay src/ bằng thư mục cần kiểm tra.

Một file vừa được stage có thể đã xuất hiện ở đây nhưng chưa có trong lịch sử commit. Ngược lại, file bị xóa khỏi ổ đĩa nhưng chưa stage việc xóa vẫn có thể còn trong index. Vì vậy, không dùng danh sách này để kết luận mọi đường dẫn đều tồn tại vật lý hoặc đã được đồng bộ.

3. Liệt kê file mới chưa bị ignore

git ls-files --others --exclude-standard
git ls-files --others --exclude-standard -- docs/

--others chọn file chưa được theo dõi; --exclude-standard áp dụng các quy tắc loại trừ chuẩn của Git. Đây là nhóm nên xem xét khi tìm tài liệu mới hoặc mã nguồn chưa được đưa vào quy trình commit.

Ví dụ giả định danh sách trả về docs/setup-notes.md và src/NewParser.php. Đừng tự động thêm cả hai: đọc nội dung, xác định phạm vi công việc và kiểm tra thông tin nhạy cảm trước. Một file mới có thể thuộc công việc đang làm dở của người khác.

4. Xem riêng file chưa được theo dõi nhưng bị ignore

git ls-files --others --ignored --exclude-standard

Lệnh này hữu ích để kiểm tra dữ liệu không xuất hiện trong danh sách file mới thông thường. Nó chỉ liệt kê tên, không đọc nội dung. Trong dự án lớn, hãy thêm đường dẫn cụ thể để tránh đầu ra quá dài từ thư mục dependency hoặc build.

Ignored không có nghĩa là không quan trọng. File chứa thiết lập máy cá nhân, bản sao dữ liệu thử nghiệm hoặc tài liệu nội bộ có thể cần sao lưu nhưng không nên commit. Đừng biến danh sách kiểm kê thành danh sách xóa.

5. Tìm file đã theo dõi nhưng khớp quy tắc ignore

git ls-files --cached --ignored --exclude-standard

Kết quả giúp phát hiện tình huống đã thêm quy tắc ignore sau khi file được theo dõi. Quy tắc ignore không tự xóa file khỏi index hay lịch sử. Nếu thấy file nhạy cảm, cần đánh giá phạm vi lộ và xử lý thông tin xác thực theo quy trình riêng; sửa ignore không thu hồi được bí mật đã phát tán.

Không tự động bỏ theo dõi toàn bộ kết quả. Một số file được commit có chủ đích dù trùng quy tắc chung. Trao đổi với người phụ trách và review từng đường dẫn trước khi quyết định thay đổi.

6. Khi dùng kết quả trong script

git ls-files --cached -z

Tùy chọn -z phân tách tên file bằng byte NUL. Công cụ nhận phía sau phải hiểu định dạng này; không chia theo khoảng trắng hoặc giả định mỗi dòng luôn là một tên file. Đặc biệt không nối đầu ra thành một lệnh shell để thực hiện thao tác file.

Với thao tác kiểm kê thủ công, dạng hiển thị thông thường dễ đọc hơn. Với tự động hóa, thiết kế parser và kiểm thử tên có khoảng trắng, ký tự đặc biệt trước khi dùng dữ liệu làm đầu vào cho bước khác.

7. Checklist bàn giao

• Xác nhận đúng repository và phạm vi thư mục.
• Xem riêng nhóm trong index, untracked và ignored.
• Đối chiếu file bắt buộc để chạy dự án với tài liệu cài đặt.
• Kiểm tra staged diff và commit trước khi kết luận file đã được bàn giao.
• Không commit bí mật chỉ để người khác có đủ cấu hình.
• Không xóa hoặc bỏ theo dõi file chỉ vì nó xuất hiện trong một nhóm kiểm kê.

Kết luận: Git ls-files giúp hiểu Git đang biết những đường dẫn nào. Một bản kiểm kê tốt tách được trạng thái theo dõi khỏi giá trị của dữ liệu và khỏi trạng thái đồng bộ lên remote.