Git Line Endings: A Complete Guide to Preventing Cross-Platform Issues

The Problem: Line Ending Chaos

If you’ve ever worked on a project with developers using different operating systems, you’ve likely encountered this frustrating warning:

warning: in the working copy of 'file.ts', LF will be replaced by CRLF the next time Git touches it

This happens because different operating systems use different line ending conventions:

• Windows: CRLF (\r\n)
• Unix/Linux/macOS: LF (\n)
• Classic Mac OS: CR (\r)

When Git tries to reconcile these differences, it can cause unnecessary file changes, merge conflicts, and confusion in your version control history.

Understanding the Issue

The core problem stems from Git’s core.autocrlf setting, which automatically converts line endings. Here’s what’s happening:

1. Windows developers create files with CRLF endings
2. Unix developers create files with LF endings
3. Git tries to “help” by converting between them
4. This creates unnecessary diffs and potential merge conflicts

The Solution: Proper Git Configuration

1. Global Git Configuration

First, configure Git globally based on your operating system:

For Windows users:

git config --global core.autocrlf true
git config --global core.eol lf

For Unix/Linux/macOS users:

git config --global core.autocrlf input
git config --global core.eol lf

2. Project-Level Configuration with .gitattributes

The most robust solution is to create a .gitattributes file in your project root. This file tells Git exactly how to handle different file types:

# Set default behavior to automatically normalize line endings
* text=auto

# Explicitly declare text files you want to always be normalized and converted
# to native line endings on checkout
*.ts text
*.js text
*.json text
*.html text
*.css text
*.scss text
*.md text
*.py text
*.yml text
*.yaml text
*.xml text
*.txt text

# Declare files that will always have CRLF line endings on checkout
*.bat text eol=crlf

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

# Denote all files that are truly binary and should not be modified
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.ico binary
*.mov binary
*.mp4 binary
*.mp3 binary
*.flv binary
*.fla binary
*.swf binary
*.gz binary
*.zip binary
*.7z binary
*.ttf binary
*.eot binary
*.woff binary
*.woff2 binary
*.pyc binary
*.pdf binary

3. Understanding the .gitattributes Syntax

• * text=auto: Automatically detect text files and normalize line endings
• *.ts text: Treat TypeScript files as text and normalize line endings
• *.bat text eol=crlf: Force Windows batch files to use CRLF
• *.sh text eol=lf: Force shell scripts to use LF
• *.png binary: Treat images as binary (no line ending conversion)

Best Practices for Teams

1. Standardize on LF

Most modern development tools and frameworks work best with LF line endings. Even on Windows, using LF is generally preferred because:

• It’s the standard for most programming languages
• It reduces merge conflicts
• It’s more consistent across platforms

2. Configure Your Editor

VS Code:

{
    "files.eol": "\n",
    "files.insertFinalNewline": true,
    "files.trimFinalNewlines": true
}

WebStorm/IntelliJ:

• Go to Settings → Editor → Code Style
• Set “Line separator” to “Unix and OS X (\n)”

3. Pre-commit Hooks

Consider using pre-commit hooks to ensure consistent line endings:

# .git/hooks/pre-commit
#!/bin/sh
# Normalize line endings
git add --renormalize .

Fixing Existing Projects

If you’re dealing with an existing project that has line ending issues:

1. Clean and Re-normalize

# Remove all files from Git's index
git rm --cached -r .

# Re-add all files with normalized line endings
git add .

# Commit the changes
git commit -m "Normalize line endings"

2. Update .gitattributes

Add the .gitattributes file as shown above, then:

# Re-normalize existing files
git add --renormalize .
git commit -m "Add .gitattributes and normalize line endings"

Common Pitfalls to Avoid

1. Don’t mix autocrlf settings across team members
2. Don’t ignore .gitattributes – it’s crucial for consistency
3. Don’t manually edit line endings – let Git handle it
4. Don’t commit binary files as text – use proper binary declarations

Verification

To verify your configuration is working:

# Check your current Git configuration
git config --list | grep -E "(core\.autocrlf|core\.eol)"

# Check line endings in a file
file your-file.ts

# On Unix systems, you can also use:
cat -A your-file.ts  # Shows $ for LF, ^M$ for CRLF

Conclusion

Proper line ending configuration is essential for any cross-platform development team. By using a combination of:

1. Appropriate global Git settings
2. A comprehensive .gitattributes file
3. Consistent editor configurations
4. Team-wide standards

You can eliminate line ending issues and focus on what really matters: building great software.

Remember: Consistency is key. Once you establish these practices, stick to them across all your projects.

---

This guide was created to solve real-world line ending issues in our development workflow. If you’re experiencing similar problems, implementing these solutions should resolve them completely.

Additional Resources

• Git Documentation on Line Endings
• Git Attributes Documentation
• EditorConfig – For consistent coding styles across editors