git-changelog — Auto-Generate Changelogs

Generate polished, categorized changelogs from git commit history. Outputs markdown ready for CHANGELOG.md or GitHub releases.

Steps

1. Verify Git Repository

git rev-parse --is-inside-work-tree

If this fails, stop — not a git repository.

2. Determine Range

The user may specify:

• Tag-to-tag: v1.0.0..v1.1.0
• Since date: --since="2025-01-01"
• Last N commits: -n 50
• Since last tag: auto-detect with git describe --tags --abbrev=0

Default behavior — find the last tag and generate from there to HEAD:

LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)

If no tags exist, use the full history.

3. Extract Commits

# Tag-to-HEAD
git log ${LAST_TAG}..HEAD --pretty=format:"%H|%s|%an|%ad" --date=short

# Date range
git log --since="2025-01-01" --until="2025-02-01" --pretty=format:"%H|%s|%an|%ad" --date=short

# Full history
git log --pretty=format:"%H|%s|%an|%ad" --date=short

4. Categorize by Conventional Commits

Parse each commit subject and group into categories:

Parse pattern: type(scope): description or type: description

5. Generate Markdown

Output format:

# Changelog

## [v1.2.0] — 2025-02-15

### ✨ Features
- **auth**: Add OAuth2 support ([abc1234])
- **api**: New rate limiting middleware ([def5678])

### 🐛 Bug Fixes
- **db**: Fix connection pool leak ([ghi9012])

### 📚 Documentation
- Update API reference ([jkl3456])

Rules:

• Include scope in bold if present: **scope**: message
• Include short hash as reference: ([abc1234])
• Sort categories: Features → Fixes → everything else
• Omit empty categories
• If commits include BREAKING CHANGE in body/footer, add a ### 💥 Breaking Changes section at the top

6. Detect Breaking Changes

git log ${LAST_TAG}..HEAD --pretty=format:"%H|%B" | grep -i "BREAKING CHANGE"

Also flag commits with ! after type: feat!: remove legacy API

7. Output

• Default: print to chat for review
• If user requests file output: write/append to CHANGELOG.md at project root
• When prepending to existing CHANGELOG.md, insert after the # Changelog header, before previous entries

Edge Cases