How to fix Filename too long in Git

GitBEGINNERMEDIUM

This error occurs when Git encounters a file path that exceeds the operating system's maximum path length limit. On Windows, this is typically 260 characters (MAX_PATH). The fix involves enabling Git's long path support and configuring Windows to handle extended paths.

What this error means

The "Filename too long" error in Git indicates that a file path in your repository exceeds the maximum path length allowed by your operating system. This is most commonly encountered on Windows, where the traditional MAX_PATH limit is 260 characters (including the drive letter, colon, backslash, and null terminator). This limitation stems from the Windows API, which historically used fixed-size buffers for file paths. While modern Windows versions (Windows 10 version 1607 and later) support extended-length paths up to approximately 32,767 characters, this support isn't enabled by default. The error typically appears when: - **Cloning a repository** that contains deeply nested directories or long filenames - **Checking out a branch** that has files with long paths - **Pulling changes** that add files exceeding the path limit - **Working with JavaScript/Node.js projects** where `node_modules` creates extremely deep directory structures Git on Linux and macOS rarely encounters this issue since those systems typically support path lengths of 4,096 characters or more. The problem is almost exclusively a Windows concern.

How to fix "Filename too long"

1Enable Git's long path support

The most direct fix is to configure Git to handle long paths. Run this command in an elevated (Administrator) command prompt or PowerShell:

bash

git config --global core.longpaths true

This tells Git to use the Windows extended-length path APIs instead of the legacy MAX_PATH-limited functions.

Verify the setting:

bash

git config --global --get core.longpaths

This should return true.

For a specific repository only:

bash

git config core.longpaths true

Note: This setting only affects Git's operations. Other Windows applications may still have issues with these long paths.

2Enable Windows long path support (Windows 10/11)

For a comprehensive fix on Windows 10 version 1607 and later, enable system-wide long path support:

Method 1: Using Group Policy Editor (Windows Pro/Enterprise)

1. Press Win + R, type gpedit.msc, and press Enter
2. Navigate to: Computer Configuration > Administrative Templates > System > Filesystem
3. Find and double-click "Enable Win32 long paths"
4. Select "Enabled" and click OK
5. Restart your computer

Method 2: Using Registry Editor (All Windows editions)

1. Press Win + R, type regedit, and press Enter
2. Navigate to: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
3. Find or create a DWORD value named LongPathsEnabled
4. Set its value to 1
5. Restart your computer

Method 3: Using PowerShell (as Administrator)

powershell

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

After enabling this, restart your computer for the changes to take effect.

3Clone into a shorter base path

If you can't modify system settings, reduce the base path length where you clone repositories:

Instead of:

bash

C:\Users\YourName\Documents\Projects\Development\MyCompany\Frontend\Repositories\my-project

Use:

bash

C:\Dev\my-project

Steps:
1. Create a short directory near your drive root:

cmd

mkdir C:\Dev
cd C:\Dev

2. Clone your repository there:

bash

git clone https://github.com/user/repo.git

This gives you more "path budget" for the files within the repository.

Using subst to create a virtual drive:

cmd

subst X: "C:\Users\YourName\Documents\Projects\Development"
X:
git clone https://github.com/user/repo.git

This creates a virtual drive X: pointing to your long path, effectively shortening the visible path.

4Fix an existing repository with long path errors

If you've already cloned a repository and are now seeing errors, follow these steps:

1. Enable long paths (if not already done):

bash

git config --global core.longpaths true

2. Reset the repository to restore missing files:

bash

git reset --hard HEAD

3. If reset fails, try a sparse checkout first:

bash

git sparse-checkout init --cone
git sparse-checkout set <directories-you-need>

4. For severely broken repositories, re-clone:

bash

# Save any local changes first
git stash

# Move the broken repo
mv my-project my-project-broken

# Clone fresh with long paths enabled
git clone https://github.com/user/repo.git my-project

# Apply your stashed changes if needed
cd my-project
git stash apply

5. Verify all files are present:

bash

git status

If files still show as deleted that shouldn't be, the repository may need the Windows long path setting enabled.

5Handle node_modules specifically

Node.js projects are notorious for deep node_modules directory structures. Here are targeted solutions:

Option 1: Use npm's flat node_modules (npm 3+)
Modern npm versions flatten the dependency tree by default, but you can force it:

bash

npm dedupe

Option 2: Use pnpm instead of npm
pnpm uses a content-addressable store and symlinks, dramatically reducing path lengths:

bash

npm install -g pnpm
pnpm install

Option 3: Exclude node_modules from Git
Ensure node_modules is in your .gitignore (it should always be):

bash

node_modules/

Option 4: Use Yarn with Plug'n'Play (PnP)
Yarn's PnP mode eliminates node_modules entirely:

bash

yarn set version berry
yarn config set nodeLinker pnp
yarn install

If node_modules is accidentally committed:

bash

# Remove from Git tracking (keeps local files)
git rm -r --cached node_modules
echo "node_modules/" >> .gitignore
git commit -m "Remove node_modules from tracking"

6Use Git's sparse-checkout for selective cloning

If you only need specific parts of a repository with long paths, use sparse-checkout to avoid the problematic files:

Initialize sparse-checkout:

bash

git clone --filter=blob:none --sparse https://github.com/user/repo.git
cd repo

Select specific directories:

bash

git sparse-checkout set src docs config

Add more directories later:

bash

git sparse-checkout add tests

View current sparse-checkout configuration:

bash

git sparse-checkout list

Disable sparse-checkout and get everything:

bash

git sparse-checkout disable

This approach lets you work with repositories that have problematic paths without ever downloading the long-path files.

Advanced notes

Understanding Windows Path Limits:

The Windows MAX_PATH limit of 260 characters is calculated as:
- Drive letter: 1 character (e.g., C)
- Colon: 1 character
- Backslash: 1 character
- Path: up to 256 characters
- Null terminator: 1 character

The actual usable path is therefore 256 characters maximum.

Extended-Length Paths (\\?\):

Windows has always supported paths up to 32,767 characters using the \\?\\C:\\ prefix syntax. The Windows 10 long path setting essentially makes applications use this extended syntax transparently.

Why Git on Windows Has This Problem:

Git was originally developed for Linux (for the Linux kernel), where path limits are typically 4,096 characters (PATH_MAX). Many repositories developed on Linux/macOS don't consider Windows path limits, leading to this issue when Windows developers clone them.

Git for Windows Implementation:

When core.longpaths is enabled, Git for Windows:
1. Converts paths to the extended-length format (\\?\\)
2. Uses wide-character (Unicode) Win32 API functions
3. Bypasses the legacy ANSI path limitations

MinGW/MSYS2 Considerations:

Git for Windows uses MSYS2, which has its own path handling. Some operations may still fail even with long paths enabled if they go through MSYS2's path translation layer. In such cases:

bash

# Use Windows-native path format
git clone https://github.com/user/repo.git "C:\Dev\repo"

CI/CD Pipeline Considerations:

On CI systems like GitHub Actions, Azure DevOps, or Jenkins running on Windows:

yaml

# GitHub Actions example
- name: Enable long paths
  run: git config --system core.longpaths true
  shell: cmd

- name: Checkout
  uses: actions/checkout@v4

For Azure DevOps:

yaml

steps:
- checkout: self
  fetchDepth: 1
  lfs: false
  submodules: false
  persistCredentials: true
- script: git config core.longpaths true

WSL (Windows Subsystem for Linux):

If you frequently work with repositories that have long paths, consider using WSL:
- Linux path limits apply within WSL
- Access from Windows (\\wsl$\Ubuntu\home\...) still has Windows limits
- Keep repositories within WSL's filesystem for best compatibility

Preventing Long Path Issues in New Projects:

1. Keep directory nesting shallow: Avoid deeply nested folder structures
2. Use short, meaningful names: src instead of source_code_files
3. Configure CI to test on Windows: Catch path issues before they affect Windows developers
4. Use package managers wisely: pnpm, Yarn PnP, or npm's --legacy-bundling=false
5. Add path checks to pre-commit hooks: Warn about files approaching the limit

Checking Path Lengths:

powershell

# PowerShell: Find files with paths > 200 characters
Get-ChildItem -Recurse | Where-Object { $_.FullName.Length -gt 200 } |
  Select-Object FullName, @{N='Length';E={$_.FullName.Length}} |
  Sort-Object Length -Descending

# PowerShell: Find the longest paths in a directory
Get-ChildItem -Recurse | Sort-Object { $_.FullName.Length } -Descending |
  Select-Object -First 20 FullName, @{N='PathLength';E={$_.FullName.Length}}

Third-Party Tool Issues:

Even with Git configured correctly, other tools may fail:
- Some IDEs don't support long paths
- Windows Explorer has historical issues (improved in Windows 10+)
- Build tools may use legacy APIs
- Antivirus software may fail to scan long-path files

Always test your complete toolchain when working with repositories that have long paths.

How to fix Filename too long in Git

What this error means

Typical symptoms

Common causes

How to fix "Filename too long"

Advanced notes

Related errors

Official resources & further reading