Introduction

core.autocrlf=true tells Git to convert line endings between CRLF (Windows) and LF (Unix/macOS) automatically. On commit, it converts CRLF to LF so the repository stores consistent Unix-style line endings. On checkout, it converts LF back to CRLF so Windows tools display files correctly. This prevents diff noise where every line appears changed just because of line ending differences, and avoids merge conflicts caused by different developers using different operating systems. For modern projects, .gitattributes is the preferred approach, but core.autocrlf=true remains common on Windows workstations.

What Line Endings Are

1Unix/Linux/macOS line ending (LF):
2  Hello\n
3  World\n
4
5Windows line ending (CRLF):
6  Hello\r\n
7  World\r\n
8
9\n = Line Feed (0x0A)
10\r = Carriage Return (0x0D)

Different operating systems use different characters to mark the end of a line. When a Windows developer commits a file with CRLF endings and a macOS developer opens it, tools may display extra ^M characters. When both edit the file, Git sees every line as changed even if only the line endings differ.

The Three Settings

1# Windows: convert CRLF→LF on commit, LF→CRLF on checkout
2git config --global core.autocrlf true
3
4# macOS/Linux: convert CRLF→LF on commit, no conversion on checkout
5git config --global core.autocrlf input
6
7# No conversion at all
8git config --global core.autocrlf false

Why Use core.autocrlf=true

1# Scenario: mixed team, no .gitattributes
2
3# Developer A (Windows, autocrlf=true)
4echo "hello" > file.txt     # File has CRLF on disk
5git add file.txt             # Git stores LF in the repository
6git commit -m "add file"
7
8# Developer B (macOS, autocrlf=input)
9git pull                     # Gets LF on disk (no conversion needed)
10echo "world" >> file.txt     # Appends with LF
11git commit -am "append"
12
13# Developer A pulls
14git pull                     # Converts LF back to CRLF on disk
15# Windows tools see CRLF — no issues
16# Repository always has LF — clean diffs

With autocrlf=true, Windows developers work with CRLF locally while the repository stays LF-normalized. This prevents the "every line changed" problem in diffs.

The Better Alternative: .gitattributes

1# .gitattributes (committed to the repository)
2* text=auto
3
4# Force LF for specific file types
5*.sh text eol=lf
6*.bash text eol=lf
7
8# Force CRLF for Windows-specific files
9*.bat text eol=crlf
10*.cmd text eol=crlf
11
12# Binary files — no conversion
13*.png binary
14*.jpg binary
15*.zip binary

# After adding .gitattributes, normalize existing files
git add --renormalize .
git commit -m "Normalize line endings"

.gitattributes is committed to the repository and applies to all developers regardless of their local Git config. * text=auto detects text files and normalizes them to LF on commit, similar to autocrlf=true but enforced at the repository level.

When autocrlf Causes Problems

1# Problem 1: binary files misidentified as text
2# Git may convert line-ending bytes in binary files, corrupting them
3git config --global core.autocrlf true
4git add image.png  # If misdetected as text → corrupted!
5
6# Fix: use .gitattributes to mark binary files
7*.png binary
8
9# Problem 2: shell scripts with CRLF on Windows
10# autocrlf=true converts to CRLF on checkout
11# But bash requires LF line endings
12#!/bin/bash\r\n   ← fails with "/bin/bash^M: bad interpreter"
13
14# Fix: force LF for scripts
15*.sh text eol=lf

1# Problem 3: inconsistent team settings
2# Developer A: autocrlf=true
3# Developer B: autocrlf=false
4# Result: mixed line endings in the repository, noisy diffs
5
6# Fix: commit a .gitattributes file instead of relying on local config

Checking and Fixing Line Endings

1# Check current setting
2git config --global core.autocrlf
3
4# See line endings in a file
5file myfile.txt
6# myfile.txt: ASCII text, with CRLF line terminators
7
8# Check what Git would store (blob content)
9git show HEAD:myfile.txt | cat -A
10# Hello$           ← LF only ($ marks end of line)
11# Hello^M$         ← CRLF (^M is \r)
12
13# Fix all files in repository after adding .gitattributes
14git rm --cached -r .
15git reset --hard
16# OR (Git 2.16+):
17git add --renormalize .
18git commit -m "Normalize all line endings"

Recommended Configuration

1# For a new project — use .gitattributes (best practice)
2echo "* text=auto" > .gitattributes
3echo "*.sh text eol=lf" >> .gitattributes
4echo "*.bat text eol=crlf" >> .gitattributes
5echo "*.png binary" >> .gitattributes
6git add .gitattributes
7git commit -m "Add .gitattributes for line ending normalization"
8
9# Additionally, set local config as a safety net
10# Windows:
11git config --global core.autocrlf true
12# macOS/Linux:
13git config --global core.autocrlf input

Common Pitfalls

• Using autocrlf=true on Linux/macOS: This converts LF to CRLF on checkout, which breaks shell scripts and Makefiles. Use autocrlf=input on Unix systems, or better yet, rely on .gitattributes and set autocrlf=false.
• Not committing .gitattributes: core.autocrlf is a local setting that varies per developer. Without a committed .gitattributes, new team members get whatever their default is. Always commit .gitattributes to enforce consistent behavior.
• Corrupting binary files: autocrlf=true may modify bytes in binary files that happen to contain 0x0D 0x0A sequences. Mark binary files explicitly in .gitattributes with the binary attribute or -text.
• Forgetting to renormalize after adding .gitattributes: Existing files in the repository keep their old line endings until you run git add --renormalize . and commit. Without this step, old files retain mixed endings.
• Docker and CI environments ignoring local config: Build containers and CI runners often have autocrlf=false by default. If your repository relies on autocrlf=true for correct line endings, scripts may fail in CI. Use .gitattributes with explicit eol=lf for scripts instead of depending on local config.

Summary

• core.autocrlf=true normalizes line endings to LF on commit and converts to CRLF on checkout — designed for Windows
• core.autocrlf=input converts to LF on commit without checkout conversion — designed for macOS/Linux
• .gitattributes is the preferred solution because it is committed to the repository and applies to all developers
• Use * text=auto in .gitattributes for automatic text detection and normalization
• Force eol=lf for shell scripts and eol=crlf for batch files regardless of developer platform
• Run git add --renormalize . after adding .gitattributes to fix existing files in the repository