Difference between revisions of "XDG Base Directory"

From ArchWiki
Jump to navigation Jump to search
Line 302: Line 302:
 
==={{ic|~/.inputrc}} ([http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html readline])===
 
==={{ic|~/.inputrc}} ([http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html readline])===
  
  export INPUTRC="${XDG_CONFIG_HOME:-$HOME/.config}"/readline/inputrc
+
  $ export INPUTRC="${XDG_CONFIG_HOME:-$HOME/.config}"/readline/inputrc
  
 
==={{ic|~/.lesshst}} ([http://www.greenwoodsoftware.com/less/ less])===
 
==={{ic|~/.lesshst}} ([http://www.greenwoodsoftware.com/less/ less])===

Revision as of 08:10, 29 May 2015

This article exists to catalog the growing set of software using the XDG Base Directory Specification. This is here to demonstrate the viability of this specification by listing commonly found dotfiles and their support status. For those not currently supporting the Base Directory Specification, workarounds will be demonstrated to emulate it instead.

The workarounds will be limited to anything not involving patching the source, executing code stored in environment variables or compile-time options. The rational for this is that configurations should be portable across systems and having compile-time options prevent that as will not do.

Hopefully this will provide a source of information about exactly what certain kinds of dotfiles are and where they come from.

Exceptions

These directories and files are unlikely to ever change, there is far too much historical baggage and most tools written expect these files and directories to exist in these locations.

While some of these tools are still in active development and maintainence, the developers are unwilling to accommodate for the necessary changes due to the aforementioned reasons.

~/.ssh
Assumed to be present by many ssh daemons and clients such as DropBear and OpenSSH. https://bugzilla.mindrot.org/show_bug.cgi?id=2050
~/.pki
Part of Mozilla's NSS Project
~/.netrc
Like ~/.ssh, many programs expect this file to be here. These include projects like curl (CURLOPT_NETRC_FILE), ftp (NETRC), s-nail (NETRC), etc. While some of them offer alternative configurable locations, many do not such as w3m, wget and lftp.
~/.dbus
Is unfortunately required by the specification, an oversight to be sure. https://bugs.freedesktop.org/show_bug.cgi?id=35887

Contents

The XDG Base Directory Specification

Please read the full specification here. I will attempt to break down the essence of what it tries to achieve.

None of the XDG_* directories should be set by default except some systems do set XDG_RUNTIME_DIR such as systemd (logind).

All paths defined must be absolute and valid.

User Directories

  • XDG_CONFIG_HOME
    • Defaults to HOME/.config
    • Where user-specific configurations should be written. (Like /etc)
  • XDG_CACHE_HOME
    • Defaults to HOME/.cache
    • Where user-specific non-essential (cached) data should be written. (Like /var/cache)
  • XDG_DATA_HOME
    • Defaults to HOME/.local/share
    • Where user-specific data files should be written. (Like /usr/share)

System Directories

  • XDG_DATA_DIRS
    • List of directories seperated by : (Like PATH)
    • Defaults to /usr/local/share:/usr/share
  • XDG_CONFIG_DIRS
    • List of directories seperated by : (Like PATH)
    • Defaults to /etc/xdg
  • XDG_RUNTIME_DIR
    • Used for non-essential, user-specific data files such as sockets, named pipes, etc.
    • Defaults to nothing, warnings should be issued if not set or equivalents provided.
    • Must be owned by the user with an access mode of 0700.
    • Filesystem fully featured by standards of OS.
    • Must be on the local filesystem.
    • May be subject to periodic cleanup.
    • Modified every 6 hours or set sticky bit if persistence is desired.
    • Can only exist for the duration of the user's login.
    • Shouldn't store large files as it may be mounted as a tmpfs.

Contributing

When contributing make sure to use the correct section.

Nothing should require code evaluation (such as vim and VIMINIT), patches or compile-time options to gain support and anything which does must be deemed hardcoded.

Try to find the commit or version a project switched to XDG Base Directory or any open discussions and include them in the entries' section:

For most projects simply note down any discussion or commits, e.g.

* Since http://commit-url
* Discussion http://any-links-to-open-discussions

If however there are multiple links, use a bulleted list for the urls, e.g.

Since
* http://commit-url/1
* http://commit-url/2
Discussion
* http://any-links-to-open-discussions/1
* http://any-links-to-open-discussions/2

Next include any appropriate workarounds or solutions for unsupported projects. Be terse, this article assumes intelligence and good charity from the reader. If something is unclear then feel free to expend some explanation to clarify it.

Lastly, and this goes without saying, please verify that your solution is correct and functional.

Supported

antimicro (antimicro)

blender (blender)

burp (burp)

chromium (chromium)

cower (cower)

dconf (dconf)

d-feet (d-feet)

dunst (dunst)

dwb (dwb)

~/.fontconfig (fontconfig)

fontforge (fontforge)

Discussion

~/.fonts (fontconfig)

Use "${XDG_DATA_HOME:-$HOME/.local/share}"/fonts instead.

~/.gconf (gconf)

~/.gitconfig (git)

htop (htop)

i3 (i3)

i3status (i3status)

inkscape (inkscape)

lgogdownloader (lgogdownloader)

livestreamer (livestreamer)

llpp (llpp)

Currently llpp places the configuration directly under XDG_CONFIG_HOME instead of creating a directory.

~/.mpdconf (mpd)

mpv (mpv)

mypaint (mypaint)

newsbeuter (newsbeuter)

offlineimap (offlineimap)

orbment (orbment)

pacman (pacman)

~/.pulse ~/pulse-cookie (pulseaudio)

Since

Discussion

util-linux (util-linux)

Since

Partial

~/.abook (abook)

$ abook --config "${XDG_CONFIG_HOME:-$HOME/.config}"/abook/abookrc \
        --datafile "${XDG_CACHE_HOME:-$HOME/.cache}"/abook/addressbook

~/.aspell.conf (GNU Aspell)

~/.cargo (cargo)

$ export CARGO_HOME="${XDG_DATA_HOME:-$HOME/.local/share/}"/cargo

~/.conkyrc (conky)

$ conky --config="${XDG_CONFIG_HOME:-$HOME/.config}"/conky/conkyrc

~/.dircolors (coreutils)

$ source "$(dircolors "${XDG_CONFIG_HOME:-$HOME}"/dircolors)"

~/.elinks (elinks)

$ export ELINKS_CONFDIR="${XDG_CONFIG_HOME:-$HOME/.config}"/elinks

~/.esd_auth (pulseaudio)

Very likely generated by the module-esound-protocol-unix.so module. It can be configured to use a different location but it makes much more sense to just comment out this module in /etc/pulse/default.pa or XDG_CONFIG_HOME/pulse/default.pa.

~/.gdbinit (gdb)

$ gdb -nh -x "${XDG_CONFIG_HOME:-$HOME/.config}"/gdb/init

~/.gimp-2.8 (gimp)

However this doesn't appear to work, see workaround below.

Discussion

$ export GIMP2_DIRECTORY="${XDG_CONFIG_HOME:-$HOME/.config}"/gimp

~/.glivrc (gliv)

$ gliv --glivrc="${XDG_CONFIG_HOME:-$HOME/.config}"/gliv/glivrc

~/.gnupg (GPG)

$ export GNUPGHOME="${XDG_CONFIG_HOME:-$HOME/.config}"/gnupg
$ gpg2 --homedir "${XDG_CONFIG_HOME:-$HOME/.config}"/gnupg

~/.gtkrc-2.0 (gtk)

$ export GTK2_RC_FILES="${XDG_CONFIG_HOME:-$HOME/.config}"/gtk-2.0/gtkrc

~/.httpie (httpie)

$ export HTTPIE_CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}"/httpie

~/.inputrc (readline)

$ export INPUTRC="${XDG_CONFIG_HOME:-$HOME/.config}"/readline/inputrc

~/.lesshst (less)

export LESSHISTFILE="${XDG_CACHE_HOME:-$HOME/.cache}"/less/history

~/.mutt (mutt)

$ mutt -F ${XDG_CONFIG_HOME:-$HOME/.config}"/mutt/muttrc
muttrc
set header_cache = ~/.config/mutt/cache/headers
set message_cachedir = ~/.config/mutt/cache/messages
set mailcap_path = ~/.config/mutt/mailcap
set record = ~/.config/mutt/record/sent

~/.ncmpcpp (ncmpcpp)

-c "${XDG_CONFIG_HOME:-$HOME/.config}"/ncmpcpp/config

~/.weechat (weechat)

export WEECHAT_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"/weechat
weechat -d "${XDG_CONFIG_HOME:-$HOME/.config}"/weechat

~/.wine (wine)

export WINEPREFIX="${XDG_DATA_HOME:-$HOME/.local/share}"/wine

~/.XAuthority (xorg-auth)

export XAUTHORITY="${XDG_RUNTIME_DIR"/X11/xauthority"

~/.XCompose (libx11)

export XCOMPOSEFILE="${XDG_CONFIG_HOME:-$HOME/.config}"/X11/xcompose

~/.xinitrc (xorg-xinit)

The startx script which comes with xorg-xinit will fallback to looking for ~/.xinitrc if no arguments are given. A simple workaround is to pass in the path to your xinitrc such as $ startx ~/.config/X11/xinitrc or using an alternative startx script.

~/.Xresources ~/.Xdefaults (xorg-xrdb)

Ultimately you should be using Xresources and since these resources are loaded via xrdb you can specify a path such as xrdb -load ~/.config/X11/xresources.

Hardcoded

~/.ApacheDirectoryStudio (Apache Directory Studio)

~/.aMule (Amule)

~/.gnome (xdg-utils)

For some reason the script xdg-desktop-menu hardcodes gnome_user_dir="$HOME/.gnome/apps". This is used by chromium amoung others.

/usr/bin/xdg-desktop-menu
@@ -1317,7 +1317,7 @@
 kde_global_dir=`kde${KDE_SESSION_VERSION}-config --path apps 2> /dev/null | cut -d ':' -f 2`
 [ -w $kde_global_dir ] || kde_global_dir=
 
-gnome_user_dir="$HOME/.gnome/apps"
+gnome_user_dir="${XDG_DATA_HOME:-$HOME/.local/share}/gnome/apps"
 gnome_global_dir="/usr/share/gnome/apps"
 [ -w $gnome_global_dir ] || gnome_global_dir=

~/.milkytracker_config (milkytracker)

~/.python_history (python)

All history from interactive sessions is saved to ~/.python_history by default since version 3.4, custom path can still be set the same way as in older versions (see this example).

~/.vim ~/.vimrc ~/.viminfo (vim)

Since 7.3.1178 vim will search for ~/.vim/vimrc if ~/.vimrc is not found.

~/.vim/vimrc
set undodir = ~/.cache/vim/undo " vim will not create this directory.
set directory = ~/.cache/vim/swap " vim will not create this directory.
set backupdir = ~/.cache/vim/backup " vim will not create this directory.
set viminfo += n ~/.cache/vim/viminfo

See also

~/.juliarc.jl ~/.julia_history (julia)

Discussion

A Personal Suggestion

Ever copied a directory expecting * to really match everything only to find it had skipped all of the "dotfiles"? Do you often spend most of your time on the shell habitually running ls immediately followed by your la alias if the directory appeared empty?

If you're like me, this kind of overhead becomes tedious, but there is a solution. POSIX requires that ls implements the -A command-line option which prints all files and directories except for . and ... This was the original intention of Dennis Ritchie or Ken Thompson during the UNIX v2 rewrite. They made a mistake which resulted in all files with a leading dot being hidden from ls.

Instead, let us abolish "dotfiles", no more "hidden" content, no more hacks. To achieve this add the following to your shell's rc:

shellrc
alias ls='ls -A' # Never see missing files again.
alias ll='ls -lA' # And so on, for any ls alias you have, add -A.  To view . and .., use -a.  This is rarely useful in combination with -l to see timestamps.

Now to handle dotfiles being included in glob expressions, set the following for your preferred shell:

zshrc
setopt glob_dots # Forces the shell to consider "dotfiles" when using normal glob expressions.
bashrc
shopt -s dotglob # Bash's version of the above.
dash
# No known solution