How to fix warning: path 'file.txt' contains non-UTF-8 characters in Git

GitINTERMEDIATELOW

This Git warning appears when a filename contains characters that are not valid UTF-8 encoding. It commonly occurs with files created on systems using different character encodings (like Latin-1 or Windows code pages) and can cause cross-platform issues.

What this error means

Git expects path names (filenames and directory names) to be encoded in UTF-8 normalization form C. When Git encounters a filename that contains byte sequences that don't form valid UTF-8 characters, it displays this warning. At its core, Git treats path names as sequences of bytes rather than characters. However, Git's display utilities and many Git-based tools assume path names are UTF-8 encoded. When a filename contains bytes that represent characters in a different encoding (such as ISO-8859-1/Latin-1, Windows-1252, or other legacy encodings), Git cannot properly interpret or display the filename. This warning doesn't prevent Git from tracking the file, but it signals a potential portability problem. Repositories with non-UTF-8 filenames may work on the system where they were created but cause issues when cloned to systems with different locale settings. Many Git GUIs, web interfaces, and CI/CD systems will fail to display these filenames correctly or may fail to process them entirely.

How to fix "warning: path 'file.txt' contains non-UTF-8 characters"

1Identify the problematic files

First, find which files have non-UTF-8 characters in their names:

bash

# List all tracked files and look for warnings
git ls-files

# Check the status to see warnings
git status

Files with encoding issues will trigger warnings. You may also see filenames displayed as quoted octal sequences like "file\303\251.txt" instead of the actual characters.

To see the raw bytes of a filename:

bash

# On Linux/macOS
ls -b
# Or use hexdump to see the actual bytes
ls | hexdump -C

2Configure Git to display non-ASCII characters properly

By default, Git quotes non-ASCII characters in filenames. Disable this to see the actual characters:

bash

# Stop quoting high-byte characters
git config --global core.quotePath false

This won't fix the encoding issue, but it will display the characters as-is rather than as escaped sequences.

Additionally, ensure your Git environment uses UTF-8:

bash

# Set commit and log output encoding
git config --global i18n.commitEncoding utf-8
git config --global i18n.logOutputEncoding utf-8

3Check your system locale settings

Verify that your system is configured to use UTF-8:

On Linux:

bash

# Check current locale
locale

# The LANG and LC_ALL should include UTF-8, like:
# LANG=en_US.UTF-8

If not set to UTF-8, configure it:

bash

# Set UTF-8 locale (add to ~/.bashrc or ~/.zshrc)
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

On macOS:

bash

# Check current settings
locale

# Set in ~/.zshrc or ~/.bash_profile
export LANG=en_US.UTF-8

On Windows Git Bash:

bash

# Check current settings
echo $LANG

# Set in ~/.bashrc
export LANG=en_US.UTF-8

4Rename files with proper UTF-8 encoding

The most reliable fix is to rename the files using proper UTF-8 encoding. First, use the convmv tool (Linux) to convert filenames:

bash

# Install convmv (Debian/Ubuntu)
sudo apt-get install convmv

# Install convmv (macOS with Homebrew)
brew install convmv

# Preview what would change (dry run)
convmv -f iso-8859-1 -t utf-8 -r .

# Actually rename the files
convmv -f iso-8859-1 -t utf-8 -r --notest .

Replace iso-8859-1 with the actual source encoding if different (common alternatives: windows-1252, cp437, latin1).

Manual rename approach:

bash

# Remove the old file from Git
git rm --cached "oldfilename"

# Rename the file on the filesystem
mv "oldfilename" "newfilename_utf8"

# Add the renamed file
git add "newfilename_utf8"

# Commit the change
git commit -m "Rename file to use UTF-8 encoding"

5Handle macOS Unicode normalization issues

macOS uses a unique Unicode normalization (NFD - decomposed form) that can conflict with other systems using NFC (composed form). Git 1.7.12+ includes support for this:

bash

# Enable Unicode precomposition for macOS
git config --global core.precomposeUnicode true

This setting ensures Git normalizes Unicode characters consistently, preventing issues when sharing repositories between macOS and Linux/Windows.

If you're experiencing issues where filenames with accents appear differently on macOS vs other systems, this setting should resolve the discrepancy.

6Configure for Git for Windows

Git for Windows requires specific configuration for proper UTF-8 handling:

bash

# Comprehensive UTF-8 configuration
git config --global core.quotePath false
git config --global i18n.commitEncoding utf-8
git config --global i18n.logOutputEncoding utf-8
git config --global gui.encoding utf-8

Additionally, ensure your terminal supports UTF-8. In Git Bash, you can set:

bash

# Add to ~/.bashrc
export LESSCHARSET=utf-8

For PowerShell, set the output encoding:

powershell

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

7Verify the fix

After renaming files or configuring Git, verify the warning is resolved:

bash

# Check status - should show no encoding warnings
git status

# List files - should display properly without escaping
git ls-files

# View your configuration
git config --list | grep -E "(quote|i18n|precompose)"

If you've renamed files, commit the changes:

bash

git add -A
git commit -m "Fix non-UTF-8 filename encoding"

Advanced notes

### Understanding Git's Path Encoding

Git internally stores path names as byte sequences, not as Unicode strings. The index file, tree objects, and ref names all use UTF-8 normalization form C (NFC). However, Git doesn't perform encoding conversions on paths at the core level (except on macOS and Windows for specific normalizations).

This means:
- A file named "cafe.txt" (with e-acute encoded in Latin-1) will have different bytes than the same visual filename encoded in UTF-8
- Git will track both as different files if both exist
- Many Git tools assume UTF-8 and will fail with other encodings

### Common Encoding Mismatches

| Source Encoding | Common On | Byte Example for "e" |
|----------------|-----------|---------------------|
| UTF-8 | Modern systems | c3 a9 |
| ISO-8859-1 (Latin-1) | Western European legacy | e9 |
| Windows-1252 | Windows applications | e9 |
| Mac Roman | Legacy macOS | 8c |

### Repository Migration Strategy

If you have a legacy repository with many non-UTF-8 filenames:

1. Clone on a system with the original encoding - Set your locale to match the encoding used when files were created
2. Use `convmv` to batch convert - Convert all filenames to UTF-8
3. Commit the renames - Create a single commit with all renames
4. Update `.gitattributes` - If needed, specify encodings for file contents (separate from filenames)

### BOM and .gitignore Files

Files like .gitignore, .gitattributes, and other Git configuration files must not have a UTF-8 BOM (Byte Order Mark). If your editor adds a BOM, Git may fail to parse these files correctly:

bash

# Check for BOM
file .gitignore
# Should say "ASCII text" or "UTF-8 Unicode text", NOT "UTF-8 Unicode (with BOM)"

# Remove BOM if present (using sed)
sed -i '1s/^\xEF\xBB\xBF//' .gitignore

### Cross-Platform Repositories

For teams working across different operating systems:

1. Standardize on UTF-8 for all filenames
2. Avoid special characters in filenames when possible
3. Use .gitattributes to enforce consistent line endings
4. Enable core.precomposeUnicode on macOS
5. Consider using ASCII-only filenames for maximum compatibility

How to fix warning: path 'file.txt' contains non-UTF-8 characters in Git

What this error means

Typical symptoms

Common causes

How to fix "warning: path 'file.txt' contains non-UTF-8 characters"

Advanced notes

Related errors

Official resources & further reading