git-cliff icon indicating copy to clipboard operation
git-cliff copied to clipboard

Support grouping changelog entries by minor version instead of per patch tag

Open d-cichon opened this issue 3 months ago • 2 comments

Is there an existing issue or pull request for this?

  • [x] I have searched the existing issues and pull requests

Feature description

Currently git-cliff generates changelog sections strictly per git tag.
For example, with tags like 0.0.1, 0.0.2, 0.0.412, 1.0.0, 1.0.5 the changelog is grouped as:

## 0.0.1
...
## 0.0.2
...
## 0.0.412
...
## 1.0.0
...
## 1.0.5
...

But often what we want in a product changelog is to group entries per minor version (X.Y), so that all patches under the same minor are merged into one section, like:

## 0.0
### Added
- …

### Changed
- …

## 1.0
### Added
- …

### Fixed
- …

## 1.0
### Added
- …

### Fixed
- …

This way the changelog is more compact and readable, and patch-level detail is unnecessary.

Desired solution

Expected feature:

  • New configuration option (e.g. group_by = "minor") that allows git-cliff to automatically aggregate commits from all patch tags (X.Y.Z) into a single section X.Y.
  • Ideally this should respect conventional commit groups (Added/Changed/Fixed etc.), just aggregated across all patch releases in the same minor.

Why useful:

  • Many projects use continuous patch releases (0.0.413, 0.0.414 …) but don’t want hundreds of patch sections in their changelog.
  • Grouping by minor gives a cleaner high-level overview while still keeping semantic grouping.

Alternatives considered

Workarounds tried:

  • Using tag_pattern = '^v?\d+\.\d+\.0$' only shows .0 tags, but then commits from later patches (0.0.2, 0.0.412) are not included.
  • Complex templates in footer that iterate over releases are error-prone and generate huge outputs.
  • Post-processing scripts (awk/grep) work, but defeat the purpose of having a single-tool solution.

Additional context

No response

d-cichon avatar Sep 03 '25 08:09 d-cichon

Thanks for opening your first issue at git-cliff! Be sure to follow the issue template! ⛰️

welcome[bot] avatar Sep 03 '25 08:09 welcome[bot]

Heya 👋🏼

This sounds good to me and I believe people can benefit from it if it is implemented. I think the easiest and most straightforward way for this would be a new Tera filter, such as group_by_scope, so you can use it in the template.

An example implementation of a filter is available in #1287 - we can also get inspired by the built-in group_by filter: https://github.com/Keats/tera/blob/4e5145e2231c7b7b5939b1aa4bc85789a8a75fcd/src/builtins/filters/array.rs#L150

Marking as good-first issue if anyone wants to give this a shot.

orhun avatar Nov 04 '25 14:11 orhun