What Is .gitattribute

Content on WhatAnswers is provided "as is" for informational purposes. While we strive for accuracy, we make no guarantees. Content is AI-assisted and should not be used as professional advice.

Last updated: April 10, 2026

Quick Answer: .gitattributes is a Git configuration file that defines attributes for pathnames in a repository, controlling how Git handles line endings (CRLF vs LF), binary files, and diff/merge behaviors across different platforms. Introduced as part of Git's attribute system and documented in Git 1.4.4+, it ensures consistent file handling across teams regardless of OS.

Key Facts

Committed to repository root, ensuring all team members use identical line ending and file handling rules
Automatically normalizes line endings to LF in Git's index while preserving platform-specific line endings in working directory
.gitattributes supersedes core.autocrlf setting, providing repository-level standardization instead of per-user local configuration
Supports 40+ built-in attributes including text, binary, eol, diff, merge, and working-tree-encoding for fine-grained file control
Prevents line ending merge conflicts by standardizing CRLF (Windows) and LF (Unix/Linux) handling across cross-platform development teams

Overview

.gitattributes is a text configuration file that resides in your Git repository and defines attributes for specific files and directories based on pathname patterns. It tells Git how to handle various file types, with special emphasis on line ending normalization, binary detection, and merge/diff strategies. This file is committed to the repository, ensuring all team members automatically use the same file handling rules regardless of their operating system.

The .gitattributes system addresses a critical problem in cross-platform development: different operating systems use different line ending conventions. Windows uses carriage return and line feed (CRLF, \r\n), while Unix, Linux, and macOS use only line feed (LF, \n). Without proper configuration, developers working on different operating systems can accidentally introduce line ending changes that create massive diff noise and merge conflicts. The .gitattributes file provides a centralized, version-controlled solution to this problem.

How It Works

The .gitattributes file uses a simple pattern-matching system where each line specifies a path pattern followed by attribute assignments. Git reads these attributes and applies them when staging files, creating diffs, performing merges, and checking out files. Here's how the core mechanisms function:

Path Matching: Patterns work similar to .gitignore, supporting wildcards like *.sh, *.txt, or specific paths. When a file matches a pattern, Git applies all attributes listed on that line to that file.
Line Ending Normalization: The text attribute tells Git to treat a file as text and normalize its line endings. Setting text=auto lets Git automatically detect text files. The eol attribute specifies the exact line ending style (lf for Unix-style or crlf for Windows-style) that should appear in the working directory when the file is checked out.
Binary File Handling: The binary attribute marks files as binary, preventing Git from attempting text diffs or line ending conversions. This is essential for image files (.png, .jpg), compiled binaries, and other non-text formats. Setting binary automatically disables the text and diff attributes.
Diff and Merge Control: You can specify custom diff and merge drivers for specific file types using attributes like diff=custom or merge=union. This allows specialized handling for formats like Excel files, PDFs, or custom binary protocols.
Text Encoding: The working-tree-encoding attribute allows Git to transparently convert files between different character encodings (e.g., UTF-16 to UTF-8) when storing them in the index while preserving the original encoding in the working directory.

Key Comparisons

Feature	.gitattributes (Repository-Level)	core.autocrlf (User-Level)
Scope	Applied uniformly to all developers who clone the repository	Must be manually configured by each developer on their machine
Version Control	Committed to the repository and tracked in Git history	Stored only in local .git/config, not shared across team
Flexibility	Supports 40+ attributes for granular file-type control including encoding and custom merge strategies	Only handles line ending conversion globally with limited options
Consistency Risk	Guarantees identical behavior across all team members and CI/CD systems	High risk of misconfiguration if developers forget to set or set differently
Typical Use	Modern approach recommended by GitHub, GitLab, and Git documentation	Legacy approach, now considered inferior to .gitattributes

Why It Matters

Cross-Platform Consistency: Teams with developers on Windows, macOS, and Linux environments can maintain identical line endings in the repository despite different OS defaults. This eliminates false diffs where the only change is line endings, which clutter pull request reviews and obscure actual code changes.
Automated Line Ending Handling: Git automatically normalizes line endings when staging files (converting to LF in the index) and when checking out files (converting back to the platform-appropriate style). Developers don't need to manually configure their systems or remember special settings.
Prevention of Merge Conflicts: When a developer on Windows commits a file with CRLF line endings that was previously committed with LF, Git's line ending normalization prevents this from appearing as a conflict. The repository maintains a consistent internal representation (LF).
CI/CD Pipeline Compatibility: Continuous integration systems running on Linux servers can work seamlessly with repositories configured for Windows developers. Without proper .gitattributes setup, CI systems often fail builds due to unexpected line ending changes or binary file detection errors.

The .gitattributes file represents a best practice that should be included in virtually every repository, especially those involving cross-platform teams. A typical configuration takes just minutes to set up but prevents hours of frustration from line ending issues and binary file mishandling. By treating file attributes as a first-class concern in version control, teams ensure that every developer automatically works with consistent file formats and encoding standards, regardless of their operating system or configuration preferences.