.gitattributes 推荐内容

.gitattributes 文件是解决你刚才遇到的换行符警告（LF vs CRLF）以及统一项目格式的最佳方案。它允许你针对不同类型的文件定义 Git 应该如何处理它们。

📄 推荐的 .gitattributes 内容

请在你的项目根目录下创建（或编辑）.gitattributes 文件，并粘贴以下内容：

# 1. 默认行为：让 Git 自动检测并处理文本文件
# 这会让 Git 在提交时统一转换为 LF，检出时根据系统转换为 CRLF (Windows) 或 LF (Mac/Linux)
* text=auto

# 2. 强制 Python 项目文件使用 LF 换行符
# 无论操作系统是什么，这些文件在检出时始终使用 LF，避免跨平台脚本报错
*.py text eol=lf
pyproject.toml text eol=lf
uv.lock text eol=lf
requirements.txt text eol=lf

# 3. 强制 Shell 脚本使用 LF
# Shell 脚本在 Windows (CRLF) 下运行通常会报错
*.sh text eol=lf
*.bash text eol=lf

# 4. 二进制文件处理
# 明确告诉 Git 这些是二进制文件，不要尝试转换换行符或进行差异比较
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.ico binary
*.pdf binary
*.zip binary
*.tar.gz binary

---

💡 关键配置解释

* text=auto

这是最重要的通用设置。它告诉 Git：“尽最大努力判断哪些是文本文件，并对其进行换行符标准化。” 这能防止二进制文件（如图片或编译后的 .pyc）被破坏。

text eol=lf

针对你遇到的警告，这是核心解决方案。

• 为什么对 Python 文件这样做？ 虽然 Python 解释器通常能处理 CRLF，但在跨平台协作中，统一使用 LF 是行业标准。
• 效果： 即使你在 Windows 上工作，Git 也会强制将这些文件保存为 LF 格式。这消除了 LF will be replaced by CRLF 的警告，并保证仓库中的内容一致。

binary

对于图片、压缩包等文件，必须设置为 binary。这实际上是 text -diff -merge 的简写，防止 Git 尝试去“修补”二进制文件的内容，否则会导致文件损坏。

---

🚀 如何立即生效

创建或修改 .gitattributes 文件后，Git 不会自动修改现有的文件。你需要运行以下命令来“重新规范化”你的工作区：

1. 添加文件到暂存区

   git add .gitattributes
   

2. 重新规范化所有文件 这个命令会根据 .gitattributes 的新规则，重置工作区中所有文件的换行符。

   git add --renormalize .
   

3. 提交更改

   git commit -m "chore: configure git attributes and normalize line endings"
   

执行完这些步骤后，之前的警告信息应该就会消失，且你的项目将更加规范。