Fix Git 'Filename too long' Error When Cloning or Checking Out on Windows

What happened

You tried to clone a repo — or switch branches — and Git bailed out with this:

error: unable to create file some/very/deeply/nested/path/component/filename.tsx: Filename too long
fatal: unable to checkout working tree

The working tree is incomplete. Files exist in the index but not on disk. Running git status shows hundreds of deletions that aren't real.

This is a Windows-only problem. Linux and macOS allow path lengths up to ~4096 characters. Windows caps file paths at 260 characters by default — a limit inherited from DOS called MAX_PATH. When a repo has deeply nested folders (monorepos, generated code, Java Maven layouts, heavily nested React component trees), paths blow past that limit and Git can't write the files.

Confirming it's the path length

Before applying any fix, verify this is actually the cause and not a permissions issue or a filesystem problem.

Check how long the offending path actually is. Copy the path from the error message and run:

# In PowerShell
$path = "C:\Users\yourname\projects\some\very\deeply\nested\path\component\filename.tsx"
$path.Length

If the number is over 260, you've confirmed the issue. You can also check the current Git setting:

git config --global core.longpaths

If it returns nothing or false, long path support is off — that's your problem.

Fix 1: Enable longpaths in Git (quick fix, usually enough)

Git for Windows has a config flag that tells it to use Windows extended-length path syntax (\\?\ prefix) internally. Enable it globally so it applies to all your repos:

git config --global core.longpaths true

Then retry the clone or checkout:

# If cloning fresh
git clone https://github.com/org/repo.git

# If you already cloned and the working tree is broken
git checkout HEAD -- .

For most repos, this is all you need. Git wraps the Windows API calls with the extended path prefix and bypasses the 260-character cap on its own.

Fix 2: Enable long path support at the Windows level (required for some cases)

Some tools in your workflow — editors, build scripts, npm, package managers — also hit the same limit. If the Git fix alone isn't enough, or you want a permanent solution for everything on the machine, enable long paths in Windows itself.

Option A: Group Policy (Windows 10 Pro / Enterprise / Windows 11)

Press Win + R, type gpedit.msc, press Enter.
Navigate to: Local Computer Policy → Computer Configuration → Administrative Templates → System → Filesystem
Double-click "Enable Win32 long paths" and set it to Enabled.
Click OK and reboot (or run gpupdate /force from an admin terminal).

Option B: Registry edit (works on all Windows editions)

# Run PowerShell as Administrator
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1

Reboot after making this change.

Option C: One-liner via reg.exe (admin terminal)

reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f

Fix 3: Clone to a shorter base path

If you can't change system settings (e.g., on a corporate machine without admin rights), the practical workaround is cloning directly to a short root path:

# Instead of cloning into a deeply nested folder:
git clone https://github.com/org/repo.git C:\r\repo

# Or use a drive root
mkdir D:\dev
git clone https://github.com/org/repo.git D:\dev\repo

Moving the repo root from C:\Users\yourname\Documents\projects\work\2024\... to something like C:\dev\repo often shaves 50–80 characters off every path, which is enough to clear the 260-char ceiling.

Verifying the fix worked

After applying whichever fix fits your situation:

# Check the git setting is active
git config --global core.longpaths
# Should output: true

# Retry checkout and watch for errors
git checkout main

# Confirm no files are missing
git status
# Should show: nothing to commit, working tree clean

# Count files that were checked out vs what the index expects
git ls-files | wc -l
git ls-files --deleted | wc -l
# Second command should output 0

If git ls-files --deleted still shows files, run git checkout HEAD -- . to force-restore the working tree now that the fix is in place.

A note on team-wide prevention

If your team uses Windows and the repo has deep nesting, add a note in your README or onboarding docs to run git config --global core.longpaths true on setup. You can also ship a setup script that applies it automatically:

# setup.sh / setup.ps1 onboarding step
git config --global core.longpaths true
echo "Git longpaths enabled."

CI systems running on Windows (GitHub Actions windows-latest, Azure Pipelines) sometimes need this too. Add it as a step before your checkout action:

# GitHub Actions
- name: Enable long paths
  run: git config --global core.longpaths true
  shell: bash

- uses: actions/checkout@v4

Lessons learned

The 260-character Windows path limit is ancient and still bites people constantly. It's not a Git bug — Git is just the messenger. The real fix is either telling Git to use the Windows extended-path API (core.longpaths true) or enabling it system-wide. The Git config fix is two seconds and handles 95% of cases. If you're on a machine where even that doesn't help, shorten your clone path — it's the fastest escape hatch when you can't touch system settings.