Git LF vs CRLF: Complete Guide to Line Endings

LF and CRLF are different line ending conventions used across operating systems - LF (Line Feed) is standard on Unix/Linux/macOS, while CRLF (Carriage Return + Line Feed) is used on Windows. The warning “LF will be replaced by CRLF in ” occurs when Git detects inconsistent line endings and is about to convert them based on your core.autocrlf configuration, which you can handle by either accepting the conversion, disabling it, or normalizing all line endings to LF for better cross-platform compatibility.

Contents

• Understanding LF vs CRLF Line Endings
• Why Git Shows the “LF will be replaced by CRLF” Warning
• Git’s core.autocrlf Configuration Explained
• Best Practices for Handling Line Endings
• Step-by-Step Solutions to Line Ending Issues
• Recommended Approach for Cross-Platform Development

Understanding LF vs CRLF Line Endings

LF (Line Feed) and CRLF (Carriage Return + Line Feed) represent different ways to mark the end of a line in text files, with each convention being native to different operating systems:

• LF (\n) - Line Feed only, used by Unix, Linux, and macOS systems
• CRLF (\r\n) - Carriage Return followed by Line Feed, used by Windows systems

These differences exist due to historical reasons. The CRLF format originated from typewriters where the carriage return would move the print head back to the start of the line, and the line feed would advance the paper to the next line. Unix systems simplified this to just Line Feed.

When files are shared across different operating systems, these differences can cause issues. The Git documentation explains that Git can handle this by auto-converting CRLF line endings into LF when you add a file to the index, and vice versa when it checks out code onto your filesystem.

Key Point: The warning you’re seeing indicates that Git has detected a mismatch between the line endings in your files and what your operating system expects.

Why Git Shows the “LF will be replaced by CRLF” Warning

The warning message “LF will be replaced by CRLF in ” appears when Git detects that files in your repository have LF line endings (Unix-style) but your Git configuration is set to convert them to CRLF (Windows-style) for your local working directory.

According to Stack Overflow, this warning says that you (having autocrlf=true) will lose your unix-style LF after commit-checkout cycle. The warning occurs during operations like git add because Git is about to perform line ending conversion.

The warning serves as an important notice that:

1. Git will automatically modify your file line endings
2. The changes won’t be committed yet - they’ll only affect your working directory
3. The original line endings will be preserved in the repository’s database
4. This conversion happens to ensure your editor and tools work correctly on your OS

As explained by Better Stack Community, Git ensures consistent line endings in your repository regardless of the operating system you’re using. This prevents issues like scripts failing due to incorrect line endings.

Git’s core.autocrlf Configuration Explained

The core.autocrlf setting controls how Git handles line ending conversions. This configuration setting determines whether Git automatically converts line endings when you commit or checkout files.

There are three possible values for core.autocrlf:

core.autocrlf = true (Windows default)

• On commit: Converts CRLF to LF
• On checkout: Converts LF to CRLF
• Best for: Windows-only development
• When you see the warning: “LF will be replaced by CRLF”

core.autocrlf = input (Linux/macOS recommended)

• On commit: Converts CRLF to LF
• On checkout: No conversion (keeps LF)
• Best for: Cross-platform development
• When you see the warning: Rare, typically when CRLF files are committed

core.autocrlf = false

• No automatic conversion of line endings
• Best for: Projects that require exact line ending preservation
• When you see the warning: None - Git leaves line endings as-is

The GitHub documentation recommends using core.autocrlf = input for cross-platform projects, as it ensures that all line endings are normalized to LF in the repository while maintaining the correct line endings for each platform during checkout.

Best Practices for Handling Line Endings

When dealing with line ending warnings in Git, consider these best practices:

1. Choose the Right core.autocrlf Setting

For most developers, the optimal configuration depends on your development environment:

• Windows-only teams: Use core.autocrlf = true
• Cross-platform teams: Use core.autocrlf = input on Unix systems
• Mixed environments: Consider using .gitattributes for more control

2. Normalize Line Endings Early

It’s best to decide on a line ending strategy before starting a new project or joining an existing one. Changing line ending configurations mid-project can cause confusion and unnecessary changes in the repository history.

3. Use .gitattributes for Fine Control

For more complex scenarios, you can create a .gitattributes file in your repository to specify how different file types should be handled:

# Set the default behavior, in case people don't have core.autocrlf set.
* text=auto

# Explicitly declare text files you want to always be normalized and converted
# to native line endings on checkout.
*.c text
*.h text
*.cpp text
*.hpp text

# Denote all files that are truly binary and should not be modified.
*.png binary
*.jpg binary

4. Educate Your Team

Ensure all team members understand and use the same line ending strategy to avoid unnecessary conflicts and confusion.

Step-by-Step Solutions to Line Ending Issues

Here are practical solutions to handle the “LF will be replaced by CRLF” warning:

Solution 1: Accept the Conversion (Windows Users)

If you’re working exclusively on Windows and want your files to have Windows-style line endings:

git config --global core.autocrlf true

This will convert LF to CRLF when you checkout files, which is what most Windows editors expect.

Solution 2: Normalize to LF (Cross-Platform)

For cross-platform development, it’s generally recommended to normalize all line endings to LF:

git config --global core.autocrlf input

This ensures that all line endings are stored as LF in the repository while maintaining the correct line endings for your platform during checkout.

Solution 3: Disable Automatic Conversion

If you prefer to handle line endings manually or have specific requirements:

git config --global core.autocrlf false

Solution 4: Convert Existing Files

If you already have files with mixed line endings and want to normalize them:

# Add .gitattributes file first
echo "* text=auto" > .gitattributes
git add .gitattributes

# Normalize all text files to LF
git add --renormalize .
git commit -m "Normalize line endings"

Solution 5: Ignore Specific Files

For binary files or files that should maintain their original line endings:

*.dll binary
*.exe binary
*.jpg binary

Recommended Approach for Cross-Platform Development

For teams working across different operating systems, the following approach provides the best balance of compatibility and consistency:

1. Set global configuration:

   bash

   # On Unix systems (Linux, macOS)
   git config --global core.autocrlf input
   
   # On Windows
   git config --global core.autocrlf true
   

2. Add a .gitattributes file to your repository:

   gitattributes

   # Set the default behavior
   * text=auto
   
   # Denote binary files
   *.png binary
   *.jpg binary
   

3. Normalize existing repositories:

   bash

   git add --renormalize .
   git commit -m "Normalize line endings"
   

4. Educate team members to use the same configuration

This approach ensures that:

• All text files are stored consistently as LF in the repository
• Each developer gets the appropriate line endings for their platform
• Binary files remain untouched
• The repository remains clean and free of unnecessary line ending changes

As Aleksandr Hovhannisyan explains, this strategy prevents issues where scripts might fail due to incorrect line endings and ensures consistent behavior across different development environments.

Sources

1. Git - Git Configuration
2. Configuring Git to handle line endings - GitHub Docs
3. Git replacing LF with CRLF - Stack Overflow
4. CRLF vs. LF: Normalizing Line Endings in Git - Aleksandr Hovhannisyan
5. LF will be replaced by CRLF in Git - What Is That and Is It Important? - Better Stack Community
6. Why should I use core.autocrlf=true in Git? - Stack Overflow
7. How to address ‘warning: LF will be replaced by CRLF in README.md’ - LabEx
8. Git - LF Will Be Replaced by CRLF - Delft Stack

Conclusion

Understanding and properly handling LF vs CRLF line endings is crucial for smooth Git workflows across different operating systems. The “LF will be replaced by CRLF” warning is generally not an error but rather Git’s way of informing you about automatic line ending conversions based on your configuration.

Key takeaways:

• LF is standard on Unix/Linux/macOS, while CRLF is used on Windows
• The warning appears when Git detects line ending mismatches and is about to convert them
• For cross-platform development, use core.autocrlf = input on Unix systems and core.autocrlf = true on Windows
• Consider using .gitattributes for fine-grained control over line ending behavior
• Normalize line endings early in projects to avoid confusion and repository bloat

Recommended action: If you’re working in a cross-platform environment, set your core.autocrlf configuration appropriately and consider adding a .gitattributes file to your repository to ensure consistent line ending handling across all team members.