当前位置：首页 > news >正文

gitattributes配置文件的作用

news 2025/7/6 3:19:50

0 Preface/Foreword

0.1 基本概念

Git版本管控工具功能强大，在使用过程中，在多人合作的项目开发过程中，经常会遇到提交代码时出现的warning提醒，尤其是换行符。

Linux/Unix/Mac OS操作系统的换行符使用LF符号（\n），而Windows使用CR（\r）LF（\n）作为换行符。

CR：Carriage Return，回车，ASCII码0x0D，Ctrl为 ^M

LF：Line Feed，换行，ASCII码0x0A，Ctrl为^J

影响换行符的几个因素：

操作系统（平台）
编辑器（尤其是Windows平台下的编辑器）
core.autocrlf 变量设置， true, false, input

core.autocrlf不同值的作用：

true，最终提交到代码库中时，所有文件都认为是text，把所有CRLF转成LF。checkout时，全都转为CRLF；（git add的过程中，会强制将LF转成CRLF; git commit时，强制将CRLF 转成LF）（推荐在Windows中使用，适合多平台协作）
false，最终提交到代码库中时，保持原来text内容。CRLF还是CRLF，LF还是LF。（适合纯Windows）
input，最终提交到代码库中时，所有CRLF转成LF。checkout时，保持LF或者CRLF（不转换）。（推荐在Linux/Unix下使用，适合纯Linux/Mac OS）

core.safecrlf不同值的作用：

true，若有mixed line endings，无法提交，fatal错误
false，允许提交包含混合line endings的文件
warn，只是警告，仍然可以提交

core.eol的值类型：当且仅当core.autocrlf为false时，core.eol设置才有效

lf
crlf
native，根据平台，自动转换

Git版本管控的几个区域：

工作区， working directory，检出（git checkout <branch>）到对应的分支
暂存区，stage/index，通过git add 添加修改过的文件，git add的动作就是将文件修改放入到了暂存区
本地版本库，commit history, 通过git commit动作，提交成功后，对应的文件会放入版本库中
远程版本库，通过git push动作，将本地版本库更新到远程库

0.2 git 变量查看和设置

0.2.1 查看autocrlf

git config core.autocrlf

0.2.2 查看safecrlf

git config core.safecrlf

0.2.3 查看eol

git config core.eol

1 Usage

使用方法可参考文章：

Configuring Git to handle line endings - GitHub Docs

[转载]通过阅读 git-config 文档理解 Git 如何使用autocrlf、safecrlf、eol和.gitattributes处理line-ending - 简书

Git提示“warning: LF will be replaced by CRLF”最详细解释+解决方案-CSDN博客

git如何避免”warning: LF will be replaced by CRLF“提示？ - 知乎

https://docs.github.com/zh/get-started/getting-started-with-git/configuring-git-to-handle-line-endings?platform=windows

.gitattributes 作用详细讲解（git大佬必会技能) - 代码先锋网

1.1 Warning

warning: LF will be replaced by CRLF in xxx file

The file will have its origninal line endings in your working directory.

1.2 添加.gitattributes文件

.gitattributes中的内容会覆盖 core.autocrlf的设置，大多数情况下使用配置文件来设置不同文件的line endings。

除了用命令行设置core.autocrlf，还可以用.gitattributes文件管理Git读取特定存储中的行结束符的方式。该文件提交到存储库时，它将覆盖所有存储库贡献者的core.autocrlf设置。可以确保所有用户的行为一致，而不管其他Git设置和环境如何。

# Set the default behavior, in case people don't have core.autocrlf set.
* text=auto
#文件的行尾自动转换。如果是文本文件，文件入Git库时，行尾自动转为LF。若在库中的文件行尾是CRLF，则文件在入库时，不再转为LF。# Explicitly declare text files you want to always be normalized and converted
# to native line endings on checkout.
*.c text
*.h text
#对于txt文件，标记为文本文件，并进行行尾规范化。# Declare files that will always have CRLF line endings on checkout
*.uvprojx text eol=lf
#对于.uvprojx标记为文本文件，在文件入库时进行规范化，行尾转成LF；检出是也保持LF。#Explicitly declare files you want to always be normalized and converted
# to LF line endings on checkout
*.py eol=lf
#对于py文件，只针对工作目录中的文件，行尾设置为LF#Denote all files that are truly binary and should not be modified.

*.bin binary

*.jpg binary

#对于.bin 和 .jpg文件，表示二级制文件，检出是不修改

NOTE：可以发现，文件是匹配的，用*.c、*.uvprojx、*.bin（用空格分隔），然后给定一个设置，即为text、text eof=lf、binary。

text=auto Git将以其认为的最佳方式处理文件。这是一个合适的默认选项。
在检出时 text eol=lf Git将始终把行结束符转换为LF，该场景用于必须保持LF结束符的文件，即使在Windows上。
在检出时text eol=crlf Git将始终把行结束符转换为CRLF，该场景用于必须保持CRLF结束符文件，即使在Linux或OSX上。
binary Git会理解指定文件不是文本，并且不应尝试更改该文件。该binary设置也是-text -diff的别名

更改行结束符后刷新仓库注意事项如下：

当.gitattributes文件已经提交到代码库中时，为了让该文件可以在所有开发者本地工作路径都能生效，可以根据以下动作进行：

在本地拉取最新代码，git pull
git rm --cached -rf
git reset --hard HEAD

1.2.1 .gitattributes介绍

.gitattributes是一个文本文件，文件中的一行定义一个路径的若干个属性，主要目的是用来定义每种文件的属性，方便git帮助统一管理。

.gitattributes文件格式：

需要匹配的文件模式属性1 属性2 ...

在该文件每一行中，一个属性（以text为例）可能有4种状态：

设置 text
不设置 -text
设置值 text=auto
未声明，通常不出现该属性即可；但是为了覆盖其他文件中的声明，也可以用 !text

.gitattributes中可以定义的属性包括（持续更新中）：

text，用于控制line endings的规范性。如果一个文本文件是规范的，则Git库汇总该文件（Git服务器中的文件）的行尾总是LF。
eol，设置行尾字符，eol=lf，入库时将行尾规范为LF，检出时行尾为LF； eol=crlf，入库时行尾规范为LF，检出时将行尾设置为CRLF
diff，告诉git声明文件需要比较版本差异
binary，二进制文件
merge，合并策略

diff属性：

diff状态描述如下：

diff 强制视为文本文件，即使包含一些通常从不出现在文本文件的字节值，比如NULL
!diff 表示为非文本文件
未定义

1.2.2 .gitattributes生效顺序

生效顺序如下：

项目中有多个.gitattributes文件情况，远离根目录的文件优先级越高（生效）。
同一个.gitattributes文件情况，遵循覆盖原则，后面的行会覆盖前面的设置，如果一个文件的某个属性被多次设置，则后设置的优先。

1.2.3 text 和eol的区别

参考文献：git - What does "!eol" in gitattributes do? - Stack Overflow

Git有两个属性处理行尾。（Git has 2 attributes that deal with end-of-lines）

Text：

Documentation says:

This attribute enables and controls end-of-line normalization.When a text file is normalized, its line endings are converted to LF in the repository.

This effectively means that when you commit to the repo, it will convert line-endings to LF.

eol：

Documentation says:

This attribute sets a specific line-endings style to be used in the working directory. It enables end-of-line normalization without any content checks, effectively setting the text attribute.

So while the text attribute affects how the file will look like IN THE REPO, eol affects how the file looks like in the working directory.

An attribute can have 4 states:

text，set with no value
-text，unset
text=auto，set with specific value, this setting means you let Git decide if a file is text and if it is it will normalize it (set line-endings in the repo to LF)
!text，unspecified

!eol：

!eof means that the attribute eol is set to unspecified explicitly, in this case it is the same as not specifying it at all, instructing Git to look at the core.autocrlf and core.eol configuration settings to see how to deal with line-endings in the working directory. Note this :

The core.eol configuration variable controls which line endings Git will use for normalized files in your working directory; the default is to use the native line ending for your platform, or CRLF is core.autocrlf is set.

1.3 常用template(.gitattributes)

# Help git with file types
* text=auto
*.o binary
*.obj binary
*.bin binary
*.lib binary
*.mbn binary
*.svf binary

# Always use LF EOL on shell script files, otherwise Docker cannot run scripts
# in a folder mapped from Windows into the Docker container.
*.sh eol=lf

# Documentation files are often changed in multiple concurrent branches.
# Use git union strategy when merging, so it keeps both side's modifications
# without conflicts.
README.md merge=union
CHANGELOG.md merge=union
RELEASENOTES.md merge=union