How to fix warning: BOM detected in file, this may cause issues in Git

GitBEGINNERLOWUpdated Dec 2, 2025· 309 views

Git has detected a UTF-8 Byte Order Mark at the beginning of a file. While valid UTF-8, BOMs can cause cross-platform compatibility issues with diff, merge, and patch operations.

Quick fix

Fixes warning: BOM detected in file, this may cause issues

  1. Check which files contain BOMs
  2. Remove BOM using your text editor
  3. Remove BOM using command-line tools
  4. Configure .gitattributes for automatic handling
  5. Commit the BOM removal
git — error
# warning: BOM detected in file, this may cause issues
warning: BOM detected in file, this may cause issues

What this error means

A Byte Order Mark (BOM) is a special Unicode character (0xEF 0xBB 0xBF) that some text editors add to the beginning of UTF-8 files. While technically valid UTF-8, the BOM is unnecessary and even problematic for UTF-8 encoding because UTF-8 has a fixed byte order. Git detects these BOMs and may warn you because they can cause various issues in version control workflows. Git treats file content as byte sequences and does not strip or ignore the BOM. This means the BOM becomes part of the tracked content. When files with BOMs are used in cross-platform projects (Windows, Linux, macOS), they can cause problems with git diff, git apply, scripts with shebangs, and other tools that don't expect the invisible BOM bytes. According to RFC 3629, the UTF-8 BOM is "useless" and not recommended. Git's official documentation recommends storing all text files as UTF-8 without BOM with LF line endings for best cross-platform compatibility.

Typical symptoms

  • Git shows warning message about BOM detected in file
  • git diff shows entire file as changed when only BOM was added/removed
  • git apply fails when applying patches to files with BOM
  • Markdown files (README.md) display incorrectly with first line formatting issues
  • Shell scripts with shebangs fail to execute on Linux/Unix systems
  • CI/CD pipelines fail due to encoding mismatches
  • Git merge conflicts appear in files that haven't actually changed

Common causes

  1. Windows text editors (Notepad, Visual Studio) adding BOM by default when saving UTF-8 files
  2. VS Code or other editors configured to save files as "UTF-8 with BOM"
  3. Google Docs exporting documents as text with BOM included
  4. PowerShell scripts created on Windows with UTF-8-BOM encoding
  5. Files copied from Windows systems where BOMs are common practice
  6. Legacy editors that require BOM to detect UTF-8 encoding
  7. Automatic encoding conversion tools adding BOMs incorrectly

How to fix "warning: BOM detected in file, this may cause issues"

1Check which files contain BOMs

Use this command to identify all files with UTF-8 BOM in your repository:

You can also check a specific file:

2Remove BOM using your text editor

VS Code:
1. Click "UTF-8 with BOM" in the bottom-right status bar
2. Select "Save with Encoding"
3. Choose "UTF-8" (without BOM)

Visual Studio:
1. Go to File → Save As
2. Click the dropdown arrow on the Save button
3. Select "Save with Encoding"
4. Choose "Unicode (UTF-8 without signature)"

Visual Studio Code (command):

3Remove BOM using command-line tools

For Unix/Linux systems, use sed or specialized tools:

For batch processing multiple files:

4Configure .gitattributes for automatic handling

If you must work with files that require BOM in working directory (e.g., legacy Windows tools), use .gitattributes to handle encoding conversion:

Note: The UTF-8-BOM encoding in .gitattributes only works on Windows. This will break repository compatibility on Linux/macOS systems.

5Commit the BOM removal

After removing BOMs from your files, commit the changes:

Git will detect the BOM removal as a content change and commit it.

6Prevent future BOMs with editor settings

Configure your development tools to never add BOMs:

VS Code (settings.json):

EditorConfig (.editorconfig):

Git hooks: Create a pre-commit hook to automatically strip BOMs:

Advanced notes

Why Windows adds BOMs: Windows Notepad and some Microsoft tools add BOMs on purpose because older versions required the BOM to correctly detect UTF-8 encoding. Modern editors don't need this, but the practice persists for backward compatibility.

BOM and shebangs: If a shell script starts with a shebang () and has a BOM, the BOM becomes part of the interpreter path, causing "interpreter not found" errors on Unix systems. The kernel sees instead of .

Git's handling philosophy: Git intentionally does not strip BOMs or treat them as whitespace because Git's core principle is to preserve content exactly as authored. This makes BOM handling a repository policy decision rather than a tool decision.

Cross-platform encoding strategy: For projects that must support both Windows-only tools (requiring BOM) and Unix systems (requiring no BOM), use .gitattributes with working-tree-encoding to store files as UTF-8 without BOM in the repository, converting to BOM on Windows checkouts. However, this only works if all contributors use Windows, as Linux/macOS Git doesn't support the UTF-8-BOM encoding.

Alternative to BOMs: If you need to ensure UTF-8 encoding is detected, rely on proper Content-Type headers in web contexts, file extensions, or explicit encoding declarations in file formats that support them (like XML or HTML meta tags).

Frequently asked questions

What does "warning: BOM detected in file, this may cause issues" mean?
A Byte Order Mark (BOM) is a special Unicode character (0xEF 0xBB 0xBF) that some text editors add to the beginning of UTF-8 files. While technically valid UTF-8, the BOM is unnecessary and even problematic for UTF-8 encoding because UTF-8 has a fixed byte order. Git detects these BOMs and may warn you because they can cause various issues in version control workflows.
How do I fix "warning: BOM detected in file, this may cause issues"?
Git has detected a UTF-8 Byte Order Mark at the beginning of a file. While valid UTF-8, BOMs can cause cross-platform compatibility issues with diff, merge, and patch operations.
What causes "warning: BOM detected in file, this may cause issues"?
Windows text editors (Notepad, Visual Studio) adding BOM by default when saving UTF-8 files VS Code or other editors configured to save files as "UTF-8 with BOM" Google Docs exporting documents as text with BOM included
Is the "warning: BOM detected in file, this may cause issues" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading