xdg-dirs

Manage your XDG directories.

Meant to replace both xdg-user-dirs & xdg-user-dirs-update plus:

• Supports the missing non-user XDG paths, namely:
  • XDG_DATA_HOME
  • XDG_CONFIG_HOME
  • XDG_STATE_HOME
  • XDG_CACHE_HOME
  • XDG_RUNTIME_DIR
• Cross-platform: macOS and Linux, perfect for cross-platform dotfiles.

It works very similarly, but instead of using ~/.config/user-dirs.dirs which is both a subjectively awful name, and an objectively non-XDG-compliant path, we use ~/.config/xdg/ for both the user-editable user.dirs and the generated.dirs which represents what is being applied.

Features

• Non-destructive directory updates, when a new XDG folder is set, the previous folder is not modified in any way
• Customizable user directory locations on ~/.config/xdg/user.dirs
• Automatic generation of ~/.config/xdg/generated.dirs, which will be a merge of ~/.config/xdg/user.dirs and default XDG standards as per this XDG go library

Installation

Compiling from source

To compile xdg-dirs from source:

1. Ensure you have Go installed on your system. You can download it from https://golang.org/dl/

2. Clone the repository:

   git clone https://github.com/adriangalilea/xdg-dirs.git
   cd xdg-dirs
   

3. Compile for your current system:

   go build -o xdg-dirs ./cmd/xdg-dirs
   

4. Move the binary to a directory in your PATH:

   sudo mv xdg-dirs /usr/local/bin/
   

Usage

The tool is designed to be evaluated by the shell. This means that the only output is the exported variables:

$ xdg-dirs
export XDG_CONFIG_HOME="/home/adrian/.config"
export XDG_DATA_HOME="/home/adrian/.local/share"
export XDG_RUNTIME_DIR="/run/user/1000"
export XDG_DOCUMENTS_DIR="/home/adrian/Documents"
export XDG_MUSIC_DIR="/home/adrian/Music"
export XDG_VIDEOS_DIR="/home/adrian/Videos"
export XDG_TEMPLATES_DIR="/home/adrian/Templates"
export XDG_CACHE_HOME="/home/adrian/.cache"
export XDG_STATE_HOME="/home/adrian/.local/state"
export XDG_DESKTOP_DIR="/home/adrian/Desktop"
export XDG_DOWNLOAD_DIR="/home/adrian/Downloads"
export XDG_PICTURES_DIR="/home/adrian/Pictures"
export XDG_PUBLICSHARE_DIR="/home/adrian/Public"

So it's meant to be used like this:

eval "$(xdg-dirs)"

To ensure XDG environment variables are set in your shell:

1. (Optional) Create ~/.config/xdg/user.dirs with your desired XDG directory locations.

2. Add the following line to your shell's startup file (~/.zshenv, ~/.profile, ~/.zshrc, or ~/.bashrc):

   eval "$(xdg-dirs)"
   

3. Restart your shell or source your configuration file for the changes to take effect.

The tool will generate a ~/.config/xdg/generated.dirs file, which is a combination of user-specified directories in user.dirs and platform-specific defaults for directories not specified in user.dirs. All modifications should be done in user.dirs.

Command-line Options

• -h, --help: Show help message
• -d, --debug: Enable verbose output
• -n, --dry-run: Simulate changes without applying them
• -c, --create-dirs: Create directories if they don't exist
• -l, --log-file: Specify the log file path (default: $HOME/.local/state/xdg-dirs/xdg-dirs.log)

Example usage with log file specification:

xdg-dirs -l ~/xdg-update.log

Configuration

• ~/.config/xdg/user.dirs: User-defined configuration (edit this file)
• ~/.config/xdg/generated.dirs: Generated configuration file (do not edit this file directly)

Example Configuration

Here's an example of what your ~/.config/xdg/user.dirs file might look like:

XDG_CACHE_HOME="$HOME/.local/cache"

For instance, I prefer to have the cache folder in ~/.local/cache rather than ~/.cache simply because I prefer a clutter-free ~ home :)

Recommended macOS Configuration

If you're on macOS and want to use standard XDG paths instead of macOS defaults:

# ~/.config/xdg/user.dirs
# Custom XDG directories - prefer standard XDG paths over macOS defaults
XDG_CONFIG_HOME="$HOME/.config"
XDG_CACHE_HOME="$HOME/.local/cache"
XDG_DATA_HOME="$HOME/.local/share"
XDG_STATE_HOME="$HOME/.local/state"
# Use macOS temp directory for runtime - auto-cleaned on reboot
XDG_RUNTIME_DIR="$TMPDIR"

This configuration:

• Uses standard XDG paths (.config, .local/share, etc.) instead of ~/Library/Application Support
• Respects the XDG spec requirement that XDG_RUNTIME_DIR must be cleaned on reboot by using $TMPDIR
• Keeps your home directory organized with a clean .local structure

You can omit any directories you don't want to customize, and the tool will use platform-specific defaults.

For instance, in this case, XDG_VIDEOS_DIR will be ~/Videos on Linux and ~/Movies on macOS.

Default Behavior

• Uses platform-specific defaults for all directories
• User configurations in user.dirs override defaults
• Preserves exact configurations from user.dirs
• Generates ~/.config/xdg/generated.dirs based on user.dirs and defaults

For more information on XDG Base Directory Specification, check XDG.

FAQ

Why do you remove the ~/.config/user-dirs.dirs?

The XDG library which this program relies on:

XDG user directories environment variables are usually not set on most operating systems. However, if they are present in the environment, they take precedence.

On Unix-like operating systems (except macOS and Plan 9), the package reads the user-dirs.dirs config file.

source

So in order to read the actual defaults for your system, we need to first remove the file and unset the vars.

Note that the program backs up ~/.config/user-dirs.dirs to ~/.config/xdg/user-dirs.dirs-backup rather than deleting it. If a backup already exists, it will be overwritten.

Why are XDG_DATA_DIRS and XDG_CONFIG_DIRS missing?

Because they're missing from the XDG lib we use.