Managing Line Endings with Git

Line endings are a surprisingly common source of difficulty when working on cross-platform projects, particularly when collaborating with others. Different operating systems use different characters to signify the end of a line in a text file. Windows uses a combination of Carriage Return (CR) and Line Feed (LF), denoted as \r\n. Unix-based systems (Linux, macOS) use only Line Feed (\n). This difference can manifest as unexpected changes or difficulties when merging code if not properly managed. Git offers several ways to handle these differences, ensuring consistency across platforms.

Understanding the Problem

When you create a text file on Windows and commit it to a Git repository, the \r\n line endings are stored. If a collaborator using a Unix-based system checks out the file, their text editor might interpret the \r as an unwanted character, causing visual issues or errors. Conversely, if a file created on Unix with \n line endings is checked out on Windows, it might appear as a single long line in some editors.

Git’s Approaches to Line Endings

Git provides several configurations to address these issues, allowing you to control how line endings are treated during checkout and commit. The primary mechanism for this control is the core.autocrlf configuration option. There are three main settings:

true (Checkout Windows-style, commit Unix-style): This is the recommended setting when working on a cross-platform project from Windows. Git will convert LF to CRLF when checking out text files, and CRLF to LF when committing them.
input (Checkout as-is, commit Unix-style): This is recommended when working on a cross-platform project from Unix/macOS. Git will not perform any conversion during checkout but will convert CRLF to LF during commit.
false (Checkout as-is, commit as-is): Git will not perform any line ending conversion at all. This is generally not recommended for cross-platform projects as it can lead to inconsistencies.

Configuring `core.autocrlf`

You can configure core.autocrlf globally (for all your Git repositories) or locally (for a specific repository).

Globally:

git config --global core.autocrlf true  # For Windows
git config --global core.autocrlf input # For Unix/macOS

Locally (within a repository):

Navigate to the repository’s root directory in your terminal and run:

git config core.autocrlf true  # For Windows
git config core.autocrlf input # For Unix/macOS

To view your current configuration, use:

git config --get core.autocrlf

Using `.gitattributes` for Fine-Grained Control

While core.autocrlf is useful for broad control, the .gitattributes file provides even more granular control over line endings. This file resides in the root of your repository and allows you to define line ending behavior for specific file types or paths.

Here are some common .gitattributes configurations:

* text=auto: This treats all files as text and automatically converts line endings during checkout and commit, based on the operating system. This is a good default for most projects.
*.txt text: This explicitly marks all .txt files as text, ensuring line ending conversion.
*.jpg -text: This marks all .jpg files as binary, preventing any line ending conversion. Binary files should not have their line endings modified.
*.sh text eol=lf: This forces all .sh (shell script) files to use LF line endings.
*.vcproj text eol=crlf: This forces all .vcproj (Visual Studio project) files to use CRLF line endings.

Example .gitattributes file:

* text=auto
*.jpg -text
*.sh text eol=lf
*.vcproj text eol=crlf

Best Practices

Consistency is Key: Choose a strategy (global core.autocrlf or .gitattributes) and stick with it across your team.
Use .gitattributes for Specific Needs: If you have files that require specific line endings, use .gitattributes to enforce them.
Binary Files: Always mark binary files (images, compiled code) as -text in .gitattributes to prevent unwanted line ending conversions.
Team Communication: Ensure all team members are aware of the chosen line ending strategy.