You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add first‑class support for producing pre‑release versions (e.g., alpha, beta, rc) when computing the next version in git-cliff. Many teams ship pre‑release builds to internal users or early adopters prior to a final release. Today, git-cliff can compute and bump versions, but there’s no explicit mechanism to mark the next version as a pre‑release and increment the pre‑release sequence.
Desired solution
The introduction of a new CLI flag that will instruct git-cliff to incremental the version and at the same time use pre-relase versioning. Something similar to the logic used in the the commit-and-tag-version project
Set pre‑release to .0 (e.g., alpha.0, beta.0, rc.0).
If there is an existing pre‑release:
if the same type: increment the numeric suffix (rc.1 to rc.2).
If a different type: set to the new type with numeric suffix .0. (as long as we are not reducing the type of the release. For example if we already have beta.1 and the user specifies alpha, then the resulting version should be beta.2 and not alpha.0)
Furthermore, prereleases are also usually filtered out, so the implementation should also be able to handle the skip_tags options and still calculate correct the next version.
Alternatives considered
I did not find a way on the documentation to achieve the creation of preleases, without creating first the tag myself.
I would ignore the flag. The semantics are not clear. I would not apply the flag in cases where we do not have already a release. If the user wants an alpha initial tag, he/she can specify it directly in the options
1.2.0-beta.2
--bump --pre-release beta
1.2.0-beta.3. This helps with pipelines or instructions. You know from the beggining that the counting will be correct
1.2.0-rc.3
--bump
Should produce 1.2.0 . This is the point of release candidates, right? To be able to release the final version without bumping patch or minor version
1.2.0-alpha.2
--pre-release beta
Should become 1.2.0-beta.0. beta is greater than alpha, so we can just start counting from 0
1.2.0-beta.3
--pre-release alpha
Ignore and produce 1.2.0-beta.4. Or if not possible just reject it and warn the user for the mistake ?
1.2.0-rc.0, 1.2.0-rc.2
--pre-release rc
I would argue that it should be rc.3. I am guessing the same behavior with existing normal released tags. We increment the last valid one.
1.2.0-beta.2+build.45
--pre-release beta
That`s a good question. For this complicated cases I would argue that probably we should leave it to the user. But how can we let the user input the parameters? Probably we need better input arguments in the CLI ?
1.2.0-alpha.1.2
--pre-release alpha
What does it even mean? Probably next_version would increase the last digit ... I would reject to be honest, but I do not know what the user is trying to achieve. Probably the same use case as the previous one
v1.2.0
--pre-release beta
I am guessing it should preserve the prefix and produce v1.3.0-beta.0. What happens to the normal tags ? I would keep the same behavior, as the normal tags
1.2.0-beta.3 (skipped via skip_tags)
--pre-release beta
I would say yes, it should be taken into consideration and affect the version calculation. If the user really wants to exclude it, he/she can use the ignore_tags. That way you can also put the pre-release tags in the ignore_tags and then they will be concantanated into the next release
0.3.0-beta.2
--bump major --pre-release alpha
What would happen if we just had 0.3.0 with --bump major? If it the result is 0.4.0, then we increment to 0.3.0-beta.3 (because the 0.3.0-beta.2 --bump major should produce 0.3.0 ). If the result is 1.0.0, then we can start with 1.0.0-alpha.0.
1.2.0-beta.2, 1.2.0
--pre-release rc
Next valid version with -rc appended. So 1.3.0-rc.0
One more comment for the 1.2.0-beta.2+build.45 use case. Apparently it is specified in the specs: Build metadata MUST be ignored when determining version precedence. So after that I would say it should be ignored/preserved. So something like 1.2.0-beta.3+build.45 . What does git-cliff currently does with build metadata?
I think the interaction between --bump and --prerelease will likely require quite a bit of design discussion, and it's not entirely clear yet whether (or how) we want to support all those edge cases.
As a first step, I would suggest starting with a smaller and more well-scoped change: extending the existing --bump option to support prerelease as a version type, similar to the current major, minor, and patch options:
This would likely require clarifying some details around next_version, but overall the semantics seem much less ambiguous compared to introducing a separate --prerelease flag and defining its interaction with --bump.
Once that is in place, we could then iterate on more advanced prerelease workflows if needed.
The implementation sketch you shared is about handling the dependency between --bump and --prerelease. What I am proposing here is slightly different. I'm focusing on adding Prerelease as a new variant to BumpType:
Since we already rely on the next_version crate, which extends semver::Version and provides prerelease support via the NextVersion trait, we can leverage that implementation directly:
Do not introduce or fully support --prerelease yet
If prerelease bump is requested but no prerelease identifier is detected in the previous version, return an error during changelog generation
This way, we can introduce --bump prerelease in a minimal and well-scoped manner without blocking on the full --prerelease CLI design. Then, the detailed behavior and interaction between --bump and --prerelease can continue to be discussed in this tracking issue.
I think we should first define what --bump prerelease means in isolation, before defining how it interacts with other flags or edge cases.
That said, even the semantics of --bump prerelease itself might turn out to be more complex than it initially appears. A prerelease is technically not a version "level" like major/minor/patch, but rather an identifier attached to a version. Because of that, modeling it as a --bump type could introduce some conceptual distortion in the design and it might not even be the best abstraction for this feature.
As we can already see from the combination tables discussed here, the number of cases this feature would need to cover is larger than it might seem at first glance. So it may be worth carefully scoping what we want the initial behavior to guarantee before expanding it to handle all edge cases.
Ah, I took another look at the current implementation, and it seems that the existing --bump behavior already covers what I was trying to propose here (--bump prerelease).
So there's no need to introduce Prerelease as a new BumpType after all. Sorry for the noise, please disregard this suggestion.
Sorry for the slow progress here. I'll take another look at the proposal again. My current feeling is that we should try to keep the solution and semantics as simple as possible.
So, I took my time reading through all of the comments and to be frank, I think we are in an area of overcomplicating a solution to a problem that doesn't really exist. @anagno's initial proposal was simple and clean. Just introduce a pre-release tag and only consider tags that do match a simple pattern of <semver>-<pre-release tag>.<sequence nr>. If people want to embed even more information in their version numbers (which I would strongly advocate against), they simple leave the realm of what can reasonably be supported without over-complicating the situation.
Also, I didn't go through the exercise of creating tables myself, but they feel like you just went through all possible permutations of tags and parameters and are trying to make sense of them. But that doesn't work. We need to think about the workflows that drive use of git-cliff and result in a much more limited set of reasonable combinations of parameters. And all of those make sense to me. The only question is whether git-cliff should spent effort on detecting unreasonable combinations and hold the user's hand or whether we enter undefined behaviour.
I would go integrate the simple schema proposed here. It allows using git-cliff for versioning in a slightly more elaborate setup than the tool can support until now, without causing a mess.
@orhun@ognis1205 The #1345 is implementing the simpler logic. I would suggest either to take a look on the PR or if it is not something that you would like to support let`s close the PR
I'm not sure... we need to either rebase #1345 or come up with another approach.
I think that PR is a good start though.
WDYT? Does that satisfy your use case?
I built the rebased PR and gave it a try — it works great!
The PR description seems a little outdated now, though. For example, the option is currently --prerelease rather than --pre-release, and it needs to be used together with --bump.
Other than that, it works very well for my use case. Thanks for rebasing it!
Activity
welcome commentedon Feb 24, 2026
Thanks for opening your first issue at git-cliff! Be sure to follow the issue template! ⛰️
orhun commentedon Feb 25, 2026
This sounds reasonable. However there are still some cases to think about:
--bump --pre-release alpha<initial_tag>-alpha.0, right? But what if e.g.<initial_tag>is0.1.0-alpha.51.2.0-beta.2--bump --pre-release beta1.2.0-beta.3or1.2.1-beta.0?1.2.0-rc.3--bump1.2.0instead of1.2.1, right?1.2.0-alpha.2--pre-release beta1.2.0-beta.0?1.2.0-beta.3--pre-release alpha1.2.0-beta.4?1.2.0-rc.0,1.2.0-rc.2--pre-release rc1.2.0-rc.3or fill gap withrc.1?1.2.0-beta.2+build.45--pre-release beta1.2.0-alpha.1.2--pre-release alphav1.2.0--pre-release betav1.3.0-beta.0(preserve prefix?)1.2.0-beta.3(skipped viaskip_tags)--pre-release beta0.3.0-beta.2--bump major --pre-release alpha0.4.0-alpha.0or1.0.0-alpha.0?1.2.0-beta.2,1.2.0--pre-release rc1.3.0-rc.0or reuse1.2.0?anagno commentedon Feb 25, 2026
I would say:
--bump --pre-release alpha1.2.0-beta.2--bump --pre-release beta1.2.0-beta.3. This helps with pipelines or instructions. You know from the beggining that the counting will be correct1.2.0-rc.3--bump1.2.0-alpha.2--pre-release beta1.2.0-beta.0. beta is greater than alpha, so we can just start counting from 01.2.0-beta.3--pre-release alpha1.2.0-beta.4. Or if not possible just reject it and warn the user for the mistake ?1.2.0-rc.0,1.2.0-rc.2--pre-release rc1.2.0-beta.2+build.45--pre-release beta1.2.0-alpha.1.2--pre-release alphav1.2.0--pre-release betav1.3.0-beta.0. What happens to the normal tags ? I would keep the same behavior, as the normal tags1.2.0-beta.3(skipped viaskip_tags)--pre-release beta0.3.0-beta.2--bump major --pre-release alpha0.3.0with--bump major? If it the result is0.4.0, then we increment to0.3.0-beta.3(because the0.3.0-beta.2 --bump majorshould produce0.3.0). If the result is1.0.0, then we can start with1.0.0-alpha.0.1.2.0-beta.2,1.2.0--pre-release rc1.3.0-rc.0anagno commentedon Feb 25, 2026
One more comment for the
1.2.0-beta.2+build.45use case. Apparently it is specified in the specs:Build metadata MUST be ignored when determining version precedence. So after that I would say it should be ignored/preserved. So something like1.2.0-beta.3+build.45. What doesgit-cliffcurrently does with build metadata?ognis1205 commentedon Feb 25, 2026
I think the interaction between
--bumpand--prereleasewill likely require quite a bit of design discussion, and it's not entirely clear yet whether (or how) we want to support all those edge cases.As a first step, I would suggest starting with a smaller and more well-scoped change: extending the existing
--bumpoption to supportprereleaseas a version type, similar to the currentmajor,minor, andpatchoptions:This would likely require clarifying some details around
next_version, but overall the semantics seem much less ambiguous compared to introducing a separate--prereleaseflag and defining its interaction with--bump.Once that is in place, we could then iterate on more advanced prerelease workflows if needed.
anagno commentedon Feb 25, 2026
@ognis1205 Would something similar to your comment be ok ?
For pre-releases we will need the type, so it has to specified.
ognis1205 commentedon Feb 25, 2026
@anagno
The implementation sketch you shared is about handling the dependency between
--bumpand--prerelease. What I am proposing here is slightly different. I'm focusing on addingPrereleaseas a new variant toBumpType:git-cliff/git-cliff-core/src/config.rs
Lines 311 to 318 in e7e89c4
Since we already rely on the
next_version crate, which extendssemver::Versionand provides prerelease support via theNextVersiontrait, we can leverage that implementation directly:https://docs.rs/next_version/0.3.1/next_version/trait.NextVersion.html
My idea is:
prereleaseas a valid value to--bump--prereleaseyetThis way, we can introduce
--bump prereleasein a minimal and well-scoped manner without blocking on the full--prereleaseCLI design. Then, the detailed behavior and interaction between--bumpand--prereleasecan continue to be discussed in this tracking issue.ognis1205 commentedon Feb 25, 2026
I think we should first define what
--bump prereleasemeans in isolation, before defining how it interacts with other flags or edge cases.That said, even the semantics of
--bump prereleaseitself might turn out to be more complex than it initially appears. A prerelease is technically not a version "level" likemajor/minor/patch, but rather an identifier attached to a version. Because of that, modeling it as a--bumptype could introduce some conceptual distortion in the design and it might not even be the best abstraction for this feature.As we can already see from the combination tables discussed here, the number of cases this feature would need to cover is larger than it might seem at first glance. So it may be worth carefully scoping what we want the initial behavior to guarantee before expanding it to handle all edge cases.
ognis1205 commentedon Feb 25, 2026
I'm curious how this has been handled in practice so far.
For example, in @ratatui , how were prerelease changelog managed @orhun ?
ognis1205 commentedon Feb 25, 2026
Ah, I took another look at the current implementation, and it seems that the existing
--bumpbehavior already covers what I was trying to propose here (--bump prerelease).So there's no need to introduce
Prereleaseas a newBumpTypeafter all. Sorry for the noise, please disregard this suggestion.ognis1205 commentedon Mar 10, 2026
Sorry for the slow progress here. I'll take another look at the proposal again. My current feeling is that we should try to keep the solution and semantics as simple as possible.
17 remaining items
Cyclonit commentedon Apr 14, 2026
So, I took my time reading through all of the comments and to be frank, I think we are in an area of overcomplicating a solution to a problem that doesn't really exist. @anagno's initial proposal was simple and clean. Just introduce a pre-release tag and only consider tags that do match a simple pattern of
<semver>-<pre-release tag>.<sequence nr>. If people want to embed even more information in their version numbers (which I would strongly advocate against), they simple leave the realm of what can reasonably be supported without over-complicating the situation.Also, I didn't go through the exercise of creating tables myself, but they feel like you just went through all possible permutations of tags and parameters and are trying to make sense of them. But that doesn't work. We need to think about the workflows that drive use of git-cliff and result in a much more limited set of reasonable combinations of parameters. And all of those make sense to me. The only question is whether git-cliff should spent effort on detecting unreasonable combinations and hold the user's hand or whether we enter undefined behaviour.
I would go integrate the simple schema proposed here. It allows using git-cliff for versioning in a slightly more elaborate setup than the tool can support until now, without causing a mess.
anagno commentedon Apr 17, 2026
@orhun @ognis1205 The #1345 is implementing the simpler logic. I would suggest either to take a look on the PR or if it is not something that you would like to support let`s close the PR
orhun commentedon Apr 25, 2026
Going to come back to this for 2.14.0
harlequin commentedon Sep 10, 2026
I have read that this topic is moved into the 2.15.0 milestone. Do you have an estimation when it will be ready?
orhun commentedon Sep 18, 2026
I'm not sure... we need to either rebase #1345 or come up with another approach.
I think that PR is a good start though.
WDYT? Does that satisfy your use case?
harlequin commentedon Sep 19, 2026
Yes, this would be brilliant. If you would generate a preview version (a release candidate 😁) I can test it.
Illustar0 commentedon Sep 19, 2026
For my use case, #1345 already meets my needs. Perhaps we could simply rebase that PR?
I'd also be happy to test a preview release!
anagno commentedon Sep 22, 2026
I rebased the PR, so whoever wants can give it a try
Illustar0 commentedon Sep 23, 2026
I built the rebased PR and gave it a try — it works great!
The PR description seems a little outdated now, though. For example, the option is currently
--prereleaserather than--pre-release, and it needs to be used together with--bump.Other than that, it works very well for my use case. Thanks for rebasing it!
chore: release with cargo-release instead of release.sh (#500)
anagno commentedon Oct 20, 2026
@harlequin @orhun Any input/suggestions for the open PR ?
harlequin commentedon Oct 28, 2026
Perfekt, please merge