Collaborating on coding projects across different operating systems can lead to frustrating inconsistencies with line endings. Windows, macOS, and Linux each have their own conventions for marking the end of a line, which can cause havoc when merging code. Thankfully, Git offers a powerful tool to manage these differences: core.autocrlf. Understanding this setting is crucial for smooth, cross-platform development workflows.

What is core.autocrlf?

The core.autocrlf setting in Git controls how line endings are handled when committing and checking out files. It acts as a translator between the different line ending conventions used by various operating systems. This setting prevents mixed line endings within your repository, ensuring consistent code across platforms and avoiding unexpected merge conflicts.

This setting takes different values depending on your operating system. For Windows, setting core.autocrlf to true ensures that when you check out code, line endings are converted to CRLF (Carriage Return and Line Feed), the Windows standard. When committing code, LF (Line Feed) is used, maintaining consistency within the repository. This automatic conversion prevents issues arising from mixed line endings.

On macOS and Linux, setting core.autocrlf to input converts CRLF to LF on commit, ensuring the repository uses Unix-style line endings. It doesn’t perform any conversion on checkout. A value of false disables any line ending conversion, useful when cross-platform compatibility isn’t a primary concern.

Setting core.autocrlf on Different Operating Systems

To configure core.autocrlf, use the following commands in your Git terminal:

• Windows: git config --global core.autocrlf true
• macOS/Linux: git config --global core.autocrlf input
• Disable conversion: git config --global core.autocrlf false

Setting the configuration globally applies it to all your Git repositories. You can also set it locally within a specific repository by omitting the --global flag. This allows you to tailor the setting to the specific needs of a project.

Choosing the correct setting is crucial for preventing line ending issues. For instance, setting core.autocrlf to true on macOS can lead to files having CRLF endings within the repository, which is generally not recommended.

How core.autocrlf Prevents Merge Conflicts

Imagine a scenario where a Windows developer and a macOS developer are working on the same project. Without core.autocrlf, the Windows developer would introduce CRLF line endings, while the macOS developer would use LF. This difference would lead to Git flagging almost every line as changed during merges, creating unnecessary conflicts.

By using the appropriate core.autocrlf setting, these inconsistencies are handled automatically. This prevents spurious merge conflicts, saving developers time and frustration, and promoting smoother collaboration.

A consistent approach to line endings contributes significantly to a cleaner Git history, making it easier to track changes and understand the evolution of the codebase. This becomes especially valuable in larger projects with multiple contributors.

Best Practices and Troubleshooting

While core.autocrlf largely automates line ending management, understanding its behavior and potential pitfalls is essential. Here are some best practices:

1. Consistency is Key: Ensure all developers on a project use the appropriate core.autocrlf setting for their operating system.
2. .gitattributes File: For fine-grained control, use a .gitattributes file. This file allows you to specify line ending rules for individual files or file types, overriding the global or local core.autocrlf setting. This is particularly useful for managing files that require specific line ending conventions, regardless of the platform.
3. Regularly Check Configuration: Periodically verify your core.autocrlf setting using git config --get core.autocrlf.

If you encounter line ending issues, tools like dos2unix and unix2dos can help convert line endings in existing files. However, addressing the root cause through proper core.autocrlf configuration is the preferred long-term solution. Learn more about effectively managing text files.

FAQ

Q: What happens if I set core.autocrlf to false on Windows?

A: Git won’t perform any line ending conversions. Your repository will store files with the line endings used by your operating system, which might lead to inconsistencies if collaborating with developers on other platforms.

Managing line endings effectively is a cornerstone of smooth cross-platform development. By correctly configuring and utilizing core.autocrlf, you can prevent frustrating merge conflicts and maintain a clean, consistent codebase. Leveraging the power of Git’s features, such as .gitattributes, offers even greater control over line ending behavior. Explore further resources on Git configuration and best practices to maximize your development workflow efficiency and collaboration effectiveness. Dive deeper into specific use cases and explore related tools like dos2unix and managing line endings on Stack Overflow.

Learn more about related Git functionalities and best practices at Git’s official documentation.

Question & Answer :
I’ve read a lot of different questions and answers on Stack Overflow as well as git documentation on how the core.autocrlf setting works.

This is my understanding from what I’ve read:

Unix and Mac OSX (pre-OSX uses CR) clients use LF line endings.
Windows clients use CRLF line endings.

When core.autocrlf is set to true on the client, the git repository always stores files in LF line ending format and line endings in files on the client are converted back and forth on check out / commit for clients (i.e. Windows) that use non-LF line endings, no matter what format the line endings files are on the client (this disagrees with Tim Clem’s definition - see update below).

Here is a matrix that tries to document the same for the ‘input’ and ‘false’ settings of core.autocrlf with question marks where I’m not sure of line ending conversion behavior.

My questions are:

1. What should the question marks be?
2. Is this matrix correct for the “non-question marks”?

I’ll update the question marks from the answers as consensus appears to be formed.

core.autocrlf value true input false ---------------------------------------------------------- commit | convert ? ? new | to LF (convert to LF?) (no conversion?) commit | convert to ? no existing | LF (convert to LF?) conversion checkout | convert to ? no existing | CRLF (no conversion?) conversion 

I’m not really looking for opinions on the pros and cons of the various settings. I’m just looking for data which makes it clear how to expect git to operate with each of the three settings.

--

Update 04/17/2012: After reading the article by Tim Clem linked by JJD in the comments, I have modified some of the values in the “unknown” values in the table above, as well as changing “checkout existing | true to convert to CRLF instead of convert to client”. Here are the definitions he gives, which are more clear than anything I’ve seen elsewhere:

core.autocrlf = false

This is the default, but most people are encouraged to change this immediately. The result of using false is that Git doesn’t ever mess with line endings on your file. You can check in files with LF or CRLF or CR or some random mix of those three and Git does not care. This can make diffs harder to read and merges more difficult. Most people working in a Unix/Linux world use this value because they don’t have CRLF problems and they don’t need Git to be doing extra work whenever files are written to the object database or written out into the working directory.

core.autocrlf = true

This means that Git will process all text files and make sure that CRLF is replaced with LF when writing that file to the object database and turn all LF back into CRLF when writing out into the working directory. This is the recommended setting on Windows because it ensures that your repository can be used on other platforms while retaining CRLF in your working directory.

core.autocrlf = input

This means that Git will process all text files and make sure that CRLF is replaced with LF when writing that file to the object database. It will not, however, do the reverse. When you read files back out of the object database and write them into the working directory they will still have LFs to denote the end of line. This setting is generally used on Unix/Linux/OS X to prevent CRLFs from getting written into the repository. The idea being that if you pasted code from a web browser and accidentally got CRLFs into one of your files, Git would make sure they were replaced with LFs when you wrote to the object database.

Tim’s article is excellent, the only thing I can think of that is missing is that he assumes the repository is in LF format, which is not necessarily true, especially for Windows only projects.

Comparing Tim’s article to the highest voted answer to date by jmlane shows perfect agreement on the true and input settings and disagreement on the false setting.

The best explanation of how core.autocrlf works is found on the gitattributes man page, in the text attribute section.

This is how core.autocrlf appears to work currently (or at least since v1.7.2 from what I am aware):

• core.autocrlf = true

1. Text files checked-out from the repository that have only LF characters are normalized to CRLF in your working tree; files that contain CRLF in the repository will not be touched
2. Text files that have only LF characters in the repository, are normalized from CRLF to LF when committed back to the repository. Files that contain CRLF in the repository will be committed untouched.

• core.autocrlf = input

1. Text files checked-out from the repository will keep original EOL characters in your working tree.
2. Text files in your working tree with CRLF characters are normalized to LF when committed back to the repository.

• core.autocrlf = false

1. core.eol dictates EOL characters in the text files of your working tree.
2. core.eol = native by default, which means working tree EOLs will depend on where git is running: CRLF on a Windows machine, or LF in *nix.
3. Repository gitattributes settings determines EOL character normalization for commits to the repository (default is normalization to LF characters).

I’ve only just recently researched this issue and I also find the situation to be very convoluted. The core.eol setting definitely helped clarify how EOL characters are handled by git.