Blog
7 min read

Git "Filename too long" on Windows: Why It Happens and How to Fix It

Git error Filename too long means a file path passed Windows' 260-character limit. Fix it with core.longpaths, a shorter clone folder, or WSL, step by step.

Git's "Filename too long" error means a file in the repository, combined with the folder you cloned it into, adds up to a path longer than Windows' classic limit of 260 characters. Git itself has no such limit; Git for Windows enforces it by default. The usual fix is one command, git config --global core.longpaths true, followed by retrying the checkout.

Checked against the Git for Windows long paths page, Git for Windows' core.longpaths documentation and source, the git clone manual and Microsoft Learn's Maximum Path Length Limitation in November 2026.

What the error looks like

You usually see it during git clone, git checkout, git switch or git pull on Windows:

error: unable to create file src/components/dashboard/widgets/reporting/QuarterlyRevenueBreakdownChart.test.tsx: Filename too long

A folder can fail the same way:

fatal: cannot create directory at 'packages/some/deeply/nested/folder': Filename too long

When it happens during a clone, Git finishes downloading the history but can't write all the files, so it ends with:

fatal: unable to checkout working tree
warning: Clone succeeded, but checkout failed.
You can inspect what was checked out with 'git status'
and retry with 'git restore --source=HEAD :/'

That last message is good news. The repository data is on your disk; only the working files are incomplete. You don't need to clone again.

Why Windows has a 260-character limit

The Windows API defines a constant called MAX_PATH as 260 characters. That counts the whole path: the drive letter, the colon, every folder name, the file name and an invisible terminating character. Microsoft's own documentation uses Git as its example: you can hit the limit "if you are cloning a git repo that has long file names into a folder that itself has a long name."

So the problem is the sum of two parts:

  • Where you cloned it. C:\Users\alexandra\Documents\GitHub\my-company-dashboard\ is already around 50 characters before the repo's own folders start.
  • How deep the repo goes. Nested src folders, long component names, test files and generated folders add up fast.

According to the Git for Windows project, "Git's source code itself does not have the limitation, it is Windows-only." On macOS, Linux and inside WSL's Linux file system, the same repository clones without complaint. That's also why a teammate on a Mac can't reproduce your error.

Fix 1: turn on core.longpaths (the main fix)

Git for Windows has a setting, core.longpaths, that is off by default. When you turn it on, Git converts long paths to the \\?\ extended-length form, which Windows accepts for paths well beyond 260 characters.

To turn it on for every repository on your machine:

git config --global core.longpaths true

If you'd rather enable it only for one repository, run this inside that repository's folder instead:

git config core.longpaths true

Recovering a clone that already failed

You don't need to delete the half-finished clone. Move into it, enable the setting, and ask Git to write the missing files, exactly as its own message suggests:

cd my-company-dashboard
git config core.longpaths true
git restore --source=HEAD :/
git status

git restore --source=HEAD :/ rewrites the working files from the last commit. On a fresh clone that's what you want. On a repository where you've already made changes, it would overwrite them, so commit or stash your work before running it there.

Cloning with the setting from the start

git clone accepts -c to set a config value in the new repository before any files are checked out:

git clone -c core.longpaths=true https://github.com/example/my-company-dashboard.git

This is handy on a machine where you don't want to change your global Git config, such as a shared build server.

The catch

Git for Windows keeps this off by default for a reason. Its documentation says long paths aren't supported by Windows Explorer, cmd.exe and the Git for Windows tool chain (the bundled bash, perl and tcl), and asks you to enable it only if you're "prepared to live with a few quirks." In practice:

  • Git's built-in commands (clone, checkout, status, add, commit) handle the long paths.
  • Git commands implemented as scripts may still fail on those files.
  • Other programs that open the files, including your editor, build tools and File Explorer, may have their own limits.

For most people this is fine: Git can now check out the repo, and the other tools either cope or need their own fix (see Fix 3).

Fix 2: clone into a shorter folder

The simplest change involves no settings at all. Put your code close to the root of the drive:

mkdir C:\src
cd C:\src
git clone https://github.com/example/my-company-dashboard.git

Moving from C:\Users\alexandra\Documents\GitHub\ to C:\src\ saves dozens of characters, which is often enough on its own. It also helps every other tool on the machine, which core.longpaths doesn't. It's worth doing alongside Fix 1 rather than instead of it, because a repo that's close to the limit today can pass it after the next big folder rename.

Fix 3: enable long paths in Windows itself

You'll see this suggested everywhere, so it helps to know what it does and doesn't do.

Since Windows 10 version 1607, Windows can lift the 260-character limit for programs that opt in. Microsoft's docs say two things are needed: the LongPathsEnabled registry value set to 1, and the program declaring itself "long path aware" in its manifest. The registry switch alone changes nothing for programs that haven't opted in.

Git for Windows doesn't depend on this setting, because core.longpaths uses the \\?\ path form instead. Turn on the Windows setting when other tools on your machine also choke on the long paths after Git has checked them out.

From PowerShell run as Administrator (this command is from Microsoft's documentation):

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
-Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

On managed machines the same switch is a Group Policy: Computer Configuration > Administrative Templates > System > Filesystem > Enable Win32 long paths. Microsoft notes a reboot might be required, because programs that were already running read the old value.

This edits a machine-wide registry setting, so on a work laptop check with whoever manages it first.

Fix 4: work inside WSL

If you develop on Windows but your project targets Linux servers anyway, cloning inside WSL avoids the Windows limit entirely, because the files live on a Linux file system. Keep the repository in your Linux home folder (for example ~/code/my-company-dashboard) rather than under /mnt/c/, which Microsoft also recommends for file performance. (What Is WSL? explains the setup, and Claude Code on Windows: Native or WSL? covers the trade-offs for AI tooling.)

Which fix to use

Situation Do this
A clone or checkout just failed git config --global core.longpaths true, then git restore --source=HEAD :/ in the repo
You keep code deep under Documents Move it to something like C:\src
Git works now, but your editor or build tool fails on the same files Enable LongPathsEnabled (admin, possibly a reboot)
The project runs on Linux in production Clone and work inside WSL's file system
You maintain the repo Consider shorter folder and file names so Windows contributors don't hit this

Quick checklist

  1. Confirm you're on Windows and the message says Filename too long.
  2. Run git config --global core.longpaths true.
  3. In a failed clone, run git restore --source=HEAD :/, then git status.
  4. If paths are still marginal, move the repo to a short folder like C:\src.
  5. If other tools still fail, enable Win32 long paths in the registry or Group Policy.

New to cloning in general? git clone Explained walks through the basics.

EasySpawn runs your projects on a managed Linux server, so a repository cloned there never meets the Windows path limit, and you can reach it from a browser or over SSH from your Windows machine. It's pre-launch; join the waitlist if that sounds useful.

Related: What Is WSL? Running Linux on Windows, Explained · git clone Explained: Copy a Repository to Your Computer · Claude Code on Windows: Native or WSL? · Git and GitHub for Beginners: The Undo Button for Your Whole Project

Keep reading