https://github.com/adriangalilea/xdg-dirs
Manage your XDG directories. meant to replace `xdg-user-dirs` & `xdg-user-dirs-update` while being cross-platform.
https://github.com/adriangalilea/xdg-dirs
linux mac macos xdg xdg-compliance xdg-user-dirs
Last synced: about 2 months ago
JSON representation
Manage your XDG directories. meant to replace `xdg-user-dirs` & `xdg-user-dirs-update` while being cross-platform.
- Host: GitHub
- URL: https://github.com/adriangalilea/xdg-dirs
- Owner: adriangalilea
- Created: 2024-07-28T18:48:56.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-04T17:16:32.000Z (about 1 year ago)
- Last Synced: 2025-03-30T21:29:55.891Z (7 months ago)
- Topics: linux, mac, macos, xdg, xdg-compliance, xdg-user-dirs
- Language: Go
- Homepage:
- Size: 43 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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](https://github.com/adrg/xdg)
## 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:
```bash
# ~/.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](https://github.com/adrg/xdg).
## FAQ
Why do you remove the `~/.config/user-dirs.dirs`?
The [XDG](https://github.com/adrg/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](https://github.com/adrg/xdg?tab=readme-ov-file#xdg-user-directories)
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](https://github.com/adrg/xdg) we use.