├── .config └── .gitkeep └── README.md /.config/.gitkeep: -------------------------------------------------------------------------------- 1 | # I exist, therefore I am. 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # 📁 config directory proposal 2 | 3 | A proposal for the `.config/` directory. 4 | 5 | ## Motivation 6 | 7 | The number of configs in projects is growing every day, and there is no convention to organize them! 8 | 9 | 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`. 10 | 11 | This makes things harder than they should be: 12 | 13 | - For developers to quickly get started and understand a new codebase 14 | - For repository maintainers, to manage config files 15 | - For tools to distinguish config files 16 | - For library authors to decide on where to store or load configs 17 | 18 | Some tools offer command line options or environment variables for setting a non-default path to their config files. 19 | 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: 20 | 21 | - Different editors and IDE's 22 | - SCM commit hooks and different manager tools for them 23 | - Plain command line usage, including one-off runs 24 | - CI/CD environments 25 | 26 | ## Goal 27 | 28 | 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. 29 | 30 | ## Discussions 31 | 32 | > [!NOTE] 33 | > More discussions related to this proposal, are moved under the [Discussions](https://github.com/pi0/config-dir/discussions) section. 34 | 35 | - [`.config` dir support tracker](https://github.com/pi0/config-dir/discussions/6) 36 | - [previous efforts](https://github.com/pi0/config-dir/discussions/5) 37 | - [alternative directory names](https://github.com/pi0/config-dir/discussions/3) 38 | 39 | ## `.config/` directory 40 | 41 | When the `.config/` directory exists, tools read the config files inside this directory. 42 | 43 | Usually, tools should use `/.config/[name].[ext]` for file name convention. 44 | 45 | ### Nesting 46 | 47 | 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. 48 | 49 | 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. 50 | 51 | ### Conventions 52 | 53 | While this proposal does not enforce the naming convention of files inside this dir, it provides some recommendations and best practices. 54 | 55 | 56 | #### Specify tool name 57 | 58 | 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. 59 | 60 | ``` 61 | ✅ .config/toolname.js 62 | 63 | ❌ .config/app.js 64 | ``` 65 | 66 | #### Avoid the `.config` and `.conf` suffix 67 | 68 | Since the `.config` directory name is already clear it is holding configuration files, the `.config` suffix is not needed and shall be avoided. 69 | 70 | ``` 71 | ✅ .config/toolname.js 72 | 73 | ❌ .config/toolconf.js 74 | 75 | ❌ .config/toolname.config.js 76 | ``` 77 | 78 | > [!NOTE] 79 | > 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. 80 | 81 | #### Specify format with extension 82 | 83 | Config files without clear extensions are harder to be parsed. Both by IDEs and other tools and also for end-users to understand. 84 | 85 | ``` 86 | ✅ .config/toolname.toml 87 | 88 | ❌ .config/toolname 89 | 90 | ❌ .config/toolrc 91 | ``` 92 | 93 | > [!Note] 94 | > This proposal discourages using the `rc` format because the syntax interpretation is ambiguous. 95 | 96 | #### Lower-case 97 | 98 | Using case-sensitive configuration file names can introduce cross-platform support issues. It is highly recommended to only use lowercase naming. 99 | 100 | ``` 101 | ✅ .config/toolname.toml 102 | 103 | ❌ .config/toolName 104 | ``` 105 | 106 | > [!NOTE] 107 | > 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. 108 | 109 | ## Exceptional files 110 | 111 | There are config/dot files that are common and unlikely to be nestable. These are excluded from the scope of this proposal: 112 | 113 | - `.env` 114 | - `.gitignore` 115 | 116 | ## Next steps 117 | 118 | 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. 119 | 120 | - Make a tracker DB of tools with known configuration files and their status with this proposal 121 | - Open individual issue trackers to each tool and invite them to collaborate 122 | - Provide a preset configuration to use VSCode File Nesting with the `.config/` directory 123 | 124 | --------------------------------------------------------------------------------