How a .gitattributes File Fixed My Broken Images (and Why You Should Use One Too!)

3 min read
How a .gitattributes File Fixed My Broken Images (and Why You Should Use One Too!) cover image

Recently, I ran into an issue where images in a documentation repository wouldn't render locally. After some digging, I realized the problem was that Git wasn't treating image files as binary, causing them to break, even in VSCode. The fix? Adding a .gitattributes file!

This post explains why .gitattributes matters, what problems it solves, and how you can use it to avoid file mishandling in your own projects.

#What is a .gitattributes File?

A .gitattributes file is a simple text file you add to your repository to tell Git how to handle specific files or patterns. Each line specifies a pattern (like *.png) and one or more attributes (like marking a file as binary).

Example:

*.png binary
*.jpg binary
*.md text

#Why is .gitattributes Important?

  • Prevents Broken Images and Binaries:
    Without proper attributes, Git might treat images or other binaries as text, corrupting them during commits or merges.
  • Consistent Line Endings:
    Handles differences between Windows (CRLF) and Unix (LF) systems, avoiding annoying diffs and merge conflicts caused by inconsistent line endings.
  • Improves Diffs and Merges:
    You can tell Git to ignore diffs for generated files, or use custom merge strategies for complex file types.
  • Better Collaboration:
    Ensures everyone on your team, regardless of OS or editor, works with files in the correct format.

#What Files Should You Add to .gitattributes?

  • Images and Binaries:
    Mark all image, audio, video, and compiled files as binary: 
    *.png binary
*.jpg binary
*.gif binary
*.pdf binary
*.zip binary
  • Text Files:
    Enforce consistent line endings: 
    *.js eol=lf
*.jsx eol=lf
*.md text
  • Large Files:
    For large assets, consider using Git LFS and mark them in .gitattributes: 
    *.psd filter=lfs diff=lfs merge=lfs -text
  • Generated or Vendor Files:
    Hide from diffs or language stats: 
    /dist/* linguist-generated=true

#Sample .gitattributes for a Documentation Repo

# Treat images as binary
*.png binary
*.jpg binary
*.gif binary
*.svg binary # SVGs are text-based (XML) but often treated as binary to prevent line-ending/merge issues.

# Treat markdown as text
*.md text

# Enforce LF for code files
*.js eol=lf
*.jsx eol=lf
*.json eol=lf

# Hide build files from diffs and stats
/dist/* linguist-generated=true

#How to Add and Commit a .gitattributes File

  1. Create a .gitattributes file in your repo's root.
  2. Add the patterns and attributes you need.
  3. Commit the file: 
    git add .gitattributes
git commit -m "Add .gitattributes for correct file handling"
git push

#Extra Tips

  • Use .gitattributes to set custom merge strategies or encoding for special file types.
  • For existing repos, you may need to re-add files with git add --renormalize . to apply new attributes.
  • For really big files (like Photoshop files), look into Git LFS.

#Useful Links

Thank you for reading, and have a beautiful day! ❤️