Git - Different Platforms

Git - Handling Line Endings on Different Platforms

Different operating systems use different characters to mark the end of a line in text files. Unix-like systems (Linux, macOS) use a Line Feed (LF), while Windows traditionally uses a Carriage Return followed by a Line Feed (CRLF).

These differences can cause issues in version control. If a file is edited on Windows and then on Linux, Git might see every line as changed due to line ending differences, creating noisy diffs and unnecessary merge conflicts. To avoid this, Git provides ways to configure line ending normalization.

Using core.autocrlf

The core.autocrlf configuration setting tells Git how to handle line endings. It’s generally recommended to set this on a per-user basis.

For Windows users:

$ git config --global core.autocrlf true

With this setting, Git will convert LF line endings to CRLF when you check out files. When you commit files, CRLF line endings will be converted back to LF. This ensures CRLF in your working directory on Windows, but LF in the repository.

For Linux or macOS users:

$ git config --global core.autocrlf input

With this setting, Git will convert CRLF line endings to LF on commit. Files are checked out as-is (preserving LF). This ensures LF in the repository.

Setting core.autocrlf false is generally not recommended for cross-platform projects as it disables any automatic conversion, potentially leading to mixed line endings in the repository.

Using .gitattributes for Per-Repository Configuration (Best Practice)

A more robust and recommended approach, especially for team projects, is to use a .gitattributes file in the root of your repository. This file allows for per-repository and per-filetype line ending configuration, ensuring consistency for everyone working on the project, regardless of their global core.autocrlf settings.

Create a file named .gitattributes in the root of your repository with the following content for most text-based projects:

# Set default behavior for all text files.
* text=auto

# Explicitly declare text files you want to normalize.
*.c text
*.h text
*.java text
*.py text
*.js text
*.html text
*.css text
*.md text

# Declare files that should always have CRLF line endings (e.g., Windows batch files).
# *.bat text eol=crlf

# Declare files that should always have LF line endings.
# *.sh text eol=lf

# Denote binary files to prevent Git from changing them.
*.png binary
*.jpg binary
*.zip binary

* text=auto lets Git decide how to handle line endings for text files. It will typically convert to LF in the repository and use native line endings in the working directory.

Specific rules like *.c text ensure that C files are treated as text and normalized. eol=lf or eol=crlf can enforce specific line endings if needed.

Commit the .gitattributes file to your repository so these settings are shared with all collaborators. This is the most reliable way to manage line endings in a collaborative environment.