Discussion: Supporting Multiple Repositories in git-cliff

[ognis1205]

I would like to start a discussion about supporting multiple repositories in git-cliff.

Based on my investigation, there are several concerns:

• Even if multiple repositories are supported, only a single cliff.toml configuration file can be applied.
  • This means that settings such as tag_pattern or include_path cannot be configured per repository.
  • Relatedly, only a single remote is supported, so metadata from all repositories cannot be fully retrieved.
• Even with multiple repository support, the program is still controlled using the same workflow as for a mono-repo.
  • As a result, generating changelogs from multiple mono-repos can become extremely complex unless the implementation is carefully designed.
  • Controlling this solely through option combinations is difficult.
  • In addition, the information output in the logs may be inaccurate in the current implementation (e.g., remote data sources).

Considering these concerns, possible approaches might include:

• Allowing per-repository settings in cliff.toml.
• Introducing subcommands for different workflows, e.g., one for multiple repositories and one for mono-repos, to provide better control.
• Implementing a subcommand for merging changelogs (context-level merge), which could support editing at the context level.

I’d like to hear thoughts from the community on these points and possible directions for implementation.

[ognis1205]

Do you know if there are any other changelog generators that currently support multiple repositories?

[orhun]

I don't think so

[orhun]

Yeah I agree that having only --repository argument for different repositories is not sufficient as of now. We should improve it for sure.

I believe allowing per-repository settings in cliff.toml would be the best approach. Maybe something like:

[changelog.repository."repo-1"]

[git.repository."repo-2"]

etc.

Implementing a subcommand for merging changelogs (context-level merge), which could support editing at the context level.

I'm not sure how that would look like but definitely an intriguing idea!

[ognis1205]

For the idea of adding per-repository settings in cliff.toml, my thinking was:

• The existing top-level entries in cliff.toml would serve as the base configuration.
• Settings defined under each repository entry would override those base values.

As for the subcommand approach, what I had in mind was something like:

 $ git-cliff merge --contexts repository1.json repository2.json

-> a merge subcommand that can combine multiple contexts.

Or:

 $ git-cliff dryrun --repository repository1

-> a dryrun command to validate whether the values specified via cliff.toml or CLI options are correct (e.g., checking if the repository defined under repository actually exists as a Git repository).

[orhun]

Settings defined under each repository entry would override those base values.

Yeah, I think that's better.

-> a merge subcommand that can combine multiple contexts.

What is this command going to do exactly? Just merge the JSON fields and spit out the merged output. It feels too specific imo

(e.g., checking if the repository defined under repository actually exists as a Git repository).

Not sure if this is necessary. It will throw an error if the repository does not exist anyway

[ognis1205]

Currently, git-cliff searches for cliff.toml starting from the command directory and stops at the first one it finds in parent directories. One idea I had was to instead merge all cliff.toml files encountered while traversing up the directory tree, so that settings closer to the command directory would override higher-level ones.

Do you think this could be a reasonable approach, or would it likely cause confusion in practice?

[orhun]

I think that would be confusing, especially if you accidentally hit this

[ognis1205]

Okay. Given that we're currently working on the repository/directory–related changes, I think it would be more practical to revisit the idea of per-repository settings in cliff.toml after we see the outcome of that implementation. At the very least, I believe we've reached consensus that with the current configuration design, it's not possible to cover the needs of multi-repository setups.

[jkellz-dev]

Ok, I just hit this. I would love to have a single cliff.toml that I can dump all my configuration for multiple repositories in. This allows me to aggregate our entire polyrepo platform and provide a unified view of changes. I don't think we need it to aggregate multiple cliff.tomls and make some inheritance hierarchy. That would be highly confusing and kind of antithetical to how engineers wanting a bird's eye view of an entire platform would want to look at the data, vs an engineer only looking at a single repo.

Ideally for me, I would want a single configuration with possible overrides for each repo in a single place, so that I can pass minimal command line flags. This would both be helpful for me as an engineer, then useful as we move this into a CI step. Any changes I make to configuration then apply to the CI pipeline.

Anything I can do to help this work effort out?

[orhun]

I think what you proposed is similar to what I said in #1258 (comment)

If so, we need a PoC PR and we can basically go from there. See the config module as a starting point.