Support a body template specifically for when there are no contributing commits

[jonathanj]

Is there an existing issue or pull request for this?

• I have searched the existing issues and pull requests

Feature description

In the case where no commits contribute to the new version, which is fairly likely with --include-path and monorepos, the body template is apparently not evaluated at all. Then when the changelog is modified (for example with --prepend …) no changes occur, and then there is nothing to stage, which git commit doesn't like and will exit with a non-zero status.

Desired solution

A template specifically for the case where there are in fact no commits contributing, then it would be possible to still output a changelog for this, which would a) record the new version's existence and b) be explicit about the fact that there are no changes.

Alternatives considered

Alternative 1: git commit --allow-empty

This is the workaround we opted for, but unfortunately it means the version isn't recorded at all in the changelog.

Alternative 2: Reuse the existing body template

Requiring everyone to cater for branching on zero commits is breaking the current contract for the body template, and seems slightly annoying to write the template for.

Additional context

I'm basing my assumption that body isn't run at all by placing some literal text at the very top of body and noting that it does not appear in the changelog until I remove filters/include paths to eventually include at least one commit.

[welcome]

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

[orhun]

Hello! Thanks for the issue and sorry for the delayed response.

I have implemented this as a configuration option (always_render) here: #859

Can you build from source and test it out if you are still interested? 🐻

[jonathanj]

Hi @orhun, thanks for the reply and the change.

I built this branch and set the always_render = true option, and played around with this a bit. I'm a bit stuck with getting what I want to happen, and I'm not sure I fully understand what is happening.

The relevant portion of my body template looks like this now:

{% if version %}
    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else %}
    ## [unreleased]
{% endif %}

{% if commits | length == 0 -%}
No significant changes.

{% else -%}
{% for group, commits in commits | group_by(attribute="group") -%}
    ### {{ group | upper_first }}
    etc.
{% endfor %}
{%- endif %}

If I run git-cliff when there are zero contributing commits at all (such as using --include-path 'nonexistent/path') then it sort of appears to work as expected:

$ git-cliff --repository ../../ --include-path 'nonexistent/path' --tag '10.6.0' --unreleased
## [unreleased]


No significant changes.

I say "sort of" because the version didn't get set, and verifying with --context I can see version: null, commits: [].

If I run git-cliff when there are contributing commits, then I get the contributing commits and the version is working correctly, however I still have version: null in context, and so the empty section is also output, except the previous context is populated:

$ git-cliff --repository ../../ --include-path 'real/path' --tag '10.6.0' --unreleased
## [unreleased]


No significant changes.


## [10.6.0] - 2024-09-18


### ✨ Features

Would I need to extend my condition to also check if previous.commits | length == 0 too? Just wanted to check if I'm going off on a tangent before I actually go off on one.

Thanks again!

[orhun]

Thanks for testing it! I pushed a new commit to that branch for fixing those cases, can you check again? 👀

[orhun]

Btw I renamed it to render_always, it sounded more correct.

[orhun]

Oops closed by accident, feel free to let me know if there are issues. Going to include it in the next release now :)