Naming convention & dir structure under `.config`

[bbatsov]

We recently added support for .config in RuboCop, but a question was brought up about whether tools are expected to go for:

• .config/.tool-config
• .config/tool/config
• .config/tool-config

See https://github.com/rubocop/rubocop/pull/12700#issuecomment-1949352779 for more context.

[bkuhlmann]

Hey. :wave: Popping in here because I maintain the Runcom gem which is essentially the Ruby implementation of what this project is all about. I wanted to mention that, per the XDG specification, it should be .config/tool/configuration.[xml|ini|toml] if that helps. This is what Runcom provides for support out of the box in case that helps.

[Splines]

Also see this repo for proposed naming conventions.

I like how it's implemented in RuboCop as per this comment: they support .config/.rubocop.yml or .config/rubocop/config.yml. While the latter conforming with the XDG specification according to bkuhlmann, I like the former more as most tools will only have one single config file and thus having a separate folder for each of them inside the .config folder seems like unnecessary clutter to me.

[bkuhlmann]

Splines: Keep in mind that while having a single (i.e. .config/.rubocop.yml) is fine for the basic use case, in practice, this never works out well. This is why having .config/rubocop/config.yml gives full expansion and why XDG is so powerful. In my case, the former solution won't work because I need the following:

• .config/rubocop/config.yml: Primary configuration.
• .config/rubocop/issue.yml: Outstanding issues that need addressing.

I suspect others will be in this boat as well.

[Splines]

Ah ok, good use case. Ideally, tools could support both (a direct config file in the .config folder and nesting). Since I still think there are many tools that only need one single configuration file. But having the flexibility to add a nested folder is of course great for bigger applications that might require multiple config files like you described.

[jasonkarns]

I'm an avid XDG fan. I generally agree with @bkuhlmann to avoid .config/.tool-config as that approach is less flexible and prevents any future desire or need to have a second file. Hence the .config/rubocop/ directory being the most flexible and future-proof approach.

However, the number of tools that would be filling a project .config directory is much less than what would be filling a user ~/.config directory. Given that a typical project has on the order of a dozen or so hidden config files in their project root, the addition per-tool directory nesting within the project seems unnecessary. Even with a 2-3 files per tool, it seems reasonable to leave them all directly in .config.

As a bonus, this reinforces the existing legacy filenames (though without their leading dot); which can make for searching/grepping more user friendly. (Based on tools or options that may only list the file basename, having a list of a handful of files all named "config" wouldn't be great.)

All that said, there is much to be said for the benefit of having ones project .config and their XDG ~/.config directory trees reflect the same patterns. Perhaps it's best if this project outline the tradeoffs and leave it to the tools to decide what makes sense? For instance, tools that don't have or support a user-level config would gain nothing from consistency with ~/.config. And tools that will likely only ever have a single file would gain little from the future proofing of tool-directory nesting.

[bkuhlmann]

Jason: Yeah, one thing worth noting about dealing with directory/file structures between global (i.e. ~/.config) and local (i.e. <project>/.config) is if you use a directory structure for global but not local, then you have a bit of a maintenance nightmare for tool maintainers which want to remain consistent with XDG. This is much easier to maintain as engineer who maintains multiple tools:

• Global: ~/.config/<tool>/configuration.yml
• Local: <project>/.config/<tool>/configuration.yml

Notice the top-level directory changes but the sub directory structure doesn't. I raise this point because swapping/subbing out <global_or_local_root_path>/<tool>/configuration.yml for the path is much easier to deal with than having to check is the global path is slightly different then the local path when needing to compute and/or fallback to the global path when the local path doesn't exist. This is was one of the reasons for implementing the Runcom gem so fellow engineers could get this benefit automatically.

In summary, what I'm trying to highlight here is there is a dance between being a maintainer of a tool that adheres to XDG and a user of the tool in terms of where configuration information can be found. I tend to lean towards consistent path structures but also see your point about not wanting to have sub-directories in your local project configuration.

All: If it helps, I highlight some of these concerns in my XDG Base Directory Specification article which might be of interest because it illustrates how this can get messy if not done right.