In this article, we analyse the .gitattributes from the react/.gitattributes. When you are part of a team, you and your colleagues often work on projects across different operating systems and development environments. As a result, file formatting issues, especially related to line endings, can arise.
Linux/macOS use a Line Feed (LF) character.
Windows uses a Carriage Return + Line Feed (CRLF) combination.
using .gitattributes you can define file’s line endings. We will study the .gitattributes from React source and find out how.
.gitattributes is a configuration file that defines attributes for paths in a Git repository. These attributes allow you to control how Git processes different types of files during specific operations, such as:
Check-in and check-out: How files are stored in the repository and retrieved in the working directory. Link to docs
Diff and merge behavior: How changes to files are compared or merged. Link to docs.
EOL (End of Line) conversion: Ensuring line endings are consistent across operating systems (Linux/macOS vs. Windows). Link to docs
The file can be committed into the repository and versioned, meaning its rules are applied consistently for every collaborator, regardless of their local settings.
Cross-Platform Consistency: Different operating systems use different end-of-line (EOL) characters (LF on Unix-based systems, CRLF on Windows). Without .gitattributes, inconsistencies in line endings can result in unnecessary changes being detected, cluttering your Git history and causing conflicts.
Binary vs. Text File Handling: Git automatically tries to detect whether a file is binary or text, but it may not always get it right (e.g., files that are partially ASCII but contain binary data). .gitattributes ensures that files are treated correctly, whether they’re text, binary, or specific formats like images or PDFs.
3. Control Over Diffs and Merges: .gitattributes can define custom diff and merge strategies, enabling better control over how files are compared and resolved during conflict situations.
A typical .gitattributes file looks something like this:
# Auto-detect text files and ensure LF line endings in the repository* text=auto# Windows batch scripts must use CRLF*.bat text eol=crlf# Go files should use LF only*.go text eol=lf# Binary files should not be modified by Git*.png binary*.jpg binary*.pdf binary
text=auto: Automatically detects whether a file is text or binary. If the file is text, Git converts line endings to LF on check-in. This prevents cross-platform issues caused by different EOL characters.
*.bat text eol=crlf: Forces Windows batch scripts to always use CRLF for proper execution on Windows.
*.go text eol=lf: Ensures Go files use LF, which is the standard line ending on Linux and macOS.
*.png binary: Prevents Git from attempting to diff or alter binary files like PNGs, which are not human-readable and should not have EOL conversions.
This simple line ensures that files with text content (such as JavaScript files) have their line endings converted to LF in the repository while preserving the developers’ local EOL preferences. This setup is enough to prevent line-ending issues across platforms while keeping the repository clean and consistent.
This attribute enables Git’s automatic handling of line-ending normalization. It ensures that line endings are consistent (LF) in the repository while allowing the developer’s system to handle them according to local conventions (e.g., CRLF on Windows).
Set: Enables EOL conversion on check-in and checkout, normalizing line endings to LF in the repository.
Unset: Disables any line-ending conversion for the specified files.
text=auto: Automatically detects if a file is text or binary. Git performs EOL normalization if the file is identified as text.
The necessity of .gitattributes depends on the project. For simple projects, Git is often smart enough to handle file types and line endings automatically. However, in larger projects with cross-platform teams, not having a .gitattributes file can lead to:
Inconsistent Line Endings: Developers on Windows may accidentally commit CRLF line endings, creating unnecessary changes in the repository.
Imagine just the EOL lines changes appearing in your pull request?
Incorrect Binary Handling: Git may misinterpret binary files as text, leading to corrupt diffs or merge conflicts.
Merge and Diff Issues: Custom merge strategies (e.g., for Unity or image files) are impossible without .gitattributes.
Hey, my name is Ramu Narasinga. I study large open-source projects and create content about their codebase architecture and best practices, sharing it through articles, videos.
