Git Changelog Generators Silently Drop Deletions: A Blind Spot in Tool Design

The Problem

A developer built a Git diff-based changelog API to compare two commits and generate release notes. The tool worked well in most cases—until a contributor deleted an entire module between v1.4 and v1.5, and the generated changelog didn't mention it at all. No error, no flag, no hint. Just a cheerful list of what was added and modified.

The root cause: git diff --name-status marks deletions with a D status, but most changelog generators (including the author's initial version) only render A (Added) and M (Modified). The developer filtered for so-called "meaningful" changes, but silently discarded the most destructive category—deletions. Renaming a function is just a find-and-replace; deleting an endpoint causes 3 a.m. alerts.

The fix is simple and correct: treat D as a first-class citizen and present it with more prominent wording than additions. "Removed POST /v1/legacy-auth" and "Added dark mode" read completely differently.

The author also found that commit messages are unreliable. The commit that deleted the module had the message "Refactor auth." The diff is the only source of truth; commit messages are just hastily written notes. The generator now prioritizes what the diff actually shows, demoting commit messages to footnotes.

Comparison with hosted changelog tools (release-drafter, semantic-release, changesets): they all rely on commit conventions—BREAKING CHANGE: footers, feat!: prefixes. This works when teams are disciplined. But the author's API targets "undisciplined reality": real repositories where people squash-merge, force-push, and write "fix stuff." Conventions are hopes; the diff is fact.

If you're comparing Git history yourself, the lesson is: never trust a changelog that doesn't show deletions. If it can't tell you what disappeared, it's not a changelog—it's a press release.

The author ultimately packaged it as https://x402.freeq.one/tools/changelog_git.html

Background

Introduction to git diff --name-status

git diff --name-status is a Git command that compares file changes between two commits (or between the working tree and staging area) and outputs a concise list. Each line contains a status letter and a file path: A for Added, M for Modified, D for Deleted, R for Renamed, C for Copied. Unlike a full git diff, it doesn't show actual code differences—only a file-level status summary—making it ideal for building changelogs, release notes, or quickly reviewing the scope of changes. In automation tools, parsing --name-status output is simpler and more reliable than parsing a full diff, but developers must explicitly handle all status types, or they'll miss deletions as described in the original article.

Hosted changelog tools and commit conventions

The core mechanism of hosted tools like release-drafter, semantic-release, and changesets is parsing conventional markers in commit messages, such as feat:, fix:, BREAKING CHANGE:, or feat!:. They assume teams follow Angular commit conventions or similar, automatically categorizing changes and generating logs. This approach is highly efficient for disciplined teams, but once someone squash-merges, force-pushes, or writes arbitrary commit messages (like "fix stuff"), the tools fail or produce misleading results. In contrast, a git diff-based approach doesn't depend on any human conventions—it directly reads the actual changes in the codebase, making it more adaptable to "undisciplined" real-world development environments. The original author embraced this philosophy, treating the diff as the single source of truth and demoting commit messages to auxiliary footnotes.