Solving Windows Path Length Limitations in Git

By Shady Nagy

Published in Github

May 10, 2025

4 min read

Solving Windows Path Length Limitations in Git

Introduction

Understanding Windows Path Length Limitations

The Solution: git config --system core.longpaths true

Implementing the Solution

Potential Issues and Troubleshooting

Best Practices

Conclusion

Additional Resources

Feedback and Questions

Introduction

As developers, we’ve all experienced the frustration of path-related errors in Windows environments. Perhaps you’ve cloned a repository with deeply nested directories, or your project’s file structure has grown organically over time. Suddenly, Git operations fail with cryptic “Filename too long” errors, bringing your workflow to a screeching halt.

This is a common problem in Windows environments, but fortunately, Git provides a straightforward solution: the core.longpaths configuration option. In this article, we’ll explore:

Why Windows has path length limitations and how they affect Git
How the git config --system core.longpaths true command solves this problem
Step-by-step instructions for implementing this fix
Common scenarios where this configuration is beneficial
Potential complications and how to address them

Let’s dive in and unlock the full potential of Git on Windows systems.

Understanding Windows Path Length Limitations

The 260-Character Constraint

Windows has historically enforced a maximum path length of 260 characters, a limitation rooted in the legacy of the Windows API. This constraint comes from the MAX_PATH definition in the Windows header files:

#define MAX_PATH 260

This limitation includes:

Drive letter (e.g., “C:“)
Colon and backslash
Path components (directories and filename)
Null terminator

While 260 characters might seem sufficient for most use cases, modern development environments with nested package structures, descriptive folder names, and deep directory hierarchies can quickly exceed this limit.

How This Affects Git Users

Git was originally developed for Unix-like systems, which have much higher path length limits. When working with Git on Windows, the operating system’s path length limitation can cause operations to fail when:

Cloning repositories with deeply nested structures
Creating or checking out branches with long names
Working with npm packages (notorious for deep directory nesting)
Managing monorepo projects with multiple nested packages

Error messages typically appear like this:

error: unable to create file [long path]: Filename too long

These errors can be particularly frustrating when working with large projects or when collaborating with teams using different operating systems.

The Solution: git config —system core.longpaths true

What This Command Does

The Git configuration command git config --system core.longpaths true tells Git to enable support for long file paths on Windows systems. Let’s break down each component:

git config: The base command for modifying Git configuration
--system: Applies the configuration at the system level (for all users on the machine)
core.longpaths: The specific configuration option for path length handling
true: Enables support for long paths

When this configuration is set, Git bypasses the default Windows API path length limitation by using the extended-length path prefix \\?\ internally, which allows paths up to approximately 32,767 characters.

System-Wide vs. Repository-Specific Configuration

There are three levels at which you can configure Git:

Level	Command	Affects	Configuration File
System	`--system`	All users, all repositories	`C:\Program Files\Git\etc\gitconfig`
Global	`--global`	Current user, all repositories	`~/.gitconfig`
Local	`--local`	Current repository only	`.git/config`

Using --system applies the configuration to all users and all repositories on the machine, making it ideal for shared development environments or when you want to set this configuration once and forget about it.

Implementing the Solution

Prerequisites

Administrative privileges on your Windows machine
Git installed on your system
Command Prompt or PowerShell with administrative rights

Step-by-Step Instructions

Open Command Prompt or PowerShell as Administrator
Right-click on Command Prompt or PowerShell and select “Run as administrator”.
Run the Git Configuration Command
Enter the following command:
```
git config --system core.longpaths true
```
Verify the Configuration
To confirm the configuration was applied correctly, run:
```
git config --system --get core.longpaths
```
The output should be true.
Test with a Repository
If you previously encountered path length issues with a specific repository, try the Git operation again to confirm the problem is resolved.

Alternative Approaches

If you don’t have administrative privileges or prefer not to make system-wide changes, you can apply the configuration at different levels:

Global configuration (affects all your repositories):
```
git config --global core.longpaths true
```
Repository-specific configuration (affects only the current repository):
```
git config core.longpaths true
```

Potential Issues and Troubleshooting

Command Failed with Access Denied

If you receive an “Access denied” error when running the command, ensure you’re using Command Prompt or PowerShell with administrative privileges.

Still Encountering Path Length Issues

If you continue to experience path length issues after applying the configuration:

Verify Windows Long Path Support Is Enabled
Windows 10 (version 1607 and later) and Windows 11 have a Group Policy setting that needs to be enabled:
1. Press Win + R, type gpedit.msc, and press Enter
2. Navigate to Computer Configuration > Administrative Templates > System > Filesystem
3. Find and enable “Enable Win32 long paths”
4. Restart your computer
Check Git Version
Ensure you’re using Git version 2.8.0 or later, which introduced the core.longpaths option:
```
git --version
```
Consider Path Structure Optimization
If possible, reorganize your repository structure to reduce path lengths:
- Use shorter directory names
- Reduce nesting depth
- Move deeply nested files closer to the root

Collaboration Considerations

Remember that this configuration is specific to Windows. When collaborating with team members using different operating systems:

Document the need for this configuration in your project’s README
Consider implementing CI/CD pipelines on systems with appropriate configurations
Use .gitattributes to help manage line endings and other cross-platform issues

Best Practices

Documentation

Always document this configuration in your project’s README or contributing guidelines, especially for projects likely to encounter path length issues.

Example README section:

## Windows Development Setup

This repository contains files with long paths. Windows users should run the following command before cloning:

```bash
git config --system core.longpaths true

Repository Structure Planning

Proactively design your repository structure to minimize path length where possible:

Choose concise but descriptive directory names
Avoid unnecessary nesting
Consider flatter structures for generated files

Continuous Integration Considerations

If your CI/CD pipeline runs on Windows servers, ensure the core.longpaths configuration is applied in your build environment.

Conclusion

The git config --system core.longpaths true command is a simple yet powerful solution to a common frustration for Windows developers working with Git. By understanding and implementing this configuration, you can prevent path-related errors and enjoy a smoother development experience, even with complex or deeply nested projects.

While this configuration addresses the immediate symptom, remember that good repository structure design and conscious path management remain best practices for maintainable codebases.