When working with Git repositories on the Windows operating system, particularly those containing deeply nested directories such as node_modules generated by package managers,

encountering a “Filename too long” error during operations like git status or git checkout is a common obstacle. This issue arises even when attempting to add files that were seemingly committed successfully.

This article explores the underlying causes of this limitation and presents several effective strategies derived from established practices to configure Git and Windows for handling long file paths.

Understanding the File Path Limitation on Windows

Historically, standard Windows APIs imposed a maximum path length limitation (often referred to as MAX_PATH), typically restricting file paths to 260 characters. While Git itself supports much longer paths (up to 4096 characters), versions of Git for Windows, especially those compiled with certain environments like older msys versions, could inherit this operating system restriction.

Git includes a configuration setting, core.longpaths, designed to enable support for longer paths by utilizing different Windows APIs. However, this option is not enabled by default because enabling it might lead to compatibility issues or unexpected behavior (“quirks”) with certain Git scripts or external tools that do not fully support long paths.

Modern versions of Windows (specifically Windows 10 version 1607 and later) introduced a system-level option to remove the MAX_PATH limitation more broadly, but this requires explicit activation.

Solutions for Enabling Long Path Support

Several methods can be employed to address the “Filename too long” error, ranging from Git configuration adjustments to system-level changes and project-specific workarounds.

1. Configure Git to Handle Long Paths (`core.longpaths`)

The primary method involves enabling Git’s built-in support for long paths using the git config command. This can be applied at different configuration levels:

System-Wide Configuration (Requires Administrator Privileges)

This setting applies to all users and repositories on the system. Execute the following command in a command prompt or Git Bash session run as Administrator:

git config --system core.longpaths true

Note: Attempting to run this command without administrator privileges will likely result in a “Permission denied” error related to locking the system Git configuration file (e.g., C:/Program Files/Git/mingw64/etc/gitconfig).

Read: How to Upgrade Git on Windows

User-Global Configuration (Recommended if Admin Rights Are Unavailable)

This setting applies to all repositories for the current user and typically does not require administrator rights:

git config --global core.longpaths true

This is often a practical alternative if system-wide changes are restricted or cause permission errors. Some GUI clients like GitHub Desktop might specifically read the --global configuration rather than the --system one.

Repository-Local Configuration

To enable long paths only for a specific project, navigate into the repository’s directory and run:

git config core.longpaths true

This approach confines the setting’s effect, which can be preferable if there are concerns about potential side effects associated with the core.longpaths setting on other projects.

Configuration During Clone

You can enable long paths specifically when cloning a new repository:

git clone -c core.longpaths=true 

This sets the configuration variable immediately after the repository is initialized but before files are checked out.

Manual Configuration File Edit

As an alternative to command-line configuration, you can manually edit the relevant Git configuration file. Locate the appropriate .gitconfig file (e.g., C:\Users\\.gitconfig for global settings, or .git/config within the repository for local settings) and add or modify the [core] section:

[core]
    longpaths = true

This method can be useful if command-line tools are unavailable or encounter permission issues that cannot be resolved via elevation.

Using PowerShell for Elevated Configuration

To apply the system or global setting with explicit elevation from PowerShell:

For system-wide setting:

Start-Process -Verb RunAs "git" "config","--system","core.longpaths","true"

For user-global setting (usually doesn’t need elevation but can be run this way):

Start-Process -Verb RunAs "git" "config","--global","core.longpaths","true"

2. Enable Long Path Support in Windows (Windows 10 v1607+)

For systems running Windows 10 version 1607 or later, you can enable long path support at the operating system level. This generally needs to be done *in addition* to the Git configuration (core.longpaths=true).

Via Registry Editor (Requires Administrator Privileges)

1. Open Registry Editor (regedit).
2. Navigate to the following key:
HKLM\SYSTEM\CurrentControlSet\Control\FileSystem
3. Find or create a DWORD (32-bit) Value named LongPathsEnabled.
4. Set its value data to 1.

A system restart might be required for this change to take full effect.

Alternatively using PowerShell (Requires Administrator privileges):

# Check current setting
Get-ItemProperty HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled

# Set the value to 1 (requires elevation)
# Note: Changes might require a restart
Set-ItemProperty HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name LongPathsEnabled -Type DWord -Value 1

Via Group Policy (Windows 10 Pro/Enterprise)

1. Open Local Group Policy Editor (gpedit.msc).
2. Navigate to: Computer Configuration → Administrative Templates → System → Filesystem.
3. Open the “Enable Win32 long paths” policy setting.
4. Set it to “Enabled”.

3. Project-Specific Workarounds

Exclude Problematic Directories

If the long paths primarily exist within dependencies like node_modules, consider excluding this directory from version control:

1. Ensure node_modules is listed in your .gitignore file.
2. If the directory has already been tracked, remove it from the Git index:

git rm -r --cached node_modules

3. Commit the changes to .gitignore and the removal:

git add .gitignore
git commit -m "Exclude node_modules from tracking"

This approach relies on package managers (like npm or yarn) to restore dependencies based on manifest files (e.g., package.json, package-lock.json). While common practice, ensure this aligns with project requirements for reproducibility.

Shorten the Repository Base Path

The total path length includes the repository’s location on disk. If possible, clone or move the repository to a location closer to the drive’s root (e.g., C:\dev\myproject instead of C:\Users\\Documents\Projects\...\myproject). This reduces the base length, potentially keeping deeply nested file paths below the problematic limit.

Update Dependency Managers

Older versions of package managers like npm (pre-v3) created deeply nested node_modules structures. Updating to newer versions (npm v3+) often results in a “flatter” dependency structure, which can significantly reduce maximum path lengths and alleviate the issue.

# Example for updating npm and reinstalling dependencies
npm install -g npm@latest
rm -rf node_modules
npm install

Consider Filesystem Interactions

In some edge cases, issues might arise from interactions with specific filesystem features, such as encrypted partitions. If working on an encrypted drive, temporarily moving the repository to a standard, unencrypted partition (like a temporary folder) for Git operations, then moving it back, might serve as a workaround.

4. Tool-Specific Adjustments

TortoiseGit

If using TortoiseGit:

1. Right-click the repository folder, select TortoiseGit → Settings.
2. Go to the Git tab.
3. Click Edit local .git/config.
4. Add longpaths = true under the [core] section in the text file that opens.
5. Save the file.

This applies the setting locally for that specific repository.

SourceTree

Ensure SourceTree is configured to use the “System” Git installation rather than its embedded version, as the system version is more likely to respect the core.longpaths setting configured via the command line.

Verification

After applying one or more of the solutions above, verify the fix by re-running the Git command that previously failed. For example, execute git status or attempt the checkout/clone operation again. If the “Filename too long” error no longer appears, the configuration is effective.

Potential Issues and Considerations

• Administrator Privileges: Modifying system-wide Git configuration (--system) or Windows Registry/Group Policy settings requires administrator rights.
• Permission Errors: The “Permission denied” error when using git config --system is common without elevation. Use --global, local configuration, or ensure the command prompt/terminal is run as Administrator.
• GUI Tool Behavior: Some Git GUI clients might not read the --system configuration or may require specific settings to use the system’s Git instance. Using --global is often more reliable for GUIs.
• Compatibility Quirks: Remember that core.longpaths = true is not the default for a reason. While generally safe, it might theoretically cause issues with older scripts or tools not designed for long paths. Apply it locally first if concerned.
• Windows Version: The system-level Windows fix (Registry/Group Policy) is only available on Windows 10 version 1607 and newer.
• Reboot Requirement: Changes to the Windows Registry or Group Policy for long paths might require a system restart to take effect fully.

Conclusion

The “Filename too long” error in Git on Windows stems primarily from the operating system’s historical path length limitations interacting with Git’s operations.

By enabling the core.longpaths setting within Git (at the appropriate scope) and, if necessary, enabling system-wide long path support in modern Windows versions, this limitation can be effectively overcome.

Workarounds like adjusting project structure, excluding problematic directories, or shortening base paths provide alternative solutions when configuration changes are not feasible or fully sufficient.