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:
- .github/
- docs/
- src/
- tests/
- .editorconfig
- .eslintrc.json
- .gitattributes
- .gitignore
- .lefthook.yml
- .markdownlint.json
- .mise.toml
- .nvmrc
- .prettierignore
- .prettierrc
- .release-it.json
- .stylelintrc.json
- CHANGELOG.md
- commitlint.config.js
- CONTRIBUTING.md
- cspell.json
- LICENSE
- package.json
- pnpm-lock.yaml
- prisma.config.ts
- README.md
- tsconfig.json
- vitest.config.ts
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.
- project/
- src/
- .ansible-lint
- .mill-version
- .rubocop.yml
- doc8.ini
- pyproject.toml
- README.md
- project/
- .config/
- .rubocop.yml
- ansible-lint.yml
- doc8.ini
- mill-version
- src/
- pyproject.toml
- README.md
- .config/
For tool authors
- Look for
.config/<tool>.<ext>, or.config/<tool>/when the tool has several files. - Keep supporting existing locations and explicit paths. Document which file wins when more than one exists.
- 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.
- .NET local toolsRepository-local toolsOnly the local tool manifest, not other .NET configuration.
.config/dotnet-tools.json - AirLive reloading
.config/air.toml - ansible-lintAnsible linting
.config/ansible-lint.yml.config/ansible-lint.yaml - BaconBackground checks and tests
.config/bacon.toml - cargo-denyDependency policy checks
.config/deny.toml - cargo-nextestTest runner
.config/nextest.toml - changelogenChangelog generation and releasesLoaded through c12.
.config/changelog.ts.config/changelog.config.ts - CSpellCode and documentation spelling
.config/cspell.json.config/cspell.config.yaml - doc8reStructuredText checks
.config/doc8.ini - git-cliffChangelog generation
.config/cliff.toml - GoReleaserRelease automation
.config/goreleaser.yml.config/goreleaser.yaml - Insta / cargo-instaSnapshot testing
.config/insta.yaml - LefthookGit hook managementAlso accepts YAML, TOML, JSON and JSONC variants.
.config/lefthook.yml - MillJVM build toolingLauncher and JVM settings; not the build definition.
.config/mill-version.config/mill-opts.config/mill-jvm-version.config/mill-jvm-opts - miseDevelopment tools, environments and tasks
.config/mise.toml.config/mise/config.toml - MoleculeAnsible testingShared settings that add to each scenario’s configuration.
.config/molecule/config.yml - NitroServer application toolkit
.config/nitro.ts.config/nitro.config.ts - NuxtVue application frameworkLoaded through c12.
.config/nuxt.ts.config/nuxt.config.ts - PrismaDatabase tooling and ORM
.config/prisma.ts - release-itVersioning and release automationKeeps the leading dot (
.config/.release-it.json.config/.release-it.yaml.release-it.json). Loaded through c12. - RuboCopRuby linting and formatting
.config/.rubocop.yml.config/rubocop/config.yml - rumdlMarkdown linting and formatting
.config/rumdl.toml - semantic-releaseAutomated versioning and publishingLoaded through cosmiconfig.
.config/releaserc.json.config/releaserc.yaml - StylelintCSS lintingLoaded through cosmiconfig.
.config/stylelintrc.json.config/stylelintrc.yaml - SVGRConvert SVGs to React componentsLoaded through cosmiconfig.
.config/svgrrc.json.config/svgrrc.yaml - TombiTOML formatting and linting
.config/tombi.toml
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
- Check the tool's docs: it may already support
.config/. - Search its issues and PRs, open and closed, for
.configandXDG. - If there's already an issue, read it, add a 👍 if you agree, and don't open another.
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.