repo-attributes

repo-attributes

配置仓库的文件级属性层：.gitattributes、.editorconfig、.gitignore 和 Git LFS 过滤器模式。

此配置仅针对仓库。它不会修改 pre-commit 钩子、CI 流水线、组织级自定义属性或社区健康文件。

此技能的适用范围

关注事项	技能
行尾、linguist 覆盖项、编辑器默认设置、忽略规则、LFS 模式	/repo-attributes（此技能）
Pre-commit / prek 钩子选择和 prek.toml	/prek
社区健康文件（README、LICENSE、CODE_OF_CONDUCT、CONTRIBUTING、SECURITY）	/oss-hygiene
组织范围的代码化设置，包括自定义属性	/safe-settings

协议

1. 检测语言标记和现有配置

扫描仓库根目录中的语言标记，使用与 /prek 相同的检测方法：

标记文件	语言/框架
Cargo.toml	Rust
pyproject.toml、setup.py、requirements.txt	Python
package.json	TypeScript/JavaScript
go.mod	Go
Gemfile	Ruby
*.sh、zsh/、bin/	Shell
Dockerfile	Docker

多个标记表示这是多语言项目。在生成的文件中涵盖检测到的所有语言。

检查是否已有 .gitattributes、.editorconfig、.gitignore 和 .gitmodules。读取每个已存在的文件，并将其内容视为底线，而非替换目标。

检查是否使用 Git LFS：

git lfs ls-files

如果未安装 git lfs，则跳过 LFS 检测并说明原因；不要猜测由 LFS 跟踪的路径。

2. 提议 .gitattributes

以 assets/gitattributes.example 为基础结构。根据第 1 步的检测结果，包含以下内容：

• * text=auto — 让 Git 规范化其识别到的文本文件的行尾。
• 为绝不能出现 CRLF 的脚本和其他文件明确设置 eol=lf，例如 *.sh text eol=lf。
• 为必须跳过行尾转换和差异转换的资源类型标记为二进制，例如 *.png binary。
• 对不应计入 GitHub 语言占比条或代码审查差异的路径，设置 linguist-generated、linguist-vendored 和 linguist-documentation。
• 对 CHANGELOG.md 等仅追加文件使用 merge=union，以便并行添加的条目能够合并而非冲突。
• 对不应包含在 git archive 输出中的路径使用 export-ignore，例如仅供 CI 使用的目录。
• 对具有更实用语义差异的文件类型设置 diff= 驱动程序（例如，在已配置该驱动程序时设置 *.md diff=markdown）。
• 对 git lfs ls-files 已跟踪的路径或用户指定的路径，设置 LFS 模式（filter=lfs diff=lfs merge=lfs -text）。

将提议内容与现有 .gitattributes 进行差异比较；如果某行已存在但内容不同，覆盖前先询问用户。

3. 提议 .editorconfig

使用 assets/editorconfig.example。包含 root = true、带有 charset、end_of_line、insert_final_newline、trim_trailing_whitespace、indent_style 和 indent_size 的 [*] 部分，然后为检测到的每种语言添加一个覆盖部分，采用其惯用缩进风格（例如 Go 和 Makefiles 使用制表符，Python 使用四空格缩进）。

4. 提议 .gitignore

获取 GitHub 为检测到的语言提供的模板：

gh api /gitignore/templates
gh api /gitignore/templates/{name} --jq .source

将获取的模板内容与现有 .gitignore 合并。追加缺失的模板行；绝不删除任何现有用户条目，即使它看起来是多余的。

5. 规范化行尾（仅在获准后）

当 .gitattributes 的变更会改变已跟踪文件的存储方式时，git add --renormalize . 会重写已跟踪文件的内容，使其符合新规则。这会破坏性地重写已跟踪内容，因此：

• 首先要求工作树干净：git status --porcelain 必须不输出任何内容。
• 运行此命令前，必须获得用户明确授权。提议 .gitattributes 时，绝不能将重新规范化作为附带操作。
• 如果工作树不干净，则停止操作，并请用户先提交或暂存更改，然后再进行重新规范化。

6. 验证

git check-attr -a <file>
git ls-files --eol
gh api repos/{owner}/{repo}/languages

使用 git check-attr -a <file> 确认应用的属性与提案一致。使用 git ls-files --eol 确认工作树和索引中的换行符与 .gitattributes 一致。更改同步到 GitHub 后，调用 GitHub languages API，确认 linguist 覆盖设置已改变报告的语言构成。

此技能不适用于

• 选择提交前或 prek 钩子——那是 /prek 的用途。
• GitHub 自定义属性或其他组织级元数据——不在此技能的范围内。
• 社区健康文件（README、LICENSE、CODE_OF_CONDUCT、CONTRIBUTING、SECURITY）——那是 /oss-hygiene 的用途。
• CI 流水线配置——这不属于仓库属性的范畴。

注意事项

• 单独使用 * text=auto 无法确保贡献者在 Windows 检出时，脚本使用 LF；对于必须避免变成 CRLF 的文件，应搭配明确的 eol=lf 规则。
• linguist-generated 和 linguist-vendored 会更改 GitHub 语言栏和 PR 差异默认折叠行为，但不会影响本地 git diff 输出。
• git add --renormalize . 只会改写索引和工作树，不会改写历史记录。现有克隆仍会显示旧的换行符，直到它们拉取更改并自行重新运行该命令。
• 如果本地没有运行 git lfs install，LFS 过滤器模式不会产生任何效果；在建议使用过滤器模式解决大文件问题前，请确认已安装 LFS。
• .gitignore 只会影响未跟踪文件。已跟踪的路径会继续保持跟踪状态，直到使用 git rm --cached 将其显式移除。

参考资料

• references/attributes.md — .gitattributes、linguist 覆盖设置、.editorconfig、换行符配置、.gitignore 和 Git LFS 的引用来源。