Add new capabilities to cz version

Description

The idea of this ticket is to track the "graduation" of cz version --project into a powerful command, capable of fetching information about the project.

This includes:

Introduce --next flag on cz version --project. Which returns the next version based on the project's config. It could potentially support forcing the increment type. Example: --next=MAJOR or --next=PATCH Introduce --next flag on cz version --project #1678
Allow users to play with the configured version_scheme, by letting them provide any version, cz version <version_arg>, this would override the commitizen version or the given --project parameter. The user would then be able to "learn" about the behavior, by doing cz version 0.1.0 --next=MAJOR Add support for cz version <version_arg> #1679
Add --tag: to actually retrieve the tag of the version with the template applied. If your tags looks like this: v0.1.0. You have to manually add v to your version right now. This would be useful to interact with git. If you want to retrieve the tagged commit, you could do: git show-ref $(cz version -p --tag). This is useful for auditing. And, if you have an old CI (e.g: jenkins), it would give an easy way for teams to check if the tag exists already before trying to bump. This parameter is the one I'm least sure about, so maybe we can work on the other features first, and if we think it would be useful, we add it.Add cz version --tag #1765
Do we want a --hash to get the version hash for auditing purposes?
BREAKING: Add --version back and deprecate cz version --comitizen which is the default for cz version

#1640

Add --tag

I have a use for this.
Due to some weaknesses in the current published action, I've had to write my own action, and I'm having to do manual tag formatting.

Additionally, I would probably have a use for a --prev flag, to get the most recent previous revision. This is potentially for regenerating incremental changelogs when running on a tag; the tag would be the "current" version, so the version to start from the previous one.

if we have --next, --prev is indeed something we can consider IMO 👀

Additionally, I would probably have a use for a --prev flag, to get the most recent previous revision. This is potentially for regenerating incremental changelogs when running on a tag; the tag would be the "current" version, so the version to start from the previous one.

I'm not sure I full understand this, what about this:

current=cz version -p
cz bump --yes
next_version=cz version -p 
cz changelog $next_version --dry-run > incremental-changelog.md

And by the way, I've introduced a new, more flexible github action, maybe it's useful to you
https://github.com/commitizen-tools/setup-cz

I'm not sure I full understand this, what about this:

... Somehow I'd missed the ability to pass a revision name to cz changelog, which would cover my needs for this case

And by the way, I've introduced a new, more flexible github action, maybe it's useful to you

This will enable me to simplify what I had to write, thank you.

@Clockwork-Muse

@Clockwork-Muse would you still need the --tag flag given this new information?

Yes.

My current workflow is:

Get current/next version
Format externally into tag format (need flag for this step)
Generate changelog (if any)
Call build process, passing in version/changelog (c# + docker)
If there's a new version, create a GitHub release (via SoftProps action).

I do not call cz bump, because I don't update files or create a bump/version commit; I only manage my versions with tags. Therefore the only way for me to get the new tag would be the new flag

Note that the only reason I'm having to get the tag myself is because, at least previously, the only way to get the "next tag" with the official release action was to bump and update files/create a new commit, which wasn't acceptable for me. If the official action could be fully configured to only create (+push?) the tag and/or create the release, I probably don't need this flag (only the ability to get the version)

@Clockwork-Muse

Cross-checked against master (v4.15.1) by a claude-opus-4.7 validation pass while triaging #1976.

Status: partially fixed (umbrella tracker — most sub-tasks shipped, three remain).

Sub-task	Status
`--next` on `cz version --project` (#1678)	partial — forced-increment form works (`commitizen/commands/version.py:93-103`), `USE_GIT_COMMITS` form still TODO at `commitizen/commands/version.py:85-91`
`manual_version` positional override (#1679)	shipped — `commitizen/cli.py:588-594`, `commitizen/commands/version.py:60-83`
`--tag` to apply tag template (#1765)	shipped — `commitizen/cli.py:562-567`, `commitizen/commands/version.py:116-120`
`--major` / `--minor` / `--patch` extractors	shipped — `commitizen/cli.py:544-576`, `commitizen/commands/version.py:105-113`
`cz --version` top-level + deprecate `cz version --commitizen` (#1785)	in flight — PR #1798 (open, `mergeable_state: blocked`)
`--hash` (emit commit hash for the version)	not implemented, no follow-up issue found
`--prev` (raised by @Clockwork-Muse, ack'd by @Lee-W)	not implemented, no separate ticket

Recommend keeping this open until #1678, PR #1798 (#1785) land and a decision is made on --hash and --prev.

(Surfaced via the round-3 triage in #1976.)

Navigation Menu

Add new capabilities to `cz version` #1677

Description

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add new capabilities to cz version #1677

Description

Description

Activity

Clockwork-Muse commented on Dec 3, 2025

Lee-W commented on Dec 4, 2025

woile commented on Dec 4, 2025

Clockwork-Muse commented on Dec 4, 2025

woile commented on Dec 12, 2025

Clockwork-Muse commented on Dec 12, 2025

bearomorphism commented on May 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Add new capabilities to `cz version` #1677