The Þog of 2022-09-18 — XDG Base Directories

I've seen a lot of confusion as to how the XDG base directories work. Long story short, they're not scary or hard to implement.

Here's a few short descriptions of how the "main" XDG base directory enviroment variables work:

$XDG_CONFIG_HOME — Where your user's preferences, keys, etc. go. Put stuff that you wouldn't want to lose in here. This is "$HOME/.config" if unset.
$XDG_DATA_HOME — Where you put long-term but not mission-critical stuff. Downloaded files, game saves, addons, and unseparated data should go here. This is "$HOME/.local/share" if unset.
$XDG_CACHE_HOME — Where you put short-term stuff that might be gone on the next reboot. Logs, temporary files, cache files, etc. go in here. This is "$HOME/.cache" if unset.

If you're worried about needing to search /etc/xdg or $XDG_{CONFIG, DATA, CACHE}_DIRS, you almost definitely don't need them. They're for system-wide stuff that you probably already have in /usr/share or /etc.

Even if you prefer dotfiles in $HOME over XDG base directories, adding two lines of code to your program is all we need to figure stuff out on our own. (I'm assuming you already have at least one line for your existing $HOME dotfile system)

Python-like pseudocode, environment variable approach

app_home = getenv('YOURAPP_HOME') # or YOURAPP_RC if you only need one file

if app_home is null:
    app_home = getenv('HOME') + '/.yourapp'

Python-like pseudocode, commandline argument approach

app_home = getenv('HOME') + '/.yourapp'

if '--profile' in args:
    app_home = args['--profile']

Bonus Content

Below is a compilation of various kludges I use to bend otherwise dotfile-happy programs to my will. As an extra bonus, these programs will no longer crash on startup if you have $HOME's write permission disabled.

Firefox

# NOTE: you'll need to set up a profile beforehand in $XDG_DATA_HOME/firefox
# .mozilla can go to XDG_CACHE_HOME, the only thing it contains is crash logs
exec env HOME="$XDG_CACHE_HOME" /usr/bin/firefox \
    --profile "$XDG_DATA_HOME/firefox" "$@"

Xonotic/Darkplaces games in general

# Run `mkdir -p "$XDG_DATA_HOME/xonotic"` if there's an error
exec xonotic-sdl -nohome -userdir "$XDG_DATA_HOME/xonotic" "$@"

LMMS

# NOTE: You'll need a pre-existing lmmsrc, LMMS dumps .lmmsrc.xml in $HOME,
# you can move this file to $XDG_CONFIG_HOME/lmms/lmmsrc.xml
exec /usr/bin/lmms -c "$XDG_CONFIG_HOME/lmms/lmmsrc.xml" "$@"

w3m

# Good news! The maintainer of w3m plans to merge a patch that makes this
# a lot easier! You can find the patch at https://github.com/tats/w3m/pull/207
# NOTE: You'll need a w3mrc and you'll have to change a couple settings that
# expect ~/.w3m
exec env HOME="$XDG_CONFIG_HOME/w3m" /usr/bin/w3m \
    -config "$XDG_CONFIG_HOME/w3m/config" \
    -bookmark "$XDG_CONFIG_HOME/w3m/bookmarks.html" \
    "$@"