Оффлайн
- Регистрация
- 1 Мар 2015
- Сообщения
- 1,481
- Баллы
- 155
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?
*.png binary
*.jpg binary
*.gif binary
*.pdf binary
*.zip binary
*.js eol=lf
*.jsx eol=lf
*.md text
*.psd filter=lfs diff=lfs merge=lfs -text
/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
git add .gitattributes
git commit -m "Add .gitattributes for correct file handling"
git push
Extra Tips
Thank you for reading, and have a beautiful day!
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.
- 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
- Create a .gitattributes file in your repo's root.
- Add the patterns and attributes you need.
- 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 .
Thank you for reading, and have a beautiful day!