https://github.com/pi0/config-dir
📁 A proposal for the .config/ directory.
https://github.com/pi0/config-dir
Last synced: 17 days ago
JSON representation
📁 A proposal for the .config/ directory.
- Host: GitHub
- URL: https://github.com/pi0/config-dir
- Owner: pi0
- Created: 2024-02-13T14:33:50.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-02-15T13:13:25.000Z (about 1 year ago)
- Last Synced: 2024-05-02T01:03:35.760Z (10 months ago)
- Homepage:
- Size: 26.4 KB
- Stars: 378
- Watchers: 5
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 📁 config directory proposal
A proposal for the `.config/` directory.
## Motivation
The number of configs in projects is growing every day, and there is no convention to organize them!
The lack of a conventional place to organize configuration files led tools to often prefer to use top-level configuration files suffixed with `.config` or `rc`.
This makes things harder than they should be:
- For developers to quickly get started and understand a new codebase
- For repository maintainers, to manage config files
- For tools to distinguish config files
- For library authors to decide on where to store or load configs
Some tools offer command line options or environment variables for setting a non-default path to their config files.
This is not a proper replacement for a standardized default lookup directory, because the tool might be invoked from a number of contexts and shipping configuration for them all (including unknown ones!) in projects does not scale, nor is it possible for some cases. Such contexts include, but are not limited to:
- Different editors and IDE's
- SCM commit hooks and different manager tools for them
- Plain command line usage, including one-off runs
- CI/CD environments
## Goal
This proposal aims to introduce a new conventional place for storing configuration files and motivate different tools to support it as a new alternative standard while allowing top-level conventions the same as before.
## Discussions
> [!NOTE]
> More discussions related to this proposal, are moved under the [Discussions](https://github.com/pi0/config-dir/discussions) section.
- [`.config` dir support tracker](https://github.com/pi0/config-dir/discussions/6)
- [previous efforts](https://github.com/pi0/config-dir/discussions/5)
- [alternative directory names](https://github.com/pi0/config-dir/discussions/3)
## `.config/` directory
When the `.config/` directory exists, tools read the config files inside this directory.
Usually, tools should use `/.config/[name].[ext]` for file name convention.
### Nesting
As the size of the configuration increases, managing them all in a single configuration will be harder. Tools can optionally support `.config/[name]/` to allow nesting.
In the case of monorepo when users need to specify multiple files of the same config, the config files can be nested into `//.config` directory and based on the tool requirements either merged with mono repo's `/.config` or not.
### Conventions
While this proposal does not enforce the naming convention of files inside this dir, it provides some recommendations and best practices.
#### Specify tool name
Tool or framework names should be explicitly clear in configuration file names to avoid conflicting tools with each other and also make it clear for users what config is for what.
```
✅ .config/toolname.js
❌ .config/app.js
```
#### Avoid the `.config` and `.conf` suffix
Since the `.config` directory name is already clear it is holding configuration files, the `.config` suffix is not needed and shall be avoided.
```
✅ .config/toolname.js
❌ .config/toolconf.js
❌ .config/toolname.config.js
```
> [!NOTE]
> To make the migration to the `.config` directory process easier and keep the existing file name conventions, tools might allow this suffix as an alternative.
#### Specify format with extension
Config files without clear extensions are harder to be parsed. Both by IDEs and other tools and also for end-users to understand.
```
✅ .config/toolname.toml
❌ .config/toolname
❌ .config/toolrc
```
> [!Note]
> This proposal discourages using the `rc` format because the syntax interpretation is ambiguous.
#### Lower-case
Using case-sensitive configuration file names can introduce cross-platform support issues. It is highly recommended to only use lowercase naming.
```
✅ .config/toolname.toml
❌ .config/toolName
```
> [!NOTE]
> This proposal recommends using the kebab case if the tool name is too long `tool-name.json` instead of a snake case like `tool_name.json` to preserve consistency in this directory.
## Exceptional files
There are config/dot files that are common and unlikely to be nestable. These are excluded from the scope of this proposal:
- `.env`
- `.gitignore`
## Next steps
This is a big ecosystem issue and unless we push to unblock it, nothing will happen! The goal of this proposal is to make a centralized effort and discussion forum for tool authors to contribute.
- Make a tracker DB of tools with known configuration files and their status with this proposal
- Open individual issue trackers to each tool and invite them to collaborate
- Provide a preset configuration to use VSCode File Nesting with the `.config/` directory