Cách khắc phục lỗi Git "Filename too long" trên Windows

Bức tường "Filename too long" khó chịu

Hôm nay tôi đã gặp phải một vấn đề kinh điển của Windows khi cố gắng clone một dự án React có cấu trúc thư mục lồng nhau sâu. Mọi thứ bắt đầu ổn thỏa, nhưng giữa quá trình checkout, Git đã xảy ra lỗi và dừng lại hoàn toàn. Đây không phải là lỗi của chính Git, mà là một giới hạn kế thừa của Windows API vẫn còn ám ảnh chúng ta trong quá trình phát triển hiện đại.

Điều gì đã thực sự xảy ra

Thông báo lỗi trông chính xác như thế này:

error: unable to create file path/to/very/deeply/nested/directory/structure/that/never/seems/to/end/filename.js: Filename too long
fatal: unable to checkout working tree
warning: clone succeeded, but checkout failed.

Mặc dù quá trình clone "thành công", nhưng thư mục làm việc trống rỗng vì Git không thể thực sự ghi các tệp vào đĩa. Trên Windows, độ dài đường dẫn tối đa mặc định (được gọi là MAX_PATH) là 260 ký tự. Điều này bao gồm ký tự ổ đĩa, dấu hai chấm, dấu gạch chéo ngược và ký tự null kết thúc. Nếu bạn đang làm việc trong một thư mục như C:\Users\Username\Documents\Projects\Company-Internal-Tools\..., bạn đã tiêu tốn hơn 60 ký tự trước khi chạm tới thư mục gốc của dự án.

Quy trình gỡ lỗi (Debug)

Trước khi bắt tay vào sửa lỗi, tôi đã kiểm tra hai thứ:

Độ dài đường dẫn: Tôi đã sử dụng một lệnh PowerShell nhanh để xem đường dẫn bị lỗi thực sự dài bao nhiêu. Nó vào khoảng 275 ký tự.
Phiên bản Git: Tôi đảm bảo rằng mình đang chạy phiên bản Git cho Windows gần đây (git --version), vì các phiên bản cũ xử lý việc này rất kém.

Giải pháp 1: Bản sửa lỗi dành riêng cho Git (Nhanh nhất)

Cách nhanh nhất để giải quyết vấn đề này cho các thao tác Git là yêu cầu Git bỏ qua giới hạn MAX_PATH và sử dụng tiền tố UNC (Universal Naming Convention) nội bộ (\\?\) để xử lý các đường dẫn lên tới 32.767 ký tự.

Chạy lệnh này trong terminal của bạn (Command Prompt hoặc PowerShell) với quyền quản trị viên:

git config --global core.longpaths true

Tại sao cách này lại hiệu quả: Thiết lập này yêu cầu Git sử dụng các phiên bản ký tự rộng (wide-character) của Windows API, cho phép nó vượt qua giới hạn 260 ký tự. Nếu bạn không muốn áp dụng điều này trên toàn hệ thống, bạn có thể chạy nó mà không có --global bên trong một kho lưu trữ cụ thể, mặc dù thường thì bạn thậm chí không thể vào thư mục repo nếu quá trình checkout thất bại.

Sau khi chạy lệnh này, tôi đã phải reset repo để lấy lại các tệp:

git checkout -f HEAD

Giải pháp 2: Bật Đường dẫn dài trong Windows (Bản sửa lỗi vĩnh viễn)

Đôi khi việc sửa lỗi cho Git là không đủ vì các công cụ khác (như VS Code, Node.js hoặc File Explorer) vẫn có thể gặp rắc rối với những đường dẫn dài đó. Bạn có thể bật hỗ trợ đường dẫn dài trên toàn hệ thống trong Windows 10 (phiên bản 1607 trở lên) hoặc Windows 11.

Cách A: Sử dụng Registry Editor

Nhấn Win + R, gõ regedit và nhấn Enter.
Điều hướng đến: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
Tìm giá trị có tên LongPathsEnabled.
Nhấp chuột phải vào nó, chọn Modify, và thay đổi Value data từ 0 thành 1.
Khởi động lại máy tính của bạn (hoặc ít nhất là khởi động lại shell/terminal của bạn).

Cách B: Sử dụng Group Policy (Windows Pro/Enterprise)

Nhấn Win + R, gõ gpedit.msc và nhấn Enter.
Đi tới: Local Computer Policy > Computer Configuration > Administrative Templates > System > Filesystem.
Tìm Enable Win32 long paths và đặt thành Enabled.

Giải pháp 3: Giải pháp thay thế "Thủ công"

Nếu bạn đang trên một máy tính bị hạn chế quyền hạn, nơi bạn không thể chỉnh sửa Registry hoặc chạy Git với quyền admin, giải pháp "ít kỹ thuật" hơn là rút ngắn đường dẫn cơ sở của bạn. Thay vì clone vào thư mục Documents nằm sâu trong nhiều lớp, hãy clone trực tiếp vào một thư mục ở thư mục gốc của ổ đĩa.

# Thay vì thế này:
# C:\Users\MyUser\Work\Archives\2024\Projects\MyRepo

# Hãy làm thế này:
C:\> mkdir dev
C:\> cd dev
C:\dev> git clone https://github.com/org/very-long-repo-name.git

Bằng cách di chuyển thư mục gốc của dự án từ độ sâu 60 ký tự xuống còn 7 ký tự (C:\dev\), bạn có thêm 53 ký tự "không gian thở" cho các cấu trúc node_modules hoặc package lồng nhau của mình.

Các bước xác minh

Để xác nhận bản sửa lỗi đã hoạt động, tôi đã thực hiện các bước sau:

Kiểm tra cấu hình Git: Chạy git config core.longpaths. Nó sẽ trả về true.
Thử Checkout lại: Chạy git checkout [branch-name]. Nếu nó kết thúc mà không có lỗi "Filename too long", bạn đã thành công.
Truy cập tệp: Thử mở một trong những tệp lồng sâu trong trình soạn thảo mã của bạn. Nếu bạn có thể chỉnh sửa và lưu nó, hỗ trợ đường dẫn dài ở cấp hệ điều hành đang hoạt động tốt.

Bài học rút ra

Windows là trường hợp ngoại lệ: Linux và macOS hiếm khi gặp vấn đề này vì giới hạn đường dẫn của chúng cao hơn nhiều theo mặc định (thường là 4096 ký tự).
Cấu trúc dự án: Mặc dù chúng ta có thể khắc phục điều này, nhưng nhìn chung tốt nhất là nên tránh việc lồng nhau quá mức. Trong hệ sinh thái JavaScript, node_modules là thủ phạm chính, nhưng các trình quản lý gói hiện đại như pnpm sử dụng symlink có thể làm trầm trọng thêm vấn đề độ dài đường dẫn trên Windows.
CI/CD: Nếu bạn có các build runner chạy trên Windows (như GitHub Actions Windows runner), hãy đảm bảo bao gồm bước git config core.longpaths true trong các tập lệnh khởi tạo của bạn để ngăn chặn các lỗi pipeline.