feat: support more configuration files

[danielpza]

Description

Motivation and Context

Fixes #1446

How Has This Been Tested?

Screenshots / Logs (if applicable)

Types of Changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation (no code change)
• Refactor (refactoring production code)
• Other

Checklist:

• My code follows the code style of this project.
• I have updated the documentation accordingly (if applicable).
• I have formatted the code with rustfmt.
  • cargo +nightly fmt --all
• I checked the lints with clippy.
  • cargo clippy --tests --verbose -- -D warnings
• I have added tests to cover my changes.
• All new and existing tests passed.
  • cargo test

[codecov-commenter]

Codecov Report

❌ Patch coverage is 50.00000% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 47.65%. Comparing base (775beb0) to head (b53b9df).
⚠️ Report is 19 commits behind head on main.

Files with missing lines	Patch %	Lines
git-cliff/src/lib.rs	0.00%	3 Missing ⚠️
git-cliff-core/src/config.rs	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1448      +/-   ##
==========================================
+ Coverage   47.57%   47.65%   +0.08%     
==========================================
  Files          24       24              
  Lines        2119     2122       +3     
==========================================
+ Hits         1008     1011       +3     
  Misses       1111     1111              

Flag	Coverage Δ
unit-tests	47.65% <50.00%> (+0.08%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[orhun]

Thanks for the PR! Just wanted to say this goes into the right direction. Let me know when this is ready for review

[danielpza]

Thanks for the PR! Just wanted to say this goes into the right direction. Let me know when this is ready for review

Hey! I think the current code should work, but I want to explore a few changes first to make it a bit more robust.

I'll be away for a couple of weeks though. I'll let you all know when it's ready. Or you can give it a try yourself if you are inclined.

Cheers.

[danielpza]

Hey @orhun, it should be good for review now. I added a couple of tests and updated the documentation to cover the changes.

I did notice there are some inconsistencies in how the configuration files are loaded, but I decided to leave that out of the scope of this PR. Eg:

• The current configuration file (cliff.toml) is read from workdir (if set), but the same doesn't apply when searching the configuration in the parent directories. For the parent directories it always searches up from env::current_dir()

• The order it loads the configuration files it's not intuitive imo:

  • it searches for the cliff.toml file (or args.config) in current directory or workdir if set (project configuration file)
  • searches for user configuration file in home directory (user configuration file)
  • searches for cliff.toml in parent directories. (project configuration file)

  I would expect it to search for project configuration files (including current and parent directories) first and then to search for the user configuration file

Related code

Let me know your thoughts.

[orhun]

I'm not sure if separating this section as Project and User Configuration makes sense here. What was the reasoning behind it?

[danielpza]

I wanted to avoid confusion since the naming convention for project and global user configurations are different.

Since the global user configuration is already scoped to git-cliff namespace, it doesn't make sense for additional scoping.

• ✔️ /home/<user>/.config/git-cliff/cliff.toml
• ❌ /home/<user>/.config/git-cliff/.cliff.toml unnecessary scoping, other programs (git, mise, etc) don't follow this convention
• ❌ /home/<user>/.config/git-cliff/.config/cliff.toml unnecessary scoping, other programs (git, mise, etc) don't follow this convention

I also used https://mise.jdx.dev/configuration.html#global-config-config-mise-config-toml as reference, they have a more detailed section for all the configuration files possible locations and patterns, and how they differ from each other.

[Cyclonit]

I think it would be cleaner to just list the actual paths it will search through instead of filenames and trying to explain relative path situations. E.g.

• ./cliff.toml
• ./.cliff.toml
• ./.config/.cliff.toml
• ~/cliff.toml
• ~/.cliff.toml
• ~/.config/.cliff.toml

A bit more verbose, but easier to understand than trying to deduplicate parts of the paths.

[ognis1205]

Thanks for the PR!

This is slightly tangential to the changes in this PR, but I wanted to share a broader design thought.

From my perspective, git-cliff is fundamentally a project-level tool, and its configuration should ideally be tied to the repository to ensure reproducibility. In that sense:

• The presence of sections like remote in cliff.toml suggests that the config is repository-specific
• We already support generating a project-local config via git cliff --init
• Keeping configuration within the repository helps maintain consistency across environments

Given that, supporting xdg / os-specific config directories might introduce additional maintenance overhead while providing relatively limited benefit, and could blur the intended design direction.

Personally, I would even consider deprecating user-level cliff.toml at some point, if it aligns with the overall direction of the project.

Curious to hear what others think. cc: @orhun

[ognis1205]

I think the doc comment /// is unnecessary here since this is a test. The function name already explains the intent well, so we might not need an additional comment here.

This comment seems to describe the behavior of retrieve_project_config_path rather than the test itself. It might be better to move it to the function as a doc comment.

[danielpza]

I don't have a strong opinion either way. @orhun suggested moving it there #1448 (comment). What's the consensus/best practice here?

[danielpza]

updated in b53b9df