Git 换行符配置 (LF 模式)

如何在 Windows 环境下统一使用 LF 换行符，配置 .gitattributes、.editorconfig 和编辑器，避免跨平台开发中的换行符问题。

#tech / ops / git #type / howto #status / evergreen #platform / windows

[!info] related notes

前置笔记: git

相关 MOC: git-moc

相关笔记: git-all-files-shown-modified-issue, git-untrack-and-remove-files

Git 换行符配置 (LF 模式)

目标

在 Windows 环境下开发，但统一使用 Linux 风格的 LF 换行符，避免跨平台开发中的换行符问题。

为什么需要统一换行符？

1. CRLF 与 LF 的区别

CRLF（回车+换行）：Windows 系统的换行符（\r\n）
LF（仅换行）：Linux/macOS 的换行符（\n）

2. 不统一换行符的影响

Lint 工具报错：Prettier 或 ESLint 通常配置为要求 LF 换行，不统一会导致格式错误
跨平台执行失败：Shell 脚本（.sh）、Docker 配置文件、Node.js CLI 文件在 Linux 上执行时会报错
Diff 混乱：Git 会认为整个文件的每一行都被修改，导致代码合并困难

3. Windows 中可以使用 LF 模式吗？

完全可以，而且强烈推荐。 现代编辑器和开发工具链都完美支持 LF：

现代编辑器：VS Code、Neovim、甚至 Windows 记事本都原生支持 LF
开发工具链：Node.js、Go、Python、Docker 等都是跨平台设计的，完全兼容 LF
与 WSL 和 Docker 无缝衔接：使用 LF 可以避免”在 Windows 下看着好好的，一进 WSL 跑就报格式错误”的问题

步骤

第一步：添加 .gitattributes 文件（最重要）

在项目根目录创建 .gitattributes 文件：

# 强制所有文本文件在 Git 仓库和本地签出时都使用 LF 换行符
* text=auto eol=lf

# 明确指定某些二进制文件不被 Git 修改
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.ico binary
*.woff binary
*.woff2 binary
*.ttf binary

# 为 Windows 特定文件保留 CRLF（可选）
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf

说明：这个文件提交到仓库后，无论是谁、用什么操作系统拉取代码，Git 都会强制把它当做 LF 处理。

第二步：重新规范化现有的文件

在终端中执行以下命令，让 Git 按照新规则重新处理所有文件的换行符：

# 让 Git 按照新的 .gitattributes 规则重新处理所有文件的换行符
git add --renormalize .

# 提交这次换行符的统一更改
git commit -m "chore: normalize line endings to LF"

执行完这两步，警告就会彻底消失，仓库里的代码也被洗成了纯净的 LF 格式。

第三步：配置编辑器（从源头掐断）

VS Code 配置

在 .vscode/settings.json 中添加：

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

Prettier 配置

在 .prettierrc 或 prettier.config.js 中添加：

{
  "endOfLine": "lf"
}

添加 .editorconfig 文件

在项目根目录创建 .editorconfig 文件，很多编辑器（包括 Neovim、VS Code）都支持或可以通过插件支持它：

root = true

[*]
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
charset = utf-8

[*.md]
trim_trailing_whitespace = false

[*.{js,ts,jsx,tsx,vue}]
indent_style = space
indent_size = 2

[*.{py,rs}]
indent_style = space
indent_size = 4

[*.go]
indent_style = tab
indent_size = 4

验证

检查当前配置

# 查看 Git 配置
git config core.autocrlf

# 查看文件行尾符信息
git ls-files --eol

# 检查特定文件
git diff HEAD -- <file>

检查结果

# 查看警告是否消失
git add .

# 检查文件状态
git status

常见问题

CRLF 换行符警告

问题：warning: in the working copy of 'xxx', CRLF will be replaced by LF the next time Git touches it

原因：Git 发现工作区文件使用的是 Windows 的 CRLF，但它在提交代码存入版本库时会自动替换为 Linux 风格的 LF。

解决方案：按照上述步骤配置 .gitattributes 并重新规范化文件。

所有文件都显示为修改

问题：git status 显示大量文件被”删除”或”修改”

原因：通常是行尾符冲突引起，参见 git-all-files-shown-modified-issue。

解决方案：

# 使用 renormalize 参数重新规范化
git add . --renormalize

# 或者直接添加所有文件
git add .

最佳实践

1. 团队协作规范

团队应统一 Git 配置策略
在项目 README 中说明推荐的 Git 配置
使用 .gitattributes 文件明确行尾符策略

2. 预防措施

创建项目时立即配置 .gitattributes 和 .editorconfig
在 .prettierrc 中配置 "endOfLine": "lf"
定期检查 git status，确保没有换行符警告

3. 跨平台项目配置

# .gitattributes
* text=auto eol=lf

# 为 Windows 特定文件保留 CRLF
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf

# 为 Shell 脚本确保 LF
*.sh text eol=lf

信息参考

官方文档

社区资源

Git MOC

Git 换行符配置 (LF 模式)

目标

为什么需要统一换行符？

1. CRLF 与 LF 的区别

2. 不统一换行符的影响

3. Windows 中可以使用 LF 模式吗？

步骤

第一步：添加 .gitattributes 文件（最重要）

第二步：重新规范化现有的文件

第三步：配置编辑器（从源头掐断）

VS Code 配置

Prettier 配置

添加 .editorconfig 文件

验证

检查当前配置

检查结果

常见问题

CRLF 换行符警告

所有文件都显示为修改

最佳实践

1. 团队协作规范

2. 预防措施

3. 跨平台项目配置

信息参考

官方文档

相关概念

社区资源

Related notes