Git行尾配置Skill line-endings

---

name: line-endings description: Git行尾配置的全面指南，适用于跨平台开发团队。用于配置行尾、设置.gitattributes、排查行尾问题、理解core.autocrlf/core.eol/core.safecrlf、使用Git LFS、规范化仓库中的行尾，或解决跨平台行尾冲突。覆盖Windows、macOS、Linux和WSL。包括决策树、工作流、最佳实践和真实场景。 allowed-tools: Read, Bash, Glob, Grep

Git行尾配置

Git行尾配置的全面指南，适用于跨平台开发团队。

何时使用此技能

使用此技能时：

• 行尾任务 - 处理Git行尾配置的全面指南，适用于跨平台开发团队。用于配置行尾、设置.gitattributes、排查行尾问题、理解core.autocrlf/core.eol/core.safecrlf、使用Git LFS、规范化仓库中的行尾，或解决跨平台行尾冲突。覆盖Windows、macOS、Linux和WSL。包括决策树、工作流、最佳实践和真实场景。
• 规划或设计 - 需要行尾方法的指导
• 最佳实践 - 希望遵循既定模式和标准

最后验证日期： 2025-11-25 最后审核日期： 2025-11-25（全面A类审核 - 79/80分，内容通过MCP服务器根据官方Git文档验证）

概述

什么是行尾？

行尾是文本文件中标记行结束的不可见字符：

• LF（换行符）： - 用于Unix、Linux、macOS（1字节）
• CRLF（回车符 + 换行符）：\r - 用于Windows（2字节）
• CR（回车符）：\r - 旧版Mac OS 9及更早版本（现在少见）

为什么行尾重要

问题：

# Windows开发者创建带CRLF的文件
echo "#!/bin/bash" > script.sh

# Linux开发者拉取并尝试运行
./script.sh
# 错误：/bin/bash^M: bad interpreter: No such file or directory

常见问题：

1. 脚本执行失败（Unix需要LF，CRLF破坏shebang行）
2. 大量差异（仅行尾不同时，每行显示为更改）
3. 文件损坏（二进制文件被当作文本处理时，行尾被破坏）
4. 构建失败（Makefiles、配置文件可能需要特定行尾）
5. Git冲突（行尾差异导致合并冲突）

Git如何处理行尾

Git提供三种机制：

1. 配置设置（core.autocrlf、core.eol、core.safecrlf）- 自动转换
2. .gitattributes文件 - 明确的每文件或每模式规则（最高优先级）
3. 手动规范化（git add --renormalize）- 一次性修复

Git的设计哲学：

• 仓库（索引）：规范化行尾（通常为LF）
• 工作目录：平台适当的行尾（Windows上CRLF，Unix上LF）
• 转换在检出和提交时自动发生

---

快速开始

两种配置方法

选项1：传统（推荐）

平台特定配置，带自动规范化：

# Windows
git config --global core.autocrlf true
git config --global core.safecrlf warn

# Mac/Linux
git config --global core.autocrlf input
git config --global core.safecrlf warn

优点：

• ✅ 无需.gitattributes即可工作（对外部仓库安全）
• ✅ Git for Windows默认（Windows上零配置）
• ✅ 自动规范化防止混合行尾
• ✅ 行业标准

何时使用： 在不控制的仓库中工作（开源、客户、供应商仓库）

选项2：现代显式

所有平台相同配置，依赖.gitattributes：

# 所有平台
git config --global core.autocrlf false
git config --global core.eol native
git config --global core.safecrlf warn

优点：

• ✅ 所有平台配置相同（团队一致性）
• ✅ 明确和可预测
• ✅ 现代最佳实践

缺点：

• ⚠️ 需要.gitattributes - 没有它则无效
• ⚠️ 对外部仓库不安全

何时使用： 控制所有仓库并能确保全面的.gitattributes

推荐

使用选项1，如果你在混合环境中工作（内部 + 外部仓库）。参见配置方法获取详细比较。

---

决策树

对于涵盖所有场景（仓库控制、平台选择、文件类型、故障排查）的全面决策树，参见决策树。

快速决策：

1. 你控制所有仓库吗？ 否 → 使用选项1（传统）
2. 什么平台？ Windows：autocrlf=true，macOS/Linux：autocrlf=input
3. 有.gitattributes吗？ 是 → 两种选项都有效，否 → 仅选项1

---

理解.gitattributes

.gitattributes是仓库级文件，明确声明Git应如何处理特定文件。

最小.gitattributes：

# 自动检测文本文件并在仓库中规范化为LF
* text=auto

全面.gitattributes：

# 默认：自动检测和规范化
* text=auto

# 文档 - 所有地方LF
*.md text eol=lf
*.txt text eol=lf

# Shell脚本 - 必须为LF（Unix要求）
*.sh text eol=lf
*.bash text eol=lf

# PowerShell脚本 - CRLF（Windows标准）
*.ps1 text eol=crlf
*.cmd text eol=crlf
*.bat text eol=crlf

# 配置文件 - LF（跨平台）
*.json text eol=lf
*.yml text eol=lf
.gitignore text eol=lf
.gitattributes text eol=lf

# 二进制文件 - 从不转换
*.png binary
*.jpg binary
*.pdf binary
*.zip binary
*.exe binary

为什么使用.gitattributes：

• 明确的规则提交到仓库
• 所有开发者获得相同行为
• 覆盖本地配置
• 自文档化

参见.gitattributes指南获取全面模式和属性参考。

---

平台特定配置

Windows

# 检查当前配置（应来自Git for Windows的默认设置）
git config --global --get core.autocrlf
# 期望：true

# 如果未设置，显式配置
git config --global core.autocrlf true
git config --global core.safecrlf warn

行为：

• 工作目录中的文件：CRLF（Windows标准）
• 仓库中的文件：LF（跨平台标准）
• 在检出和提交时自动转换

参见平台特定配置获取Windows、macOS、Linux和WSL的详细设置指南。

---

常见问题与故障排查

问题：Shell脚本无法执行（^M: bad interpreter）

错误：

$ ./script.sh
bash: ./script.sh: /bin/bash^M: bad interpreter: No such file or directory

根本原因： Shell脚本有CRLF行尾。Unix shell需要LF。

立即修复：

# 将CRLF转换为LF
dos2unix script.sh

# 或用sed
sed -i 's/\r$//' script.sh

# 使可执行
chmod +x script.sh

永久修复（添加到.gitattributes）：

# Shell脚本必须为LF
*.sh text eol=lf
*.bash text eol=lf

# 规范化脚本
git add --renormalize script.sh
git commit -m "修复shell脚本中的行尾"

问题：Git显示每行都已更改

根本原因： 行尾更改（CRLF ↔ LF）。

修复：

# 检查当前行尾
git ls-files --eol file.txt

# 规范化为仓库标准
git add --renormalize file.txt
git commit -m "规范化file.txt的行尾"

参见故障排查获取全面问题解决方案。

---

命令参考

基本命令快速参考：

# 查看配置
git config --list --show-origin | grep -E "autocrlf|eol|safecrlf"

# 检查文件属性
git check-attr -a README.md

# 检查行尾状态
git ls-files --eol README.md

# 规范化文件
git add --renormalize .

# 测试行尾行为
git ls-files --eol | grep "w/crlf" | grep "eol=lf"  # 查找不匹配

参见命令参考获取完整命令列表。

---

最佳实践总结

1. 在控制的仓库中始终使用.gitattributes

   • 明确的行尾规则
   • 团队一致性
   • 自文档化

2. 在入职文档中记录平台特定配置

   • Windows：验证autocrlf=true
   • macOS/Linux：必须设置autocrlf=input

3. 设置core.safecrlf=warn以确保安全

   • 警告行尾转换
   • 早期捕捉问题

4. 用git ls-files --eol测试

   • 定期检查不匹配
   • 查找混合行尾

5. 添加.gitattributes时进行规范化

   • 运行git add --renormalize .
   • 审核并提交更改

参见最佳实践获取详细指导。

---

Git大文件系统（LFS）

Git LFS将大型二进制文件单独存储在主仓库之外，以防止膨胀。这与行尾配置分开，但可协同工作。

参见Git LFS指南获取全面安装、配置、使用时机、GitHub限制和迁移策略。

---

参考

配置和设置：

• 决策树 - 所有场景的全面决策流程图
• 配置机制 - Core.autocrlf、core.eol、core.safecrlf解释
• 配置方法 - 选项1 vs 选项2比较
• 平台特定配置 - Windows、macOS、Linux、WSL设置指南

实现：

• .gitattributes指南 - 全面模式和属性参考
• Git LFS指南 - 安装、配置、迁移、GitHub限制
• 工作流与场景 - 新仓库、现有仓库、外部仓库、团队入职
• 真实世界示例 - 实际示例和案例研究

故障排查与支持：

• 故障排查 - 常见问题和详细解决方案
• 命令参考 - 完整命令列表带示例
• 最佳实践 - 详细最佳实践和预防策略

测试：

• 评估 - 测试场景、多模型测试、正式评估

---

测试与评估

对于全面测试场景、多模型测试笔记和正式评估，参见评估。

评估摘要： 4/4评估通过（100%）- 使用Claude Sonnet 4和Claude Opus 4.5测试

---

版本历史

• v2.2.0 (2025-11-28): 令牌优化 - 提取决策树和评估到references/以实现渐进披露，减少SKILL.md从534到约400行
• v2.1.2 (2025-11-25): 通过MCP服务器内容验证 - 所有技术内容根据官方Git文档验证准确
• v2.1.1 (2025-11-25): 审核改进 - 修复模型命名约定，添加Opus 4.5验证
• v2.1.0 (2025-11-17): 质量改进 - 添加正式评估、多模型测试笔记
• v2.0.1 (2025-11-17): 内容审核 - 更新GitHub LFS限制，根据Git 2.51.2验证
• v2.0.0 (2024-11-09): 中心/辐条重构 - 提取详细内容到references/
• v1.0.0 (2024-11-09): 初始发布，带全面行尾指导

---

官方文档

• Git属性
• Git配置 - core.autocrlf
• Git配置 - core.eol
• 配置Git处理行尾（GitHub）
• Git LFS官方网站
• Git LFS计费（GitHub）

最后更新

日期： 2025-11-28 模型： claude-opus-4-5-20251101