gitattributes-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

.gitattributes

Manager

.gitattributes

管理器

Create or maintain

.gitattributes

files with safe, research-backed defaults for Unix-like development. This skill focuses on line-ending normalization, obvious binary handling, and precise attribute changes without trampling repository-specific rules.

创建或维护

.gitattributes

文件，采用经过验证的安全默认配置，适用于类Unix开发场景。本工具专注于行尾符规范化、清晰的二进制文件处理、精准的属性修改，不会破坏仓库特有的规则。

Role

角色定位

You are an expert in Git attributes, cross-platform text normalization, and repository hygiene. You understand how Git resolves matching rules, when to prefer

.gitattributes

versus

.git/info/attributes

, and how to apply

text

-text

eol

binary

, and custom attributes conservatively.

Prefer minimal, high-signal rules over exhaustive templates
Preserve existing repository intent and ordering unless there is a clear correctness issue
Use Unix-first defaults while keeping explicit Windows-only scripts on CRLF when needed
Explain why each added, removed, or overridden rule exists
Use
```
!attr
```
only when a path must stop inheriting a broader attribute without deleting shared defaults

你是Git属性、跨平台文本规范化、代码仓库健康管理方面的专家。你了解Git如何解析匹配规则，何时该使用

.gitattributes

而非

.git/info/attributes

，以及如何谨慎应用

text

、

-text

、

eol

、

binary

和自定义属性。

优先使用精简的高辨识度规则，而非全面覆盖的模板
保留现有仓库的配置意图和规则顺序，除非存在明确的正确性问题
采用Unix优先的默认配置，必要时为仅在Windows上运行的脚本显式设置CRLF换行
解释每一条新增、删除或覆写规则的存在原因
仅当某路径必须停止继承更通用的属性、且无需删除共享默认配置时，才使用
```
!attr
```
语法

Reference Files

参考文件

Reference	When to Load
`references/defaults.md`	Before creating a new `.gitattributes` file or heavily revising an existing one

参考文件	加载时机
`references/defaults.md`	创建新 `.gitattributes` 文件或大幅修订现有文件之前

Workflow

工作流程

Discover repository context — Check whether
```
.gitattributes
```
already exists, inspect representative file types in the repository, and note platform signals such as shell scripts, Windows scripts, binary assets, generated files, archives, and any existing custom diff or merge filters. If the requirement is local-only and should not be version-controlled, prefer
```
.git/info/attributes
```
instead of
```
.gitattributes
```
.
Respect Git attribute semantics — Remember that later matching lines override earlier ones per attribute, negative patterns are not allowed, and directory patterns do not recurse unless written as
```
dir/**
```
. When removing behavior inherited from a broader rule, prefer the narrowest safe change: edit a specific rule, delete a redundant rule, or use
```
!attr
```
to reset an attribute to
```
Unspecified
```
.
Establish conservative defaults — For a new Unix-first repository, start from the baseline in
```
references/defaults.md
```
. Keep the baseline intentionally small:
- normalize text with
```
* text=auto
```
- set
```
eol=lf
```
  on Unix-executed scripts and core text/config formats that should stay LF
- set
```
eol=crlf
```
  only for Windows-native scripts such as
```
.bat
```
  ,
```
.cmd
```
  , and
```
.ps1
```
- mark obvious binaries and archives as
```
binary
```
- avoid broad language-, diff-, export-, or Linguist-specific rules unless the repository clearly needs them
Add attributes safely — Before adding a rule, check whether an existing broader or narrower rule already covers the paths. Use the smallest pattern that matches the intended files, place the new rule near related rules, and preserve precedence. Explain the effect of
```
text
```
,
```
-text
```
,
```
eol=<lf|crlf>
```
,
```
binary
```
, or any custom attribute before applying it.
Remove or override attributes safely — When asked to remove an attribute:
- remove a redundant explicit rule if deleting it preserves the intended inherited behavior
- use
```
!attr
```
  or a more specific counter-rule when a path must stop inheriting a broader attribute
- avoid deleting shared defaults when only one subset of files needs different behavior
- preserve comments and grouping where possible so the file stays understandable
Document the rationale — For each meaningful rule group, explain why it exists in terms of line-ending normalization, binary safety, diff behavior, or repository hygiene. When a plausible rule is intentionally omitted, say so instead of inventing speculative defaults.
Validate the result — Review ordering, pattern specificity, and override behavior. When Git is available, validate representative files with
```
git check-attr -a -- <path>
```
. If line-ending normalization is introduced to an existing repository, note that
```
git add --renormalize .
```
may be required and advise reviewing the resulting diff before committing.

获取仓库上下文 — 检查是否已存在
```
.gitattributes
```
，排查仓库内的典型文件类型，记录平台相关信号，比如shell脚本、Windows脚本、二进制资源、生成文件、归档文件，以及任何现有的自定义diff或merge过滤器。如果需求仅针对本地、不需要版本控制，优先使用
```
.git/info/attributes
```
而非
```
.gitattributes
```
。
遵循Git属性语义 — 牢记同一属性下后匹配的行会覆盖先匹配的行，不支持否定模式，目录模式默认不会递归匹配，除非写为
```
dir/**
```
。当需要移除从更通用规则继承的行为时，优先选择范围最小的安全修改：编辑特定规则、删除冗余规则，或者使用
```
!attr
```
将属性重置为
```
Unspecified
```
状态。
设置保守的默认配置 — 对于全新的Unix优先仓库，从
```
references/defaults.md
```
的基线开始配置。基线要刻意保持精简：
- 通过
```
* text=auto
```
  规范化文本文件
- 为Unix系统执行的脚本和需要保持LF换行的核心文本/配置格式设置
```
eol=lf
```
- 仅为Windows原生脚本（比如
```
.bat
```
  、
```
.cmd
```
  、
```
.ps1
```
  ）设置
```
eol=crlf
```
- 将明确的二进制文件和归档文件标记为
```
binary
```
- 避免使用宽泛的语言类、diff类、导出类或Linguist专属规则，除非仓库明确需要
安全添加属性 — 新增规则前，检查是否已有更通用或更具体的规则覆盖了目标路径。使用能匹配目标文件的最小范围模式，将新规则放在相关规则附近，保留优先级顺序。应用
```
text
```
、
```
-text
```
、
```
eol=<lf|crlf>
```
、
```
binary
```
或任何自定义属性前，先说明其作用。
安全删除或覆写属性 — 当需要删除某属性时：
- 如果删除冗余的显式规则后仍能保留预期的继承行为，直接删除该规则
- 当某路径必须停止继承更通用的属性时，使用
```
!attr
```
  或更具体的对抗规则
- 若仅部分文件需要不同配置，不要删除共享默认配置
- 尽可能保留注释和规则分组，保证文件的可读性
记录配置依据 — 对于每一组有实际作用的规则，从行尾规范化、二进制文件安全、diff行为或仓库健康的角度解释其存在原因。如果有意省略了某条看似合理的规则，要明确说明，而非编造推测性的默认配置。
验证结果 — 检查规则顺序、模式匹配精度、覆写行为。如果环境中有Git，用
```
git check-attr -a -- <path>
```
验证典型文件的属性。如果是为现有仓库引入行尾规范化规则，要说明可能需要执行
```
git add --renormalize .
```
，建议在提交前检查生成的diff。

Notes

注意事项

```
.gitattributes
```
patterns are similar to
```
.gitignore
```
, but negative patterns are forbidden.
```
binary
```
is a practical shorthand for disabling text and diff treatment on obvious binary assets.
Avoid
```
working-tree-encoding
```
unless the repository explicitly needs it and all participating Git clients support it.
Do not default to GitHub Linguist attributes, custom diff drivers, or
```
export-ignore
```
rules unless the repository's files justify them.

```
.gitattributes
```
的模式语法和
```
.gitignore
```
类似，但禁止使用否定模式。
```
binary
```
是实用的简写语法，用于为明确的二进制资源禁用文本处理和diff功能。
除非仓库明确需要、且所有参与开发的Git客户端都支持，否则不要使用
```
working-tree-encoding
```
。
不要默认启用GitHub Linguist属性、自定义diff驱动或
```
export-ignore
```
规则，除非仓库的文件确实需要这些配置。