DEV Community

Cover image for How a .gitattributes File Fixed Broken Images (and Why You Should Use One Too!)
Justin J Daniel
Justin J Daniel

Posted on • Originally published at justinjdaniel.com

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

#git #webdev #productivity #beginners

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
  • Text Files: Enforce consistent line endings: 
  *.js eol=lf
  *.jsx eol=lf
  *.md text
Enter fullscreen mode Exit fullscreen mode
  • Large Files: For large assets, consider using Git LFS and mark them in .gitattributes: 
  *.psd filter=lfs diff=lfs merge=lfs -text
Enter fullscreen mode Exit fullscreen mode
  • Generated or Vendor Files: Hide from diffs or language stats: 
  /dist/* linguist-generated=true
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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! ❤️

Top comments (1)