What is the purpose of (and possibly the convention of using) multiple locations for user configuration in fish shell

Question

I have recently moved to fish from bash. I'm immediately in love with the out-of-the-box functionality, but I'm a little bit at a loss when it comes to configuring the shell.

I've read through the documentation, particularly the section about initialization, and it states:

On startup, Fish evaluates a number of configuration files...

• Configuration snippets in files ending in .fish, in the directories:
  • $__fish_config_dir/conf.d (by default, ~/.config/fish/conf.d/)
  • ...
• User initialization, usually in ~/.config/fish/config.fish ...

So far, this is clear to understand. Coming from bash, I took my .bash_globals and .bash_aliases files, rewrote them a little bit according to fish's syntax, placed them into the ~/.config/fish/conf.d/ and they are loaded as expected.

However, when I looked over the contents of the config.fish file, I couldn't figure out anything that would need to be put there. To my understanding, fish is designed to work already out of the box, so the usual bash config like setting HISTCONTROL isn't necessary. Nor are the conf.d/ files called from some main script (like the .bash_aliases, etc., would be in .bashrc) - they're loaded automatically.

Is there some particular use case where config.fish is preferred - or even required - over conf.d/ files? So far, I would say individual files are cleaner to read, maintain and move between hosts. Is there some convention that's recommended to follow? Was there a specific motivation behind allowing so many levels of config, aside from giving users more freedom?

Answer 1

As far as purpose, I'd say there are several good reasons to support both.

First, and probably most importantly, as @Zanchey points out in the comments, conf.d support came about in release 2.3.0, so getting rid of config.fish at that point would have been a breaking change.

Second, as you said, freedom for the users to choose the way they would like to handle startup behavior.

Next, it's also somewhat "path of least resistance". I definitely share your preference for the modularity of conf.d/ files, and I love not having a config.fish myself. But some (perhaps even most) users who are moving over to fish for the first time default to the familiarity of a single .bash_profile-like place to put their config. I can imagine that the paradigm shift of not having a single-file config might be off-putting to some. In other words, config.fish helps provide a smooth migration for new users.

Further, config.fish is easier to explain to a new user, since it maps to something they already know in their previous shell. Even the fish FAQ defaults to telling users that config.fish is the equivalent of their previous startup scripts. Although I do wish they'd go on to explain the conf.d/ alternative as well there.

And config.fish does have one other small advantage, in that the execution order is more explicit (i.e. it's executed start to end). conf.d/ files are read just like any other conf.d/, in alphabetical order (or glob-result order, most likely). In my experience, this means that you have to resort to 00_dependency.fish type of naming to ensure that one file is run before others. That said, it should rare that anyone would have to resort to that.

As for "convention", well, I know many distributions set up their configuration files (e.g. the Apache2 httpd.conf) with a default "single-file" that goes on to process a conf.d/ structure. In fish's case, they just did away with the boilerplate for conffile in ~/.config/fish/conf.d/*.fish; source $conffile; end that would otherwise be required in config.fish.