Creating a .gitattributes File

Summary: Control line endings and merge behavior using .gitattributes.

When working on collaborative software projects, maintaining consistent file treatment across different environments is crucial. The .gitattributes file gives you control over how Git handles line endings, text conversions, merge strategies, and much more. In this guide, we’ll delve into what .gitattributes is, why it matters, and how to configure it to suit your repository's needs.

What Is a .gitattributes File?

A .gitattributes file is a plain text configuration placed in the root (or any subdirectory) of your Git repository. It allows you to specify per-path attributes, influencing how Git manages files, such as:

  • Handling end-of-line (EOL) normalization
  • Defining language-specific diffing and merging behaviors
  • Specifying which files to treat as binary
  • Customizing merge tool strategies

Why Use .gitattributes?

With teams contributing from different operating systems, default line endings differ (CRLF on Windows, LF on UNIX-based systems). Without a consistent approach, you can encounter unnecessary diffs, merge conflicts, and build issues. .gitattributes lets you:

  • Normalize line endings: Avoid cross-platform conflicts.
  • Improve code reviews: Offer better diffs for code, binaries, or generated files.
  • Optimize merges: Use custom strategies for file types that are hard to merge.

Creating Your First .gitattributes File

To get started, simply create a plain text file named .gitattributes in your repository’s root:

touch .gitattributes

You can also add .gitattributes to any subdirectory for path-specific configuration.

Controlling Line Endings

One of the most common uses is to enforce consistent line endings. Here’s how to do it:

Normalize Text Files

Add this to your .gitattributes:

# Set all text files to use LF
* text=auto

# Force LF for source files
*.js     text eol=lf
*.py     text eol=lf
*.sh     text eol=lf

# Use CRLF for Windows batch files
*.bat    text eol=crlf
*.cmd    text eol=crlf

How it works:

  • text=auto tells Git to automatically detect text files and normalize line endings to LF in the repository and convert to the platform's native EOL on checkout.
  • eol=lf or eol=crlf forces a specific EOL for matching files.

Prevent EOL Normalization for Binaries

To avoid corruption, mark binaries with -text:

# Images
*.png  binary
*.jpg  binary
*.gif  binary

# Archives
*.zip  binary
*.jar  binary

Or simply:

# General rule for known binary files
*.png  -text
*.exe  -text

Custom Diff and Merge Behavior

You may want custom diffs or merges for certain file types.

Mark Files as Binary (No Diff)

*.pdf binary

Use Custom Diff Drivers

For example, to use a custom diff on .md files:

In .gitattributes:

*.md diff=markdown

Then register a diff driver in your local .git/config:

[diff "markdown"]
    command = path/to/your/markdown-diff-script

Use Merge Strategies

To always favor "ours" strategy on generated lock files:

package-lock.json merge=ours

Or mark files as unmergeable:

*.lock binary

Example: A Typical .gitattributes File

Here’s what a complete, practical .gitattributes might look like for a Node.js project:

# Normalize all text files (LF)
* text=auto

# Source code: enforce LF
*.js   text eol=lf
*.json text eol=lf
*.ts   text eol=lf

# Shell scripts: enforce LF
*.sh   text eol=lf

# Windows scripts: enforce CRLF
*.cmd  text eol=crlf
*.bat  text eol=crlf

# Binary files
*.png  binary
*.jpg  binary
*.gif  binary
*.ico  binary

# Custom merge: favor our version for lock files
package-lock.json merge=ours
yarn.lock         merge=ours

# Markdown: custom diff
*.md diff=markdown

Best Practices

  • Commit your .gitattributes file: Make sure it’s tracked, so everyone benefits from the same attributes.
  • Be specific: Apply rules as specifically as you can to avoid surprises.
  • Review changes: Git will only update normalization upon commit. Run git add --renormalize . if you change your .gitattributes after files have been committed.
  • Document unusual attributes: Leave comments explaining any non-obvious rules.

Conclusion

The .gitattributes file empowers you to enforce consistent behavior and avoid common pitfalls in cross-platform Git projects. Whether you need control over line endings, better merge handling, or custom diff strategies, a well-crafted .gitattributes is an essential tool for healthy repositories.

Further reading:

Take a few minutes to configure .gitattributes—your team will thank you!

Back to All Articles