jason-hchsieh/changelog

Generate Changelog

You are generating or updating a CHANGELOG.md file using git-cliff. For complete usage documentation, visit the git-cliff usage guide.

Prerequisites

Check that git-cliff is installed:

git-cliff --version

If not installed, offer to install:

• macOS: brew install git-cliff
• Cargo: cargo install git-cliff

Check if cliff.toml exists in the project root. If not, suggest running /version-init to bootstrap configuration.

Workflow

1. Determine Mode

Check if CHANGELOG.md already exists:

• No CHANGELOG.md: Generate a full changelog from all history
• CHANGELOG.md exists: Prepend only unreleased changes

2. Generate Changelog

Full generation (new or full regeneration):

git-cliff --output CHANGELOG.md

Incremental update (append unreleased changes):

git-cliff --unreleased --bump --prepend CHANGELOG.md

View latest release section only (for review):

git-cliff --latest

3. Review Output

After generation, read the CHANGELOG.md file and show the user the changes (or the latest section for incremental updates).

If the user wants a full regeneration instead of an incremental update:

git-cliff --output CHANGELOG.md

4. Key git-cliff Flags Reference

For comprehensive git-cliff documentation and advanced usage, see git-cliff Usage Documentation.

| Flag | Purpose | |------|---------| | --output FILE | Write full changelog to file | | --prepend FILE | Prepend new content to existing file | | --unreleased | Only include unreleased commits | | --bump | Auto-detect next version from commits | | --latest | Show only the latest release section | | --tag TAG | Use a specific tag for the release | | --config FILE | Use a specific config file | | --init STYLE | Initialize cliff.toml (styles: keepachangelog, default, minimal) | | --changelog FILE | Specify custom changelog filename | | --strip SECTION | Strip specified section from changelog | | --exclude-path PATTERN | Exclude paths from changelog |

4.1 Configuration Styles

Keep a Changelog (recommended for most projects):

git-cliff --init keepachangelog

Produces well-structured changelogs with sections: Added, Changed, Deprecated, Removed, Fixed, Security

Default git-cliff style:

git-cliff --init

Uses git-cliff's default configuration format

Minimal style:

git-cliff --init minimal

Compact, minimal configuration for simple projects

5. Common Scenarios

First-time changelog for an existing project:

git-cliff --output CHANGELOG.md

Update before a release:

git-cliff --unreleased --bump --prepend CHANGELOG.md

Preview what would be in the next release:

git-cliff --unreleased --bump

Regenerate everything from scratch:

git-cliff --output CHANGELOG.md

Output Format

After generating, report:

## Changelog Updated

- **Mode**: Full generation | Incremental update
- **File**: CHANGELOG.md
- **Versions covered**: vX.Y.Z - vA.B.C (or "all history")

### Preview (latest section)
[Show the most recent section of the changelog]