Chuyện gì đã xảy ra
Bạn thử clone một repo — hoặc chuyển branch — và Git dừng lại với thông báo sau:
error: unable to create file some/very/deeply/nested/path/component/filename.tsx: Filename too long
fatal: unable to checkout working tree
Working tree bị thiếu file. Các file tồn tại trong index nhưng không có trên ổ đĩa. Chạy git status sẽ hiện hàng trăm file bị xóa nhưng thực ra không phải vậy.
Đây là vấn đề chỉ xảy ra trên Windows. Linux và macOS cho phép đường dẫn dài tới ~4096 ký tự. Windows mặc định giới hạn đường dẫn file ở 260 ký tự — một giới hạn kế thừa từ DOS có tên là MAX_PATH. Khi một repo có các thư mục lồng nhau sâu (monorepo, code được sinh tự động, cấu trúc Java Maven, cây component React lồng nhiều tầng), đường dẫn sẽ vượt quá giới hạn đó và Git không thể ghi file.
Xác nhận nguyên nhân do độ dài đường dẫn
Trước khi áp dụng bất kỳ cách sửa nào, hãy xác minh đây thực sự là nguyên nhân chứ không phải vấn đề quyền truy cập hay lỗi filesystem.
Kiểm tra xem đường dẫn gây lỗi thực sự dài bao nhiêu. Sao chép đường dẫn từ thông báo lỗi và chạy:
# Trong PowerShell
$path = "C:\Users\yourname\projects\some\very\deeply\nested\path\component\filename.tsx"
$path.Length
Nếu con số trả về lớn hơn 260, bạn đã xác nhận được vấn đề. Bạn cũng có thể kiểm tra cài đặt Git hiện tại:
git config --global core.longpaths
Nếu không trả về gì hoặc trả về false, tức là hỗ trợ đường dẫn dài đang bị tắt — đó chính là nguyên nhân.
Cách sửa 1: Bật longpaths trong Git (nhanh, thường là đủ)
Git for Windows có một cờ cấu hình cho phép nó sử dụng cú pháp đường dẫn mở rộng của Windows (tiền tố \\?\) ở tầng nội bộ. Bật toàn cục để áp dụng cho tất cả repo của bạn:
git config --global core.longpaths true
Sau đó thử lại lệnh clone hoặc checkout:
# Nếu clone mới
git clone https://github.com/org/repo.git
# Nếu đã clone và working tree bị hỏng
git checkout HEAD -- .
Với phần lớn repo, chỉ cần vậy là xong. Git tự bọc các lời gọi Windows API bằng tiền tố đường dẫn mở rộng và bỏ qua giới hạn 260 ký tự.
Cách sửa 2: Bật hỗ trợ đường dẫn dài ở cấp Windows (cần thiết trong một số trường hợp)
Một số công cụ trong workflow của bạn — editor, build script, npm, package manager — cũng gặp phải giới hạn tương tự. Nếu chỉ sửa Git vẫn chưa đủ, hoặc bạn muốn giải pháp lâu dài cho toàn bộ máy, hãy bật đường dẫn dài trong chính Windows.
Tùy chọn A: Group Policy (Windows 10 Pro / Enterprise / Windows 11)
- Nhấn
Win + R, gõgpedit.msc, nhấn Enter. - Điều hướng đến: Local Computer Policy → Computer Configuration → Administrative Templates → System → Filesystem
- Nhấp đúp vào "Enable Win32 long paths" và đặt thành Enabled.
- Nhấn OK và khởi động lại máy (hoặc chạy
gpupdate /forcetừ terminal quản trị).
Tùy chọn B: Chỉnh sửa Registry (hoạt động trên mọi phiên bản Windows)
# Chạy PowerShell với quyền Administrator
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1
Khởi động lại máy sau khi thực hiện thay đổi này.
Tùy chọn C: Lệnh một dòng qua reg.exe (terminal quản trị)
reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f
Cách sửa 3: Clone vào đường dẫn gốc ngắn hơn
Nếu bạn không thể thay đổi cài đặt hệ thống (ví dụ: máy công ty không có quyền admin), cách thực tế nhất là clone trực tiếp vào một đường dẫn gốc ngắn:
# Thay vì clone vào thư mục lồng sâu:
git clone https://github.com/org/repo.git C:\r\repo
# Hoặc dùng thư mục gốc ổ đĩa
mkdir D:\dev
git clone https://github.com/org/repo.git D:\dev\repo
Chuyển thư mục gốc của repo từ C:\Users\yourname\Documents\projects\work\2024\... sang dạng như C:\dev\repo thường giúp cắt bớt 50–80 ký tự khỏi mỗi đường dẫn, đủ để vượt qua giới hạn 260 ký tự.
Xác nhận cách sửa đã có tác dụng
Sau khi áp dụng cách sửa phù hợp với tình huống của bạn:
# Kiểm tra cài đặt git đã được bật
git config --global core.longpaths
# Kết quả mong đợi: true
# Thử lại checkout và quan sát lỗi
git checkout main
# Xác nhận không thiếu file nào
git status
# Kết quả mong đợi: nothing to commit, working tree clean
# Đếm số file đã được checkout so với index
git ls-files | wc -l
git ls-files --deleted | wc -l
# Lệnh thứ hai phải trả về 0
Nếu git ls-files --deleted vẫn hiển thị file, hãy chạy git checkout HEAD -- . để buộc khôi phục lại working tree sau khi cách sửa đã được áp dụng.
Lưu ý về việc phòng ngừa cho cả nhóm
Nếu nhóm của bạn dùng Windows và repo có cấu trúc thư mục lồng sâu, hãy thêm ghi chú vào README hoặc tài liệu onboarding để chạy git config --global core.longpaths true khi cài đặt môi trường. Bạn cũng có thể đưa bước này vào script setup để tự động áp dụng:
# Bước onboarding trong setup.sh / setup.ps1
git config --global core.longpaths true
echo "Git longpaths enabled."
Các hệ thống CI chạy trên Windows (GitHub Actions windows-latest, Azure Pipelines) đôi khi cũng cần cài đặt này. Hãy thêm nó như một bước trước action checkout:
# GitHub Actions
- name: Enable long paths
run: git config --global core.longpaths true
shell: bash
- uses: actions/checkout@v4
Bài học rút ra
Giới hạn đường dẫn 260 ký tự của Windows đã có từ rất lâu và vẫn liên tục gây khó chịu cho mọi người. Đây không phải lỗi của Git — Git chỉ là người đưa tin. Cách sửa thực sự là hoặc bảo Git dùng Windows extended-path API (core.longpaths true), hoặc bật nó ở cấp toàn hệ thống. Cách sửa qua Git config chỉ mất vài giây và giải quyết được 95% trường hợp. Nếu bạn đang dùng máy mà ngay cả cách đó cũng không giải quyết được, hãy rút ngắn đường dẫn clone — đó là lối thoát nhanh nhất khi bạn không thể chỉnh sửa cài đặt hệ thống.