git版本管理工具中的回车换行转换逻辑

0 Preface/Foreword

0.1 参考文档

gitattributes配置文件的作用_.gitattributes-CSDN博客

1 转换逻辑

在Git版本控制系统 中，core.autocrlf、core.eol和.gitattributes是处理跨平台 换行符（Line Endings）即文件属性的核心机制。Windows使用CRLF（\r\n）作为换行符，二Linux/macOS使用LF（\n），若配置不当，会导致代码审查困难 、合并冲突 或脚本执行错误。

1.1 涉及的相关git变量和git配置文件

• core.autocrlf
• core.eol
• .gitattributes

1.2 core.autocrlf （优先级第二）

core.autocrlf控制提交 和检出双向自动转换逻辑。

++设置的值对应的行为++：

• true :提交转LF，检出转CRLF（适合Windwos本地开发）
• input :提交转LF，检出不转（适合macOS/Linux）
• false: 完全不转换，原样存储和检出。

1.3 core.eol （优先级第三）

core.eol定义工作区检出换行类型。

当且仅当core.autocrlf=false时，core.eol设置的值才能生效。

core.eol可设置的值为：

• lf: 工作区强制为LF。
• crlf: 工作区强制为CRLF。
• native: 工作区（工作路径）使用操作系统默认换行符。

1.4 .gitattributes文件（优先级第一）

.gitattributes ：是++基于路径++ 的文件属性定义 ，是一个版本控制文件（需要提交到仓库中）；允许开发者对特定文件类型或路径定义属性；能够解决团队协作中换行符不一致问题的最佳实践（Best practice），可以覆盖个人的本地配置（core.autocrlf和core.eol），确保所有协作者的行为一致。

++该文件的主要功能如下++：

• 统一换行符处理：明确指定哪些文件是文本，哪些是二级制，以及文本文件应使用哪种换行符。
• 自定义差异比较：高数git如何对非文本文件（例如pdf等）进行diff比较。
• 识别二进制文件：防止Git对二进制文件（图片、编译生成文件、特定配置文件）进行错误的文本合并或换行转换。

++常用的属性设置如表格++：

|----------------------|----------------------------------------------------------|
| 属性设置 | 含义与作用 |
| * text=auto | 推荐默认设置。让Git自动检测文件是否为文本。如果是文本，提交时规范化为LF，检出时根据系统或配置转换。 |
| *.cpp text | 强制将.cpp文件当做文本文件，并进行换行符规范化。 |
| *.sh text eol=lf | .sh文件视为文本文件，并始终在检出时转换为LF。防止在Windwos系统上因检出时含有\r导致脚本无法运行。 |
| *.bat text eol=crlf | .bash文件视为文本文件，并始终在检出时转换为CRLF。Windows系统中批处理文件。 |
| *.png binary | 二进制文件申明，避免文件合并混乱。 |
[常用的属性设置]

在配置/设置.gitattributes文件时，要主要不同文件类型的设置，可以参考下面的模版：

# Cross-platform line-ending / binary safety.
#
# Windows git defaults to core.autocrlf=true. Without the rules below, git's
# text-vs-binary heuristic is the only thing protecting binary assets from EOL
# conversion --- which silently corrupts fonts/images on Windows checkouts. Pin it
# explicitly so a clone is byte-identical on every platform.

# Default: auto-detect binary, and force LF for everything detected as text.
#
# The `eol=lf` is load-bearing: bare `text=auto` means "convert to NATIVE on
# checkout", so on Windows every text file with no explicit rule below (SConscript,
# SConstruct, Kconfig*, proj.conf, board.conf, Doxyfile, .ini, ...) lands as CRLF.
# Several of our sdk_patches diffs target SConscript files, and an LF patch
# will not apply to a CRLF working file. Only *.bat / *.ps1 below opt back in.
* text=auto eol=lf

# Source / config --- force LF so shell scripts stay runnable under WSL & git-bash
# and C/Python sources don't churn between platforms.
*.sh    text eol=lf
*.py    text eol=lf
*.c     text eol=lf
*.h     text eol=lf
*.cpp   text eol=lf
*.lds   text eol=lf
*.sct   text eol=lf
*.json  text eol=lf
*.md    text eol=lf
*.patch text eol=lf

# Windows-native scripts --- keep CRLF.
*.bat   text eol=crlf
*.ps1   text eol=crlf

# Binary assets --- NEVER apply text/EOL conversion (this is the fonts fix).
*.ttf   binary
*.otf   binary
*.ttc   binary
*.ezip  binary
*.agif  binary
*.gif   binary
*.png   binary
*.jpg   binary
*.jpeg  binary
*.bmp   binary
*.bin   binary
*.img   binary
*.hex   binary
*.elf   binary
*.lib   binary
*.a     binary
*.o     binary
*.so    binary
*.dll   binary
*.exe   binary
*.cer   binary
*.der   binary
*.pdf   binary
*.zip   binary

1.5 仓库行尾符的标准化

不管是GitLab还是GitHub，仓库（索引）中文本文件 的的行尾符为LF。