Mark Binary Files in .gitattributes

Why Binary Files Need Explicit Marking

Git's auto-detection (text=auto) is usually good at distinguishing text from binary files, but it can occasionally misidentify a binary file as text. When this happens, Git's line ending normalization corrupts the file by modifying byte sequences that happen to match CR or LF characters.

The binary Attribute

# Images
*.png  binary
*.jpg  binary
*.jpeg binary
*.gif  binary
*.ico  binary
*.webp binary
*.svg  text

# Fonts
*.woff  binary
*.woff2 binary
*.ttf   binary
*.eot   binary
*.otf   binary

# Archives
*.zip  binary
*.gz   binary
*.tar  binary
*.7z   binary

# Compiled
*.exe  binary
*.dll  binary
*.so   binary
*.dylib binary

The binary attribute is a macro that expands to -text -diff -merge:

Attribute	Effect
-text	No line ending normalization
-diff	No textual diff output (shows "Binary files differ")
-merge	No three-way merge (always conflicts)

SVG: A Special Case

SVG files are XML-based and therefore text, not binary. They should be marked as text so Git can normalize their line endings and produce meaningful diffs. However, if your SVGs are auto-generated and very large, you might prefer text -diff to normalize endings but suppress noisy diffs.

Fonts and Web Assets

Web font formats (WOFF, WOFF2, TTF, EOT, OTF) are binary data and must never be modified by Git's normalization. Incorrectly handling these leads to broken fonts that fail to render in browsers.

Large Binary Files

For repositories with many or large binary files, consider using Git LFS (Large File Storage) instead of storing them directly. In that case, the .gitattributes entry would look like:

*.psd filter=lfs diff=lfs merge=lfs -text
*.ai  filter=lfs diff=lfs merge=lfs -text