Git变更日志漏报删除操作：工具设计中的盲区

开发者构建了一个基于Git diff的变更日志API，用于对比两个提交并生成发布说明。工具在大多数场景下运行良好，直到某位贡献者在v1.4到v1.5之间删除了整个模块——而生成的变更日志对此只字未提。没有报错，没有标记，没有任何提示。只有一份欢快的列表，展示新增和修改了什么。

这个问题的根源在于：git diff --name-status 会用 D 状态标记删除操作，但多数变更日志生成器（包括作者最初版本）只渲染 A（新增）和 M（修改）。开发者过滤了所谓“有意义”的变更，却悄悄丢弃了最具破坏性的那类——删除。重命名函数只是查找替换，删除端点却会导致凌晨三点的告警。

修复方式简单而正确：将 D 视为一等公民，并用比新增更醒目的措辞呈现。“Removed POST /v1/legacy-auth” 和 “Added dark mode” 读起来完全不同。

作者还发现提交信息并不可靠。那个删除模块的提交，信息竟是“Refactor auth”。diff 才是唯一真相来源，提交信息只是匆忙写下的说明。生成器现在以 diff 实际显示的内容为主，将提交信息降级为脚注。

与托管变更日志工具（release-drafter、semantic-release、changesets）的对比：它们都依赖提交约定——BREAKING CHANGE: 页脚、feat!: 前缀。这在团队纪律良好时有效。但作者的API面向的是“不守纪律的现实”：真实仓库中人们压缩合并、强制推送、写“fix stuff”。约定是希望，diff是事实。

如果你在自行对比Git历史，教训是：永远不要相信一个不显示删除操作的变更日志。如果它无法告诉你什么消失了，那它就不是变更日志——而是一份新闻稿。

作者最终将其打包为 https://x402.freeq.one/tools/changelog_git.html

背景补充

git diff --name-status 简介

git diff --name-status 是 Git 的一条命令，用于比较两个提交（或工作区与暂存区）之间文件的变更情况，并以简洁的列表形式输出。每行包含一个状态字母和文件路径：A 表示新增（Added），M 表示修改（Modified），D 表示删除（Deleted），R 表示重命名（Renamed），C 表示复制（Copied）。与完整的 git diff 相比，它不显示具体代码差异，只给出文件级的状态摘要，因此非常适合用于构建变更日志、发布说明或快速审查变更范围。在自动化工具中，解析 --name-status 的输出比解析完整 diff 更简单可靠，但开发者必须显式处理所有状态类型，否则就会像原文所述那样遗漏删除操作。

托管变更日志工具与提交约定

release-drafter、semantic-release、changesets 等托管工具的核心机制是解析提交信息中的约定式标记，例如 feat:、fix:、BREAKING CHANGE: 或 feat!:。它们假设团队遵循 Angular 提交规范或类似约定，从而自动分类变更并生成日志。这种方案在纪律良好的团队中效率很高，但一旦有人压缩合并、强制推送或随意填写提交信息（如“fix stuff”），工具就会失效或产生误导。相比之下，基于 git diff 的方案不依赖任何人为约定，直接读取代码库的实际变化，因此更能适应“不守纪律”的真实开发环境。原文作者正是基于这一理念，将 diff 作为唯一真相来源，把提交信息降级为辅助脚注。