Support processing the commits starting from a specific tag

[landerss1]

Is there an existing issue or pull request for this?

• I have searched the existing issues and pull requests

Feature description

Currently, there's support for processing commits starting from the current or latest tag, or commits without any tag, but not starting from a specific tag. This would make the transition from unconventional commits to conventional commits much smoother. Then, you could keep the old changelog as, e.g. HISTORY.md, and then start a new CHANGELOG.md based on commits after a specific tag.

Desired solution

Introduce a new command-line argument that can be used to specify the tag that should be used to start fetching commits from.

Alternatives considered

Can't think of any.

Additional context

No response

[welcome]

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

[orhun]

Hello!

Have you tried the git range option?

e.g.

git cliff v0.1.0..HEAD

Or even more shorter:

git cliff v2.2.1..

Other examples:

git cliff 4c7b043..a440c6e
git cliff 4c7b043..HEAD
git cliff HEAD~2..

I think this is what you are looking for :)

[landerss1]

Ah, Thanks. I saw the range CLI argument in the docs, but there was no description or examples. I have tried it now, and it solves my problem, but you have to go one tag further back than expected, so you have to specify range start=<desired-tag>-1. Is this what's to be expected?

[orhun]

I think yes, since git ranges work like that. It is handled by the underlying git library (git2).

I expanded the examples in d451252

[lermontex]

@orhun, as far as I understand, git ranges will conflict with the --unreleased, --latest, etc. flags, so git ranges is not entirely suitable, since it will not allow flexible configuration

It would be great if it was possible to specify the tag from which to start the story

There is an initial_tag parameter in the configuration, maybe it’s worth using it?

https://git-cliff.org/docs/configuration/bump/#initial_tag

[orhun]

as far as I understand, git ranges will conflict with the --unreleased, --latest, etc. flags, so git ranges is not entirely suitable, since it will not allow flexible configuration

Yeah, using those flags will override the commit range.

Can you give me an example case (i.e. git history) to make this matter more clear? I'm happy to implement it as long as we have the correct behavior with test fixtures in place.

There is an initial_tag parameter in the configuration, maybe it’s worth using it?

initial_tag option is related to the bump configuration and I don't think it is suitable for this case.

[lermontex]

@orhun, sorry for the delay in replying

A simple example: we have a repository that does not adhere to Conventional Commits (or partially adheres). We want to display history only from a certain tag (when we decided that we will strictly follow the rules)

At the moment, it can only be done this way:
git-cliff v1.0.0.. --bump --output "CHANGELOG.md"

It would be handy if the initial tag v1.0.0 could be fixed in the configuration, rather than having to be specified each time git-cliff is run

[orhun]

Ah I see, you basically want a new configuration option for the commit range.

It seems like an overly specific case though, maybe instead we can support an environment variable such as GIT_CLIFF__RANGE . Would that be useful for your case?

[lermontex]

@orhun, unfortunately, I don't understand how I can use an environment variable in this case and how it will be better than the current option, when we specify the tag directly in the console command

Basically, I want to configure git cliff so that the history always starts with a certain GIT tag, so I would like to worry about this only once

If this seems like a rare use case, here is another example: we want to have several branches (1.0, 1.1, ... 2.0) and each of them should have its own changelog:

1.0 - CHANGELOG-1.0.md
1.1 - CHANGELOG-1.1.md
...
2.0 - CHANGELOG-2.0.md

Something like here:
https://github.com/symfony/symfony

If it were possible to specify the starting tag, we could configure each branch using cliff.toml so that it does not include changes from previous branches

Hopefully this is a more common use case :)

[orhun]

I see... then we can probably add a new option to the configuration file as follows then:

[git]
range = "1.0.0" # new option
output = "CHANGELOG-1.0.md" # this is already supported

How does this look to you?

[Cyclonit]

What about two options git.ignore_before and git.ignore_after (or include_after and include_before) instead? That would give you all the flexibility you might need.

[lermontex]

@orhun, yeah that would be great! Basically we could just allow the range parameter to be set directly in the config file, then we could use something like this:

[git]
range = "v1.0.0.."
output = "CHANGELOG-1.0.md" # this is already supported

@Cyclonit, note that in the range parameter you can specify a range of values, so most likely there is no need to use 2 config parameters

git cliff 4c7b043..a440c6e
git cliff 4c7b043..HEAD
git cliff HEAD~2..
git cliff v2.2.1..
git cliff v0.1.0..HEAD

https://git-cliff.org/docs/usage/examples/

Although, there is currently no way to specify whether the specified range should include the specified commits/tags? Unfortunately I couldn't find an example