Tags mangled in CHANGELOG.md

[mattmartini]

Is there an existing issue for this?

• I have searched the existing issues

Description of the bug

I use git tags of the form: version/1.2.3 or version/v2.4.6. Recently when I run git cliff > CHANGELOG.md the word version becomes ersion in the CHANGELOG.md file. For ecample:

Given a git log snip that looks like:

* 051ceac -  (tag: version/1.0.16) fix(errors) Allow multiple errors to be cleared (2 months ago)

[ersion/1.0.16] - 2025-08-21

🐛 Bug Fixes
 • Fix(errors) Allow multiple errors to be cleared

when it should be:

[version/1.0.16] - 2025-08-21

🐛 Bug Fixes
 • Fix(errors) Allow multiple errors to be cleared

Steps To Reproduce

Build: cargo install git-cliff
Run: git cliff > CHANGELOG.md

The problem occurs independent of running the command having a cliff.toml in the directory or not.

Expected behavior

The tags should be:
[version/1.0.16] - 2025-08-21

and not:
[ersion/1.0.16] - 2025-08-21

Screenshots / Logs

No response

Software information

• Operating system: MacOS 15.6.1 (Sequioa)
• Rust version: rustc 1.90.0 (1159e78c4 2025-09-14) (Homebrew)
• Project version: git-cliff 2.10.1

Additional context

No response

[ognis1205]

I guess the issue was caused by this config (either the default cliff.toml or yours):

git-cliff/config/cliff.toml

Line 10 in 85cc05d

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

Please try removing the trim_start_matches(pat="v") part and check the result.

[mattmartini]

Yes, that fixed the problem.

The line now looks like:

    ## [{{ version }}] - {{ timestamp | date(format="%Y-%m-%d") }}

Will this change be made in the default cliff.toml?

[ognis1205]

@mattmartini

Personally, I think having this kind of setting in the default cliff.toml can actually be useful — it serves as a suggestive example when users customize their own changelog format to suit their preferences. So I don't think it's necessarily a problem to keep it as is.

That said, I can see how it might be confusing for users who just rely on the default configuration, like in this case.
I'm neutral on whether it should be changed, but it might be worth checking with @orhun for the final decision.

[orhun]

Ah yeah, good catch!

I believe this might be a bit confusing for new users so we should definitely change this or note it somewhere.
I don't think removing this is a good solution.

I propose adding a new/custom Tera filter for:

• Checking if the given input has a single v (e.g. v1.2.3 vs version/1.2.3)
• If so, removing the prefix (v1.2.3 -> 1.2.3)
• If not, do nothing (version/1.2.3 -> version/1.2.3)

It might look something like this:

{{ version | trim_prefix(pat="v") }}

For this custom filter implementation, we can do something like upper_first:

git-cliff/git-cliff-core/src/template.rs

Lines 48 to 57 in 706551f

	/// Filter for making the first character of a string uppercase.
	fn upper_first_filter(value: &Value, _: &HashMap<String, Value>) -> TeraResult<Value> {
	let mut s = tera::try_get_value!("upper_first_filter", "value", String, value);
	let mut c = s.chars();
	s = match c.next() {
	None => String::new(),
	Some(f) => f.to_uppercase().collect::<String>() + c.as_str(),
	};
	Ok(tera::to_value(&s)?)
	}

It's also documented here: https://git-cliff.org/docs/templating/syntax

What do you think? (We should probably track this in a separate issue if we all agree)

Thanks for helping debugging this @ognis1205

[mattmartini]

Your trim_prefix idea seems like the way to go.

I personally use versions of the form v1.2.3 for perl development, and of the form 1.2.3 for bash, python, and ruby development. Removing the initial v is not critical for me, but retaining it in version (as opposed to ersion) is important.

[orhun]

Sounds good!

I think we should create a new issue for trim_prefix filter then.

Are you interested in contributing btw? (no problem if not :))

[mattmartini]

I am not (yet) a Rust developer. So not at this time.

[linus-skold]

@orhun Wouldn't it be a potential issue if you have the version string and run trim_prefix(pat="v"), technically it would still replace the v at the start of the string and consider it a prefix?

I believe we would be missing context unless its a specialized trim_prefix for versions only.
Either we would need to add a denominator to signify when the prefix ends, or we would specify a length of the prefix, which would be less ideal.

Maybe replace_regex has a place here or just a new regex function for prefixes specifically. The regular rust crate for regex does not support lookaheads as it is right now, https://github.com/fancy-regex/fancy-regex does support it but by rewriting it into a rust compatible format and running it through the regular crate and then doing a fixup on the matches.

[orhun]

Wouldn't it be a potential issue if you have the version string and run trim_prefix(pat="v"), technically it would still replace the v at the start of the string and consider it a prefix?

I'm not sure what you mean. If you have v1.2.3 then yes, it would be replaced. Otherwise (version-1.2.3) it won't be replaced.

Either we would need to add a denominator to signify when the prefix ends, or we would specify a length of the prefix, which would be less ideal.

Maybe replace_regex has a place here or just a new regex function for prefixes specifically. The regular rust crate for regex does not support lookaheads as it is right now, https://github.com/fancy-regex/fancy-regex does support it but by rewriting it into a rust compatible format and running it through the regular crate and then doing a fixup on the matches.

Interesting... this definitely needs a more robust solution I agree.

But I still think we could benefit from a simple filter.