#macOS dotfiles should not go in ~/Library/Application Support
One of my pet peeves is when command-line tools look for user configuration files in ~/Library/Application Support when running on macOS. In addition to offering poor ergonomics for users, I believe this behavior is incorrect according to the documentation which is cited to justify it. Instead, command-line tools should implement the XDG Base Directory Specification and look for configuration files in $XDG_CONFIG_HOME , which defaults to ~/.config .
Usually, when a program looks for configuration files in ~/Library/Application Support , it’s not because of an intentional design decision. Instead, the author delegated that decision to a library, and several popular libraries for determining platform-specific configuration directories use ~/Library/Application Support as the default configuration directory on macOS, including Python’s platformdirs package (242 million downloads / month), JavaScript’s env-paths (95 million downloads / month), Rust’s dirs crate (4.8 million downloads / month), and Go’s adrg/xdg package (used in 913 packages). While ~/Library/Application Support may be the correct configuration directory for GUI apps which manage their configuration files for the user automatically, the vast majority of applications using these libraries are command-line utilities whose configuration belongs in ~/.config .
The main reason I dislike programs looking for dotfiles in ~/Library/Application Support is that it’s unexpected. As Ashlin Eldridge explained on GitHub:
As a new user, it’s extremely surprising to me to that a modern tool like nu would put config files under Application Support on macOS. It’s even more surprising to see that some people are actively against adopting the XDG standard. The origins of XDG no longer matter at this point. No one really cares what the X, D, and G stand for. The fact is that hundreds of tools support it (including Git, Emacs, Neovim, Tmux) and users have come to expect support for it. It’s the closest thing we have to a standard that allows users to control the placement of their config files (which facilitates users’ ability to source control their files) and it also includes support for files that shouldn’t be source controlled such as cache and data files.
If a user explains that they found a program’s behavior surprising, many engineers will respond by telling the user that their expectations were wrong. However, I find that the reason users form an incorrect mental model of a program’s behavior is usually because the program’s design violated an established convention from some broader context. In accordance with the Principle of Least Astonishment, I prefer to change the program to behave how users expect rather than futilely attempt to change what users expect.
Users expect macOS CLI tools to look for configuration files in ~/.config is because that’s what almost every other program does. Your program should probably not disagree with Bash and Vim and Git about where configuration files are supposed to go!
These conventions help us explore unfamiliar systems by letting us apply knowledge about one part of the system to other parts of the system. Consistency is predictability. When every tool works the same except for a small handful, users get justifiably annoyed at the exceptions for wasting their time.
#What do dotfile managers do?
Many engineers use (or maintain) some sort of dotfile manager to handle tracking these configuration files. If configuration files are really supposed to go in ~/Library/Application Support , we would expect dotfile managers to put configuration files there by default when running on macOS. After all, the whole point of a dotfile manager is to simplify managing configuration files across multiple machines and platforms. Let’s take a quick survey to see how some popular dotfile managers behave on macOS:
... continue reading