We previously spoke of the FHS directory standard.

This includes important rules for where a program should store its data. This is particularly important when writing your programs as you need to know where you should write your program state to.

While this answers where you should write your state to for programs that run system-wide, it does not help for per-user programs.

The traditional unix approach for this has been dotfiles so each program leaves hidden files all over the user's home directory.

This is sub-optimal since the directories are hidden by default, which solves not cluttering the file listing in your home directory at the cost of merely hiding the clutter rather than structuring it.

To plug this gap the XDG directory standard was designed.

Rather than it specifying exactly which directories should be used, it specifies an environment variable which descibes which directory to use and a default if the environment variable is not defined.

Variable Default FHS equivalent Purpose
XDG_CONFIG_HOME ~/.config /etc Program configuration files.
XDG_CACHE_HOME ~/.cache /var/cache Non-essential cached data.
XDG_DATA_HOME ~/.local/share /usr/share Data files.
XDG_RUNTIME_DIR /var/run Program state for current boot.

The standard also defines XDG_DATA_DIRS and XDG_CONFIG_DIRS, but they are about where to read system-wide config files from.

The rules are meant to be simple enough that you can implement it yourself, but there are some helper libraries available.

If you're writing python there is PyXDG. If you're writing C there's implementations in GLib, or a 3-clause BSD licensed implementation in chck.

If you're interested in more standards for where to put files, a relevant XDG user directory standard exists, which lists more variables in ${XDG_CONFIG_HOME}/user-dirs.dirs for directories like the default place to download files to.