打开一个 GitHub 仓库，看到根目录有 `.gitattributes`，很容易把它当成又一份配置文件，顺手略过。可是在 Windows 上修改脚本后，`git diff` 突然显示整份文件都变了；或者仓库明明以 TypeScript 为主，GitHub 的语言统计却显示大半是 JavaScript；又或者刚克隆的设计资源只剩下几行指针文字。这些看似没有关联的现象，都可能与 `.gitattributes` 有关。

它的作用可以从文件进入和离开 Git 的过程理解。我们在工作目录里编辑文件，执行 `git add` 时，Git 把内容放入暂存区；切换分支或克隆仓库时，Git 又把仓库中的内容写回工作目录。除此以外，Git 还需要决定怎样展示差异、怎样合并冲突、怎样制作源码归档。`.gitattributes` 允许仓库按文件路径指定这些行为。GitHub 和 Git LFS 等工具也会读取其中与自身有关的属性。

`.gitattributes` 通常是普通文本文件，并且会随代码一起提交。最简形式是一行路径匹配规则，后面跟着一个或多个属性。

```gitattributes
* text=auto
*.sh text eol=lf
*.bat text eol=crlf
*.png -text
```

这四行并不是给文件贴上供人阅读的备注。第一行让 Git 自动判断文件是否适合按文本处理。第二行要求 Shell 脚本作为文本处理，并在工作目录中使用 `LF` 行尾。第三行让 Windows 批处理文件在工作目录中使用 `CRLF`。第四行禁止对 PNG 文件进行文本行尾转换。Git 会根据实际匹配到的路径应用相应规则。

这与 `.gitignore` 有明确分工。`.gitignore` 处理的是文件是否应当被 Git 当作未跟踪文件发现，常用来排除本地缓存、构建产物和私密配置。`.gitattributes` 处理的是匹配路径上的文件应如何参与 Git 操作。把 `*.log -text` 写进 `.gitattributes`，不会使日志文件自动消失在 `git status` 中；要忽略未跟踪的日志，仍需使用 `.gitignore`。反过来，一个已经被 Git 跟踪的文件，也不会因为后来写入 `.gitignore` 就自动退出版本历史。

最常见的用途是管理行尾。Windows 环境常见 `CRLF`，Unix 类环境通常使用 `LF`。两者在编辑器里可能看起来完全一样，在字节层面却不同。当一个文件的每一行都由 `LF` 变成 `CRLF`，Git 可能把整份文件显示为改动。代码审查者原本只需要检查三行逻辑，现在面对的是几千行差异；真正的业务修改被淹没，合并冲突也更难判断。

`text` 属性控制 Git 是否对文件做行尾规范化。文件作为文本加入暂存区时，Git 可以把行尾规范化为 `LF`。`eol` 属性则进一步指定检出到工作目录后的行尾形式。因此，同一份被规范化的仓库内容，在不同工作环境中可以有不同的工作目录表现。仓库内部存放什么、编辑器打开时看到什么，需要分开理解。`* text=auto` 让 Git 判断文本与二进制；`*.sh text eol=lf` 则把脚本的要求明确写下来，避免平台设置使脚本拿到不合适的行尾。详细行为还会受到 Git 配置及文件原有内容影响，不能只凭操作系统名称推断结果。

这里有一个很具体的工程场景。一个团队同时维护 Windows 开发机上的批处理脚本，以及在 Linux 容器里执行的 Shell 脚本。仓库可以把两类文件的工作目录行尾分别固定为 `CRLF` 与 `LF`。开发机仍可以使用各自熟悉的编辑器，容器执行的脚本也不必依赖某位成员恰好把本机 `core.autocrlf` 配成了某个值。这是仓库级规则的价值，团队共用的文件约定跟着仓库走。

但给一个已有多年历史的项目补上行尾规则时，不宜以为提交 `.gitattributes` 就完成了旧文件转换。属性会影响后续处理，过去已经进入仓库的内容未必立即变成期望形式。Git 官方文档给出的做法包括在工作目录干净的前提下运行 `git add --renormalize .`，检查 `git status` 和暂存差异，再单独提交规范化结果。这个提交可能触及大量文件，应与业务逻辑修改分开，便于审查，也便于日后追溯。尤其要检查压缩包、图片和其他不该被文本规范化的文件有没有意外进入变更清单。

二进制文件也经常出现在 `.gitattributes` 中。面对 PNG、PDF 或设计源文件，逐行比较通常没有意义。`-diff` 告诉 Git 不要为匹配文件生成普通文本差异。例如，`*.pdf -diff` 可以避免把 PDF 字节误当作可读文本展示。不过，`-diff` 只影响差异展示，不能使文件免于版本跟踪，也不会自动把它送入 Git LFS。`-text` 管的是行尾转换，`-diff` 管的是差异呈现；虽然二者可能同时用于同一种文件，作用并不相同。

有些格式虽然表面上是文本，逐行差异仍可能很吵。压缩成一行的 JavaScript 文件就是一例。修改一个字符，整行都可能被标记为变化。此时团队可以决定是否将生成文件标记为生成内容，改善 GitHub 上的审查体验；也可以在本地配置特定的 `diff` 驱动，按照适合该格式的方式展示差异。`.gitattributes` 负责把路径关联到某个驱动，驱动执行什么命令通常还需要 Git 配置。光写一个驱动名称，不会凭空安装转换程序。

合并行为也是它可以控制的范围。普通文本通常适合 Git 的三方合并，因为行与行之间存在可比较的关系。二进制设计文件则不同，两个分支各自修改同一个文件时，Git 无法像处理源代码那样安全地拼接内容。可以为某些路径指定合并属性，让 Git 保留待人工解决的冲突。这里需要警惕一种看起来很省事的设置，`merge=union` 会尝试保留两边的文本行，但保留双方内容不等于得到有效结果。一个依赖顺序的配置文件，即使所有行都留下，也可能出现重复键、错误顺序或互相矛盾的设置。Git 官方文档同样提醒，使用这种合并方式后必须核查结果。

除了工作目录和合并过程，`.gitattributes` 还可以影响源码归档。`export-ignore` 告诉 `git archive` 不把匹配的文件放进生成的归档。假设我们的仓库既有应用源码，也有只供开发时使用的测试夹具，发布源码包时可能希望排除后者。可以写入相应规则，让归档命令按此处理。需要留意作用边界，`export-ignore` 不会删除仓库里的文件，也不控制日常克隆；不同平台提供的下载压缩包是否完全采用同一套归档处理方式，应依据该平台的文档和实际生成结果确认。

另一个常见场景是 Git LFS。我们执行 `git lfs track` 关联某类大文件时，工具通常会修改 `.gitattributes`。例如，针对 PSD 设计源文件，规则可能是这样。

```gitattributes
*.psd filter=lfs diff=lfs merge=lfs -text
```

这行配置让 Git LFS 的过滤器参与文件加入与检出的过程。仓库中的 Git 对象通常保存一个指向实际大文件的指针，实际内容由 LFS 机制另行管理。只把这行文字手工复制到仓库，并不能替代安装和配置 Git LFS，更不能把已经存在于普通 Git 历史里的大文件自动迁走。迁移已有文件，需要按 Git LFS 的流程处理并检查历史影响。团队还应提交 `.gitattributes`，这样新克隆仓库的成员才能获得相同的文件关联规则。

这里牵涉到 `.gitattributes` 较深的一层能力，`filter`。过滤器可以在内容进入 Git 时运行 `clean` 处理，在内容从 Git 写回工作目录时运行 `smudge` 处理。Git LFS 利用这种机制，让仓库中的表示形式与工作目录里的可用文件不同。自定义过滤器同样可以做内容转换，但共享仓库时必须考虑其他成员是否安装了对应工具、转换是否可以稳定往返，以及过滤器失败时会发生什么。若转换是文件可用的前提，配置错误造成的影响就不只是差异显示难看，而可能是检出后拿不到预期内容。

编码问题也有专门属性。某些历史系统仍使用 `UTF-16` 等编码保存文件，Git 的文本检测和差异展示可能无法像处理 `UTF-8` 文件那样自然。`working-tree-encoding` 可以指定工作目录中的编码，让支持这一属性的 Git 客户端在加入与检出时转换内容。这个功能应当审慎采用。团队若混用较旧的 Git 或其他 Git 实现，客户端支持情况可能不同；某些编码还存在往返转换风险。能够统一保存为 `UTF-8` 的项目，通常没有必要为了展示差异而引入额外的编码转换链。

在 GitHub 页面上，`.gitattributes` 还有一组容易让人误解的用途。GitHub 使用 Linguist 分析仓库文件，决定语言统计和部分文件的显示方式。假设一个以 TypeScript 编写的前端项目，把构建后的 JavaScript 文件也提交到了 `dist` 目录。若构建结果体积很大，仓库首页的语言比例可能更像 JavaScript 项目，代码审查页也可能充满生成文件的差异。团队可以用下面的属性表达这些文件的身份。

```gitattributes
dist/** linguist-generated
vendor/** linguist-vendored
```

`linguist-generated` 可以让 GitHub 将对应文件视为生成内容，在语言统计中排除，并在差异页面默认折叠。`linguist-vendored` 用于标识引入的第三方代码，使其不计入仓库语言统计。若某个文件被错误识别为另一种编程语言，Linguist 也支持用 `linguist-language` 明确指定。它们属于 GitHub 的 Linguist 所理解的属性，不能据此推断本地 Git 会停止跟踪文件，或者构建系统会停止生成它们。GitHub 的语言统计变化，也不代表实际源码发生了转换。

读规则时还要留心匹配范围。`.gitattributes` 可以放在仓库根目录，也可以放在子目录。子目录里的规则可以针对更局部的路径；多个规则同时匹配时，后面的规则可能覆盖前面的相同属性，更具体位置的属性文件也有相应优先级。它的路径匹配形式与 `.gitignore` 接近，却不能机械照搬全部写法。尤其是仅写一个目录名并不等于递归匹配目录内所有文件，表达目录树通常要使用类似 `dist/**` 的形式；用于忽略规则的否定模式也不适用于属性规则。判断一条规则是否生效，最好直接让 Git 查询，而不是只凭目测通配符。

```bash
git check-attr --all -- scripts/deploy.sh
git check-attr text eol -- scripts/deploy.sh
git ls-files --eol -- scripts/deploy.sh
```

前两条命令查看某个路径实际获得了哪些属性。第三条查看 Git 对已跟踪文件的行尾判断，包括暂存区、工作目录以及属性信息。假如脚本明明配置了 `eol=lf`，却仍出现大面积行尾变动，这几项输出能帮助定位问题，是规则没匹配到、旧内容尚未规范化，还是工作目录的当前内容需要重新检出。对于 GitHub 的 Linguist 效果，除了检查本地属性，还需确认 `.gitattributes` 已提交，因为仓库网页读取的是已提交的版本。

把这些用法放在一起看，就能理解 `.gitattributes` 为什么值得进入代码审查。它虽只有几行，却可能改变文件加入暂存区时的字节表示、检出后的行尾、合并冲突的处理、差异页面的可读性，以及大文件的存储流程。审查一条新规则时，我们应检查它匹配哪些现有文件，会不会使旧内容需要重新规范化，其他成员是否拥有所需的过滤器，以及 GitHub 页面上的变化是否只是显示层面的变化。

因此，在陌生仓库里看到 `.gitattributes`，最有效的阅读方法不是逐行背属性名称，而是拿一个具体文件问几件事，它会不会被跟踪，进入仓库时内容是否会转换，检出后是什么形式，发生冲突时怎样合并，差异页怎样显示。如果规则里出现 `filter=lfs`，还要确认实际大文件能否通过 Git LFS 取得。沿着文件的这条路径看下去，`.gitattributes` 就不再是一份神秘的隐藏文件，而是团队共同维护的文件处理约定。

## 参考资料

[Git 官方文档，gitattributes](https://git-scm.com/docs/gitattributes)

[Git 官方文档，git check-attr](https://git-scm.com/docs/git-check-attr)

[Git 官方文档，git ls-files](https://git-scm.com/docs/git-ls-files)

[GitHub 文档，自定义变更文件的显示方式](https://docs.github.com/en/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github)

[GitHub 文档，配置 Git Large File Storage](https://docs.github.com/en/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage)

[GitHub Linguist 文档，属性覆盖规则](https://github.com/github-linguist/linguist/blob/main/docs/overrides.md)

打开一个 GitHub 仓库，看到根目录有 .gitattributes，很容易把它当成又一份配置文件，顺手略过。可是在 Windows 上修改脚本后，git diff 突然显示整份文件都变了；或者仓库明明以 TypeScript 为主，GitHub 的语言统计却显示大半是 JavaScript；又或者刚克隆的设计资源只剩下几行指针文字。这些看似没有关联的现象，都可能与 .gitattributes 有关。

Git 仓库里的 .gitattributes，一份决定文件如何被处理的规则表

打开一个 GitHub 仓库，看到根目录有 .gitattributes，很容易把它当成又一份配置文件，顺手略过。可是在 Windows 上修改脚本后，git diff 突然显示整份文件都变了；或者仓库明明以 TypeScript 为主，GitHub 的语言统计却显示大半是 JavaScript；又或者刚克隆的设计资源只剩下几行指针文字。这些看似没有关联的现象，都可能与 .gitattribute

紫薇堂堂主

开发工具

编程语言

.gitattributes是Git按路径控制文件行为的规则文件，它影响行尾转换、差异展示、合并策略及GitHub语言统计。通过明确配置文本与二进制属性，可避免整文件误判改动、修复语言占比错误。规则随仓库共享，审查时需确认旧文件是否需规范化及过滤器依赖是否齐备。

日志文件

文件处理

代码解释

TypeScript 

Windows

容器

GitHub

Linux

Unix

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Git 仓库里的 .gitattributes，一份决定文件如何被处理的规则表-腾讯云开发者社区-腾讯云

Git 仓库里的 .gitattributes，一份决定文件如何被处理的规则表

Git 仓库里的 .gitattributes，一份决定文件如何被处理的规则表

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐