Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git on Windows: Filename too long and the core.longpaths fix

Windows still caps many paths at 260 characters. Shorten the clone root, enable core.longpaths system-wide, and turn on the OS long path setting.

~6 min readGit
#Git#Windows#Configuration#Troubleshooting
A git index tray with an overlong filename tape spilling out, an amber path limit gate and a cyan long path switch

Introduction & Quick Summary

error: unable to index file 'apps/web/src/...': Filename too long on Windows is not a Git bug and not a corrupt repository. Windows still enforces a 260-character limit for many path operations, the checkout path is built from your clone directory plus every directory in the repository, and Git for Windows ships with long-path support switched off. The same repository clones fine on macOS or Linux, which is why the error is often reported as "it only fails on my machine".

What actually resolves it, from least to most invasive:

  • Move the clone. C:\src\repo instead of C:\Users\you\Documents\Projects\2026\repo removes dozens of characters before Git starts.
  • Enable core.longpaths. git config --system core.longpaths true from an elevated prompt is the standard fix for Git for Windows.
  • Enable the OS setting if you want other tools to agree: the LongPathsEnabled registry value plus a manifest on the application.
  • Avoid the path entirely with sparse checkout or a deeper project layout when the offending files belong to a dependency you do not need to check out.
MessageWhere it appearsMeaning
unable to index file ... Filename too longgit addThe path exceeds the limit while staging
unable to checkout working treegit clone, git checkoutCheckout hit the limit partway
error: invalid pathgit checkoutReserved names or characters on Windows
Filename too long from npm/nodePost-checkout installThe tool, not Git, hit a path limit

Core Mechanics, Signatures & Reproducible Setup

Windows has two different limits. The classic MAX_PATH is 260 characters for the full path (drive, directories, file name). NTFS itself allows 32,767 characters, and starting with Windows 10 version 1607 the Win32 API can use the longer limit when the process opts in through a manifest and the machine has LongPathsEnabled set. Git for Windows uses plain Win32 calls, so it needs both its own core.longpaths switch and, in some commands, the OS opt-in.

Git builds the path as <worktree root>\<relative path>, so the root matters as much as the repository. A relative path of 180 characters inside a repository cloned to a 75-character root already exceeds 260. Reproduce the limit with a deliberately deep tree:

bash
mkdir deep && cd deep && git init p="a/$(printf 'b%.0s/%.0s' {1..40})c/$(printf 'd%.0s/%.0s' {1..40})leaf.txt" mkdir -p "$(dirname "$p")" && echo x > "$p" git add -A && git commit -m "deep tree"

Clone that repository into a long directory on Windows and the checkout stops with unable to checkout working tree, leaving the index populated and the working tree incomplete:

powershell
git clone https://example.com/deep.git C:\Users\me\Documents\Projects\team\service\checkout

The fix is one config value in the right file:

powershell
# elevated prompt: applies to every user and every repository git config --system core.longpaths true git config --global --get core.longpaths # confirm: true

--system matters because git.exe reads the system config first; a --global value works only when the OS long-path setting is also enabled. With the OS setting off, Git can still fail at 260 even with core.longpaths=true, because the underlying file API refuses.

Key Comparison Table

The limit belongs to the OS and the tool, not to the repository, so the same tree behaves differently on each platform.

Platform / toolPath limitNotes
Windows without opt-in260 charactersApplies to most Win32 file calls
Windows with LongPathsEnabled~32,000Requires manifest plus registry
Git for Windows, default260core.longpaths is false
Git for Windows, core.longpaths=true~32,000Still needs the OS opt-in in some cases
Linux ext44,096 bytes total, 255 per componentLong paths work; exhaust PATH_MAX rarely
macOS APFS1,024 bytes per componentCase-insensitive by default

There are four practical ways to get the files on disk, in increasing order of disruption:

ApproachEffortWorks when
Shorten the clone rootOne commandThe excess is under ~50 characters
core.longpaths=trueOne config, may need adminGit is the only tool that complains
Sparse checkoutPer-repository setupOnly a few deep directories are needed
Restructure the repositoryChanges historyPaths are genuinely too deep for every client

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

Find the offenders before changing anything

Do not guess which path is too long. Ask Git for the longest ones, then compare with the clone root length:

bash
git ls-tree -r --name-only HEAD | awk '{ print length, $0 }' | sort -rn | head -10
text
187 apps/web/node_modules/.pnpm/@scope+pkg@1.2.3/node_modules/@scope/pkg/dist/esm/internal/helpers/index.js 176 packages/ui/src/components/forms/inputs/advanced/date-range-picker/stories/basic.stories.tsx

If the top entry is 40 characters longer than the 260 minus your root, moving the clone is cheaper than any Git setting. If it is 200 characters longer, the repository layout itself is the problem.

Enable the OS long-path setting

The registry value makes the Win32 API accept long paths for applications that declare support. Set it from an elevated PowerShell, then reboot for existing processes to pick it up:

powershell
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" ` -Name LongPathsEnabled -Value 1 -PropertyType DWORD -Force
bash
git config --system core.longpaths true git --version

git --version must be run in a new shell, otherwise the old environment keeps the previous config. Some Git distributions include a manifest that declares long-path support; others do not, which is the reason core.longpaths=true alone sometimes changes nothing.

Sparse checkout for one deep dependency

When the deep paths belong to a workspace you do not need, a partial clone plus sparse checkout avoids materialising them at all:

bash
git clone --no-checkout --filter=blob:none https://example.com/monorepo.git cd monorepo git sparse-checkout init --cone git sparse-checkout set apps/api packages/shared git checkout main

This is also the right answer on CI runners with slow filesystems, since it skips the blobs you never read.

Cleaning up after a failed checkout

A failed checkout leaves the index and the working tree in disagreement, and the next git status reports deleted files that were never written. Reset deliberately; git checkout . will try to write the same long paths again and fail identically.

bash
git reset --hard HEAD git status --short | head

If the failure happened during git clone, the repository directory may be missing the .git files it needs for a retry. Delete the directory and clone again with the corrected settings rather than trying to repair it in place.

Case sensitivity, reserved names, and invalid path

Windows rejects names that other platforms allow: a trailing dot or space, CON, PRN, AUX, NUL, COM1, LPT1, and a colon anywhere but the drive letter. Git reports these as invalid path rather than "too long", and core.protectNTFS is what makes Git refuse them on checkout to avoid creating something Windows cannot open.

bash
git config --global core.protectNTFS false # avoids the failure, but creates confusing names

Prefer fixing the tree: git mv aux.txt aux-file.txt and commit the rename, so every platform gets a path that works. Disabling the protection is a local workaround that other Windows users will hit again.

Common Compilation/Runtime Mistakes & Version Gotchas

Setting core.longpaths per repository. It only affects that clone. Use --system on the machine that fails, so every repository benefits, including the ones CI clones later.

Expecting the setting to affect other tools. npm, node, python and antivirus scanners enforce their own limits. A successful checkout followed by a failing pnpm install is the OS setting, not Git, and needs the machine-wide registry value.

Cloning into a synced folder. OneDrive and Dropbox add their own path prefixes, and a deep repository inside them reaches 260 characters sooner than the same repository under C:\src. Sync also locks files during checkout, producing unrelated errors alongside the long path one.

Using --depth 1 to fix a path problem. Shallow clones change history depth, not path length. The checkout still writes the same paths.

Deleting .git/index to reset. That makes Git re-scan the working tree, and the scan is what fails. git reset --hard after the configuration fix is the safe order.

Assuming a 4096-character PATH_MAX on Linux means the same repository is safe. Linux allows the total path to be long but caps each component at 255 bytes, so a single very long file name fails there while the deep tree succeeds. Repositories that work on Windows and fail on Linux are usually this.

Version floor. core.longpaths has been in Git for over a decade; LongPathsEnabled needs Windows 10 1607 or newer; git sparse-checkout set --cone needs Git 2.25 or newer.

The most reliable order is: find the longest paths, move the clone to a short root, enable core.longpaths, then enable the OS setting if anything other than Git still fails. To extract the offending paths from a build log, the regex tester handles the quoted path patterns, and the diff tool shows exactly which files a sparse-checkout change leaves out.

Official references: core.longpaths in the git-config manual and Microsoft's maximum path length limitation.

Official references

primary documentation

The Git documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.