XDG directory specs

The XDG Base Directory Specification defines a set of environment variables for managing user-specific configuration, data, and cache files in a consistent way across different applications and environments. These environment variables help to avoid cluttering the home directory with numerous configuration and data files.

Key XDG Config Directory Variables

  1. XDG_CONFIG_HOME:

    • Purpose: Specifies the base directory for user-specific configuration files.
    • Default: $HOME/.config
    • Example: If an application needs to store its configuration files, it should place them in a subdirectory of XDG_CONFIG_HOME, such as $XDG_CONFIG_HOME/myapp/config.

  2. XDG_CONFIG_DIRS:

    • Purpose: Specifies the preference-ordered set of base directories to search for configuration files.
    • Default: /etc/xdg
    • Example: Applications should search for configuration files in these directories in addition to XDG_CONFIG_HOME, using the first found configuration file.

  3. XDG_DATA_HOME:

    • Purpose: Specifies the base directory for user-specific data files.
    • Default: $HOME/.local/share
    • Example: Applications should store data files in a subdirectory of XDG_DATA_HOME, such as $XDG_DATA_HOME/myapp/data.

  4. XDG_DATA_DIRS:

    • Purpose: Specifies the preference-ordered set of base directories to search for data files.
    • Default: /usr/local/share:/usr/share
    • Example: Applications should search for data files in these directories in addition to XDG_DATA_HOME, using the first found data file.

  5. XDG_CACHE_HOME:

    • Purpose: Specifies the base directory for user-specific non-essential (cached) data.
    • Default: $HOME/.cache
    • Example: Applications should place their cache files in a subdirectory of XDG_CACHE_HOME, such as $XDG_CACHE_HOME/myapp/cache.

  6. XDG_RUNTIME_DIR:

    • Purpose: Specifies the base directory for user-specific runtime files and other file objects (such as sockets, named pipes, etc.).
    • Default: The directory should be set by the system and typically has a more complex path, often in /run/user/UID.
    • Example: This directory is intended for short-lived files like sockets and temporary files.

Usage in Applications

Applications adhering to the XDG Base Directory Specification will store their configuration, data, and cache files in the appropriate directories, making it easier for users to manage these files and maintain a cleaner home directory. Here's an example of how an application might use these variables:

Example in a Bash Script

#!/bin/bash

# Ensure XDG variables are set
XDG_CONFIG_HOME=${XDG_CONFIG_HOME:-$HOME/.config}
XDG_DATA_HOME=${XDG_DATA_HOME:-$HOME/.local/share}
XDG_CACHE_HOME=${XDG_CACHE_HOME:-$HOME/.cache}

# Example application name
APP_NAME="myapp"

# Paths for storing configuration, data, and cache files
CONFIG_DIR="$XDG_CONFIG_HOME/$APP_NAME"
DATA_DIR="$XDG_DATA_HOME/$APP_NAME"
CACHE_DIR="$XDG_CACHE_HOME/$APP_NAME"

# Create directories if they don't exist
mkdir -p "$CONFIG_DIR" "$DATA_DIR" "$CACHE_DIR"

# Print the directories for demonstration
echo "Configuration files will be stored in: $CONFIG_DIR"
echo "Data files will be stored in: $DATA_DIR"
echo "Cache files will be stored in: $CACHE_DIR"

Running this script will create the necessary directories and print their paths, ensuring that the application follows the XDG Base Directory Specification.

Summary

The XDG Base Directory Specification provides a standardized way for applications to store configuration, data, and cache files. By using the specified environment variables (XDG_CONFIG_HOME, XDG_CONFIG_DIRS, XDG_DATA_HOME, XDG_DATA_DIRS, XDG_CACHE_HOME, XDG_RUNTIME_DIR), applications can maintain a cleaner and more organized file structure, making it easier for users to manage their personal files and settings.