.config/

Keep tool config in .config/

A convention for project tools: look for configuration in.config/ as well as the project root.

Why

On GitHub, the README comes after the file list. In a project with a lot of tooling, that list can look like this:

That's 27 entries before the README, and src/ anddocs/ are two of them. The Node.js tooling group raised the same complaint in 2020.

If tools also look in .config/, projects can gather those files in one place, much as .github/ already holds GitHub's files, without passing a custom path to every command, editor and CI job.

Before
  • project/
    • src/
    • .ansible-lint
    • .mill-version
    • .rubocop.yml
    • doc8.ini
    • pyproject.toml
    • README.md
After
  • project/
    • .config/
      • .rubocop.yml
      • ansible-lint.yml
      • doc8.ini
      • mill-version
    • src/
    • pyproject.toml
    • README.md

For tool authors

  1. Look for .config/<tool>.<ext>, or.config/<tool>/ when the tool has several files.
  2. Keep supporting existing locations and explicit paths. Document which file wins when more than one exists.
  3. Document how the project root is found and how relative paths inside the config are resolved.

Tools that support it

These tools find their configuration in .config/ without being given a path. Some accept more filenames than shown here; see each link for details.

Don't see a tool you use?

If it already supports .config/, add it to the list. If it doesn't, you can ask its maintainers.

Search before you ask

Then you can start from this text, and edit it to fit the tool:

Would you consider also looking for this tool's configuration in `.config/`?

Many projects end up with a pile of tool config files in their root. Tools such as mise, RuboCop, Prisma, Stylelint and cargo-nextest also look in `.config/`, so projects can group these files without passing a path to every command. Existing locations would keep working.

See https://dot-config.joshka.net for details and the list of supporting tools.

Questions

These came up when the problem was discussed on Hacker News in 2020 and 2023.

Isn't this just moving the mess?

Yes. The files are all still there, one click away, and the root listing gets shorter. GitHub already does this with.github/.

Isn't this for GitHub or my editor to fix?

A setting in one viewer only changes that viewer. A folder is part of the repository, so anyone who clones it or opens it on another host sees the same layout.

Why not just use fewer tools?

That helps, but even a project with a few tools ends up with a few config files, and each one goes in the root.

Why hide it behind a dot?

On Linux and macOS, ls and Finder hide dot-folders by default, which keeps tool settings out of everyday listings. They aren't secret, though. ls -a, your editor and GitHub all show the folder, and it's committed like any other file. The dot also keeps it apart from config/, which plenty of applications use for their own settings.

Why not put it all in package.json or pyproject.toml?

Where a tool supports that, use it. Many tools don't, and plenty of projects have more than one manifest or none at all.

Won't people have to guess where the config is?

Tools keep reading their existing locations and document which file wins, and a project only moves a file once its tool supports the new location. If the file has relative paths in it, check those when you move it.

Isn't this XDG, or another competing standard?

The XDG Base Directory specification covers per-user settings in ~/.config/. A project's .config/ lives in the repository and is shared by everyone working on it. Tools keep their existing file formats.

Should everything move?

No. Keep manifests, lockfiles, .gitignore and.editorconfig where the tools that read them look for them.