Git 行尾设置须知

1 背景

远端文件拉取到本地后，会根据本地机器的操作系统、或文件编辑器，修改文件内容的行尾。例如远端代码为适配其代码托管的宿主、存储服务器与编译构建环境，通常采用 LF 作为行尾，符合 Linux 文件系统习惯。而本地为 Windows 的机器则应在获取文件后将行尾从 LF 转换为 CRLF，适配 Windows 文件系统习惯。在本地做完文件修改进行提交，并准备推送回远端，行尾则应从 CRLF 转换回 LF。而本地为 Linux 的机器则无需对行尾做任何转换，始终以 LF 为行尾。

如何使文件的行尾在合适的环境使用合适的格式

• 避免不合适的格式出现在远端，如以 CRLF 行尾的文件推送至服务器。
• 避免行尾因本地环境的不同，而无法达成统一，在远端被反复来回修改。
• 避免行尾的适配转换被识别为常规的变更，影响其他文件内容变更的跟踪。
• 避免文件行尾格式不正确导致无法在特定系统中被执行，如 .bat 需要 CRLF 行尾在 Windows 中执行，.sh 需要 LF 行尾在 Linux 中执行。

这就需要能够自动进行行尾设置的工具来帮忙。恰巧 git / git for windows 内置提供此类设置功能。

2 行尾设置

2.1 通用

在仓库的根目录下使用 .gitattributes 文件设置行尾，此设置将直接影响远端对于文件行尾的应用，从而全局的影响所有从远端拉取文件到本地的开发人员。此处需要单独为 *.bat 和 *.sh 设置其在远端存储时所用的行尾，因为这两类文件的行尾设置会直接影响文件是否能够执行，其他文件则不受影响，如 *.cs 即使使用 LF 行尾仍然能够正常的编译构建。

* text=auto
*.bat text eol=crlf
*.sh text eol=lf

2.2 本地机器为 Windows

每位开发者的本地环境，通过 .gitconfig 文件设置行尾，仅影响的是本地开发环境，需要每位开发者自行配置。可能有其他更为优秀、妥当且不算复杂的方案，可以避免要求每位开发者配置本地环境，但目前对于 Windows 开发者来说，配置本地环境还是最为简单有效的方案。

[core]
	autocrlf = true
	eol = lf

之所以需要设置 core.autocrlf=true，是因为对于 Windows 用户而言，无论文件创建时是 LF 还是 CRLF，都希望拉取到本地时文件能够适配 Windows 而将 LF 的文件自动转换为 CRLF，当然 *.sh 文件除外。

• 而不设置 core.autocrlf 将影响
  • 文件行尾及文件的一致性，导致本地变更和工作树、和索引比较时，出现行尾的变更
  • 无法保障文件可执行性
  • 无法保障文件在本地 Windows 和远端 Linux 能够正常读写，编辑时可能会有编码问题，出现乱码
• 或设置 core.autocrlf=input 所表达的和 * text=auto 理论一致，其会在推送远端时将行尾转换为 LF，从远端拉取到本地时会保持文件创建时的原始行尾。造成本身就是 LF 行尾的文件在本地仍然是 LF，不会转换为 CRLF，影响文件在 Windows 系统中的编辑。

之所以要设置 core.eol=lf，是为了保障仓库内的行尾一致使用 LF，而不是某些文件 LF，某些 CRLF，某些混合。

2.3 本地机器为 Linux / OS X

无需进行 Windows 中所作的配置。

2.4 应用行尾到已经克隆的到本地工作树的仓库

本地工作树可能已经有很多文件出现混合行尾、行尾不正确的情况，此时想要应用新的行尾配置，应当执行行尾变更，推送到远端，并重新克隆。

git add --renormalize .
# 提交推送到远端
# 将远端仓库重新克隆下来的行尾便全部正常

2.5 查看当前本地工作树内文件的行尾

# 查看所有文件
git ls-files --eol
# 查找文件行尾中有混合了 LF 和 CRLF 的文件
git ls-files --eol | findstr mixed
git ls-files --eol | grep mixed



# i 表示 index，可以视作远端行尾
# w 表示 working tree，可以视作本地行尾
### 行尾可能的值有 lf、crlf、mixed，mixed 表示一个文件中行尾既有 lf 又有 crlf，应避免 ###
# attr 表示 .gitattributes 中的行尾设置
# 最后一列是文件名称，即当前执行 git ls-files 指令所在目录下的相对路径
i/lf    w/crlf  attr/text=auto          .gitattributes

3 行为表现

当正确进行了行尾设置后

• 文件拉取到本地做了行尾转换后，git 并不会认为文件产生了变更，在 git 变更中不会出现新的变更记录。
• 对于做出常规变更的文件，git 在将文件与未修改的版本进行比较时，会将本地文件的行尾自动转换为远端所设置的行尾再进行比对，不会将行尾的变更纳入为实际的变更中来。

行尾的变化对用户来说将变得无感。

4 其他注意事项

单独在 .editorconfig 设置，如所有文件类型或 *.cs 文件类型设置行尾为 CRLF，并不能够影响 git 的行为，仍然无法避免 git 将行尾修改识别为常规变更，并且导致 CRLF 行尾的文件被推送到远端，在远端也能够看到行尾的变更。该设置仅能够为 IDE 如 VS 将在保存文件时检查行尾，将行尾不是 CRLF 的设置为 CRLF。

5 参考资料

• CRLF vs. LF: Normalizing Line Endings in Git
• .gitattributes Best Practices
• merge.renormalize
• Configuring Git to handle line endings
• Git – Difference Between HEAD, Working Tree and Index