Don’t name your config Toolfile (or .tool.yml)

There is a pattern, mostly used in Ruby world, that if you write a command line tool, named – say – The Tool, and it has a configuration file tied to a project you use it with, then the tool’s configuration fie is called Toolfile, and lives in the root of the project’s directory.

Don’t do that. Please.

I suppose that this started a couple centuries ago, with mother of all the build tools Make and its Makefile. Ruby build tool Rake used the existing convention for build tools, and named its configuration file Rakefile. This makes sense: in a software project, build script is the entry point. It’s logical and convenient that it lives in top-level directory, and it’s easy to locate, because the name is capitalized.

Rake followed a useful convention for build script. But then, all other tools followed Rake without stopping to think if it’s useful. Now I have a repository that has a Rakefile, Thorfile, Gemfile, Berksfile, Vagrantfile, and Strainerfile – there are more Toolfiles in there than real content.

The other custom is to name the config .tool.yml – also in project root. While Toolfiles clutter the directory by being too visible, dotfiles files do the opposite – they disappear. Some projects get this right and use dotfiles or dot-directories for stuff that should be hidden: .rvmrc, .bundle, or even .chef are good examples. Still, .travis.yml or .rspec are ugly. Even without the dot, cucumber.yml or Jekyll’s _config.yml smell quite bad.

How to name configuration files, then? Simple: use a config directory. Let me put all the config in the config/ subdirectory instead of cluttering the root and making it harder to spot the README file. Seriously, what would be wrong with config/thor.rb, config/gems.rb, config/berkshelf.rb, or config/travis.yml? It would be even possible to adapt to different projects’ conventions by using a dotfile (that is supposed to be hidden) pointing to the directory, and looking for the config like this:

  • If .config is an empty file, always use Toolfile and don’t look at any directory
  • If .config is a file, go with `cat .config`/tool.rb
  • If .config is a directory or symlink pointing to one, `realpath .config`/tool.rb
  • If there is no .config, but config/tool.rb exists, use it
  • At the end, try Toolfile

By default, tool would look for config/tool.rb or Toolfile, and any project that uses a different config directory could use .config file or symlink to override this. Vendorificator already partially implements that, and I think that I’ll soon release a small gem that would deal with config files, including the .config override. Some other options may be useful, like finding multiple config file fragments by directory or glob.
Let’s hope that in a year or two I’ll be able to move at least some of the configuration files away and won’t need to find my project’s files between the configs!