How to fix error: invalid path 'file<name>.txt' (contains invalid Windows characters) in Git

GitINTERMEDIATEMEDIUM

This error occurs when Git encounters a file path containing characters that are invalid on Windows filesystems. Characters like < > : " | ? * cannot be used in Windows filenames, causing checkout failures when repositories created on Linux/macOS contain such files.

What this error means

This error occurs when you're working with a Git repository that contains files with characters in their names that Windows does not allow. Windows has strict rules about which characters can appear in file and folder names, while Linux and macOS are much more permissive. The following characters are forbidden in Windows file and folder names: - `<` (less than) - `>` (greater than) - `:` (colon) - `"` (double quote) - `|` (pipe) - `?` (question mark) - `*` (asterisk) - `\` (backslash, except as path separator) - Characters with ASCII values 0-31 (control characters) Additionally, Windows reserves certain names like CON, PRN, AUX, NUL, COM1-COM9, and LPT1-LPT9 regardless of file extension. When you try to check out a branch or clone a repository containing files with these characters, Git on Windows cannot create them and reports this error. This is a common issue when collaborating across operating systems, as developers on Linux or macOS may not realize they've created files that Windows users cannot access.

How to fix "error: invalid path 'file<name>.txt' (contains invalid Windows characters)"

1Identify the problematic files

First, identify which files contain invalid Windows characters. The error message usually tells you the filename, but you can list all problematic files:

bash

# On Linux/macOS, find files with Windows-invalid characters
find . -name '*[<>:"|?*]*' -o -name '*[\x00-\x1f]*'

# Using Git to list files in the repository
git ls-files | grep -E '[<>:"|?*]'

# Or check what files would be created during checkout
git diff --name-only HEAD origin/main | grep -E '[<>:"|?*]'

Note the exact filenames and their locations in the repository structure.

2Enable Git's core.protectNTFS setting

Git has a safety setting to prevent checking out files with invalid Windows characters. Make sure it's enabled (it's on by default):

bash

# Check current setting
git config core.protectNTFS

# Enable protection (recommended)
git config core.protectNTFS true

# This setting prevents Git from creating files that would be
# problematic on Windows, even when running on Linux/macOS

With this enabled, Git will refuse to check out problematic files rather than silently corrupting them or failing in unexpected ways.

3Rename files on a compatible system

The proper fix is to rename the problematic files. This must be done on a system that can access them (Linux, macOS, or WSL):

bash

# On Linux/macOS or WSL, clone or checkout the repository
git checkout branch-with-problematic-files

# Rename the file to use valid Windows characters
# Replace < > : " | ? * with alternatives like _ - ( )
git mv "file<name>.txt" "file_name.txt"
git mv "test:case.txt" "test-case.txt"
git mv "query?.txt" "query.txt"

# Commit the rename
git commit -m "Rename files to use Windows-compatible characters"

# Push the fix
git push origin branch-name

After this commit is pushed, Windows users can checkout the branch normally.

4Use sparse checkout to skip problematic files

If you cannot rename the files (e.g., you don't have write access), use sparse checkout to exclude them:

bash

# Initialize sparse checkout
git sparse-checkout init

# Set patterns to exclude problematic files
git sparse-checkout set '/*' '!path/to/problematic*'

# Or specify exactly what you want to include
git sparse-checkout set 'src/' 'docs/' 'package.json'

# Now checkout should work
git checkout branch-name

The excluded files will remain in Git's index but won't be created in your working directory.

Note: You won't be able to modify these files while using sparse checkout.

5Use WSL on Windows

Windows Subsystem for Linux (WSL) can handle these filenames because it uses a Linux filesystem:

bash

# Install WSL (from PowerShell as Administrator)
wsl --install

# After restart, open WSL terminal
wsl

# Clone the repository inside WSL's filesystem (not /mnt/c/)
cd ~
git clone https://github.com/user/repo.git
cd repo

# Work with the repository in WSL
git checkout branch-with-problematic-files

Important: Keep the repository in the WSL filesystem (~/), not in the Windows filesystem (/mnt/c/). Files with special characters cannot exist on the Windows filesystem even when accessed through WSL.

6Skip the checkout of specific files

You can tell Git to skip updating specific files in the working directory:

bash

# Mark the file to be skipped during checkout
git update-index --skip-worktree path/to/problematic/file

# Or use assume-unchanged (less recommended)
git update-index --assume-unchanged path/to/problematic/file

# Now checkout should succeed, skipping those files
git checkout branch-name

Caveat: These files won't be tracked for changes in your working copy. This is a workaround, not a solution.

To undo:

bash

git update-index --no-skip-worktree path/to/file
git update-index --no-assume-unchanged path/to/file

7Create a pre-commit hook to prevent future issues

To prevent this problem from recurring, add a pre-commit hook that checks for Windows-incompatible filenames:

Create .git/hooks/pre-commit (or add to existing):

bash

#!/bin/bash
# Prevent commits with Windows-invalid characters in filenames

# Characters invalid on Windows: < > : " | ? * and control chars
INVALID_CHARS='[<>:"|?*]'

# Check staged files for invalid characters
invalid_files=$(git diff --cached --name-only | grep -E "$INVALID_CHARS")

if [ -n "$invalid_files" ]; then
    echo "ERROR: The following files contain Windows-invalid characters:"
    echo "$invalid_files"
    echo ""
    echo "Please rename these files before committing."
    exit 1
fi

exit 0

Make it executable:

bash

chmod +x .git/hooks/pre-commit

For team-wide enforcement, consider using a tool like Husky or pre-commit that can be version-controlled.

Advanced notes

### Windows Filename Restrictions Reference

The complete list of Windows filename restrictions:

| Character | Why Invalid |
|-----------|-------------|
| < | Reserved for redirection |
| > | Reserved for redirection |
| : | Drive separator (C:) |
| " | String delimiter |
| | | Pipe operator |
| ? | Wildcard character |
| * | Wildcard character |
| \ | Path separator |
| / | Path separator |
| NUL (0x00) | String terminator |
| 0x01-0x1F | Control characters |

Reserved names (case-insensitive, with any extension):
- CON, PRN, AUX, NUL
- COM1-COM9, LPT1-LPT9

### Using Git Attributes for Cross-Platform Compatibility

You can use .gitattributes to handle line endings, but unfortunately there's no built-in attribute for filename restrictions. However, you can document requirements:

text

# .gitattributes
# Note: All filenames must be Windows-compatible
# Avoid: < > : " | ? * and control characters

### Automated Filename Sanitization

For bulk renaming on Linux/macOS:

bash

# Find and rename files with invalid characters
find . -name '*[<>:"|?*]*' -print0 | while IFS= read -r -d '' file; do
    # Replace invalid chars with underscores
    newname=$(echo "$file" | sed 's/[<>:"|?*]/_/g')
    if [ "$file" != "$newname" ]; then
        git mv "$file" "$newname"
    fi
done

### Git Configuration for Cross-Platform Teams

Recommended settings for teams with Windows and Unix developers:

bash

# Enforce Windows compatibility checks
git config core.protectNTFS true

# Handle line endings
git config core.autocrlf input  # On Linux/macOS
git config core.autocrlf true   # On Windows

# Enable long path support on Windows
git config core.longpaths true

### CI/CD Considerations

If your CI runs on both Windows and Linux:

1. Add a validation job that runs on Linux and checks for Windows-incompatible filenames
2. Fail fast before Windows jobs attempt checkout
3. Document filename requirements in CONTRIBUTING.md

Example GitHub Actions job:

yaml

validate-filenames:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Check for Windows-invalid characters
      run: |
        invalid=$(git ls-files | grep -E '[<>:"|?*]' || true)
        if [ -n "$invalid" ]; then
          echo "::error::Files with Windows-invalid characters found:"
          echo "$invalid"
          exit 1
        fi

### Unicode and International Characters

Note that this error is specifically about the reserved Windows characters, not about Unicode or international characters. Modern Windows (with UTF-8 support enabled) handles most Unicode characters fine:

- file_名前.txt - Valid on Windows
- file<name>.txt - Invalid on Windows
- file:name.txt - Invalid on Windows (looks like drive letter)

### Path Length Limitations

Windows also has a 260-character path limit (MAX_PATH) by default. If you're seeing path errors that aren't about invalid characters, you may need:

bash

# Enable long paths in Git
git config core.longpaths true

And enable long path support in Windows:

powershell

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

How to fix error: invalid path 'file<name>.txt' (contains invalid Windows characters) in Git

What this error means

Typical symptoms

Common causes

How to fix "error: invalid path 'file<name>.txt' (contains invalid Windows characters)"

Advanced notes

Related errors

Official resources & further reading