Git on Windows: What do the crlf settings mean?

I don't understand the complexities related to CrLf settings in git: core.autocrlf, core.safecrlf

I'm developing a cross-platform project in a team and would like both Windows and Linux developers to be able to work together without git marking files as modified just because of line ending style.

What do the various settings mean? What would be the consequences of choosing any of the options? And what would be the best solution for my case?

Yes, I'm aware of this question and the answers there were not insightful, thus not helpful.

The three values for autocrlf:

• true - when content goes into the repository (is committed), its line endings will be converted to LF, and when content comes out of the repository (is checked out), the line endings be converted to CRLF. This is in general meant for clueless windows users/editors. Given the assumption that an editor (or user) is going to create files with CRLF endings, and will freak out if it sees normal LF endings, but that you want LF endings in the repo, this will hopefully cover you. It's possible for things to go awry, though. There are examples of spurious merge conflicts and reports of modified files in the linked questions.

• input - when content goes into the repository, its line endings will be converted to LF, but content is left untouched on the way out. This is basically in the same realm as true, with the assumption that the editors actually can deal with LF endings correctly; you're just guarding against the possibility of accidentally creating a file with CRLF endings.

• false - git doesn't deal with line endings at all. It's up to you. This is what a lot of people recommend. With this setting, if a file's line endings are going to be messed with, you'll have to be aware of it, so merge conflicts are a lot less likely (assuming informed users). Educating developers about how to use their editors/IDEs can pretty much take care of the problem. All of the editors I've seen designed for programmers are capable of dealing with this if configured properly.

Note that autocrlf will not affect content which is already in the repository. If you've committed something with CRLF endings previously, they'll stay that way. This is a very good reason to avoid depending on autocrlf; if one user doesn't have it set, they can get content with CRLF endings into the repo, and it'll stick around. A stronger way to force normalization is with the text attribute; setting it to auto for a given path will mark it for end-of-line normalization, assuming git decides the content is text (not binary).

A related option is safecrlf, which is basically just a way to make sure you don't irreversably perform CRLF conversion on a binary file.

I don't have a ton of experience dealing with Windows issues and git, so feedback about implications/pitfalls is certainly welcome.

I explored 3 possible values for commit and checkout cases and this is the resulting table:

╔═══════════════╦══════════════╦══════════════╦══════════════╗
║ core.autocrlf ║     false    ║     input    ║     true     ║
╠═══════════════╬══════════════╬══════════════╬══════════════╣
║   git commit  ║ LF => LF     ║ LF => LF     ║ LF => LF     ║
║               ║ CR => CR     ║ CR => CR     ║ CR => CR     ║
║               ║ CRLF => CRLF ║ CRLF => LF   ║ CRLF => LF   ║
╠═══════════════╬══════════════╬══════════════╬══════════════╣
║  git checkout ║ LF => LF     ║ LF => LF     ║ LF => CRLF   ║
║               ║ CR => CR     ║ CR => CR     ║ CR => CR     ║
║               ║ CRLF => CRLF ║ CRLF => CRLF ║ CRLF => CRLF ║
╚═══════════════╩══════════════╩══════════════╩══════════════╝

I would recommend to use core.autocrlf = input across all platforms. In this case if Git faces CRLF it will implicitly convert it into LF, and existing files with LF remain as is.

FYI., By default, Line ending in Windows will take CRLF and Linux will take LF. Please find the below table for clear understanding.

╔═══════════════╦══════════════╦══════════════╦══════════════╗
║ core.autocrlf ║    false     ║    input     ║    true      ║
║               ║ Win => Unix  ║ Win => Unix  ║ Win => Unix  ║
╠═══════════════╬══════════════╬══════════════╬══════════════╣
║   git commit  ║ LF => LF     ║ LF => LF     ║ LF => LF     ║
║               ║ CR => CR     ║ CR => CR     ║ CR => CR     ║
║               ║ CRLF => CRLF ║ *CRLF => LF  ║ *CRLF => LF  ║
╠═══════════════╬══════════════╬══════════════╬══════════════╣
║  git checkout ║ LF => LF     ║ LF => LF     ║ *LF => CRLF  ║
║               ║ CR => CR     ║ CR => CR     ║ CR => CR     ║
║               ║ CRLF => CRLF ║ CRLF => CRLF ║ CRLF => CRLF ║
╚═══════════════╩══════════════╩══════════════╩══════════════╝

In the above tabular information, the symbol * highlights the differences between Windows and Unix. At a glance, below is the CLRF information based on the OS platforms:

---

For Windows users

• If windows users working with cross-platform projects, It MUST be core.autocrlf=true for Windows machines and core.autocrlf=input for Unix machines.
• If windows users work with Only Windows projects, It can be both core.autocrlf=true or core.autocrlf=false. But core.autocrlf=input will result in issues in this case.

---

For Unix users (Linux / Mac OS)

• If Unix users working with cross-platform projects, It MUST be core.autocrlf=true for Windows machines and core.autocrlf=input for Unix machines.
• If Unix users work with Only Unix projects, It can be both core.autocrlf=input or core.autocrlf=false. But core.autocrlf=true will result in issues in this case.

---

For same OS users

• For a pure Windows project or pure Unix project, it can be core.autocrlf=false.