[Bug]: Missing .gitattributes causes confusing CRLF warnings for Windows contributors #950
Description
Describe the Bug
The repository lacks a .gitattributes file, causing constant "LF will be replaced by CRLF" warnings for Windows contributors during normal git operations. This creates confusion during setup and contributes to a poor first-time contributor experience on Windows.
To Reproduce
Steps to reproduce the behavior:
- Clone the repository on a Windows machine
- Make any edit to a markdown or Python file (e.g.,
README.md) - Run
git add README.md - Observe confusing warning messages
- Run
git commit -m "test" - See additional CRLF warnings
Actual output:
warning: in the working copy of 'README.md', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'ENVIRONMENT_SETUP.md', LF will be replaced by CRLF the next time Git touches it
Expected Behavior
- No warnings should appear during normal git operations
- Git should handle line endings automatically and consistently
- Windows contributors should have the same clean experience as Unix/Mac users
- Line endings should be normalized across the repository regardless of platform
Screenshots
Not applicable - this is a console warning issue.
Environment
- OS: Windows 11
- Python version: 3.11.9
- Git version: 2.52.0
- Occurs on: All Windows machines using standard Git configuration
Configuration
Current state: No .gitattributes file exists in repository root.
Expected .gitattributes configuration:
# Auto detect text files and normalize line endings to LF
* text=auto
# Explicitly declare text files
*.md text
*.py text
*.sh text eol=lf
*.js text
*.ts text
*.json text
*.yml text
*.yaml text
*.toml text
# Ensure bash scripts always use LF
*.sh text eol=lf
quickstart.sh text eol=lf
# Windows-specific files use CRLF
*.bat text eol=crlf
*.ps1 text eol=lf
# Binary files
*.png binary
*.jpg binary
*.gif binary
*.pdf binary
*.whl binary
*.pyc binaryLogs
$ git add README.md
warning: in the working copy of 'README.md', LF will be replaced by CRLF the next time Git touches it
$ git add ENVIRONMENT_SETUP.md
warning: in the working copy of 'ENVIRONMENT_SETUP.md', LF will be replaced by CRLF the next time Git touches it
$ git commit -m "docs: fix onboarding references"
warning: in the working copy of 'ENVIRONMENT_SETUP.md', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'README.md', LF will be replaced by CRLF the next time Git touches it
[docs/fix-onboarding-exports-references c903535] docs: fix onboarding references
5 files changed, 39 insertions(+), 37 deletions(-)
These warnings appear on every git add and git commit operation.
Additional Context
Problem Impact
For New Contributors:
- Confusing warnings make them think they're doing something wrong
- Not mentioned in any troubleshooting documentation
- Creates anxiety about breaking the repository
- Adds friction to the contribution process
Technical Issues:
- Inconsistent line endings across platforms
- Potential for spurious diffs from line ending changes
- Shell scripts might fail on Unix systems if CRLF is committed
- Binary files could be corrupted if Git tries to convert them
Solution
Adding a .gitattributes file is:
- Standard practice for cross-platform projects
- One-time fix that helps all future contributors
- No code changes - just configuration
- Prevents line ending issues permanently
References
- Git documentation on gitattributes
- GitHub's gitattributes templates
- Cross-platform line ending best practices
Personal Experience
As a Windows contributor, I encountered these warnings constantly during my first setup and every subsequent commit. They made me worry I was breaking something. After researching, I realized this is a standard cross-platform issue that should be addressed at the repository level with a .gitattributes file.