feat: respect XDG Base Directory environment variables (#142)

Author: jordond

cli/src/config.rs

@@ -1,11 +1,18 @@
 use crate::theme::ThemeColors;
 use jolt_theme::NamedTheme;
 use serde::{Deserialize, Serialize};
+use std::env;
 use std::fs;
 use std::path::PathBuf;
 use std::process::Command;
 use tracing::Level;
 
+// XDG Base Directory environment variables
+pub const XDG_CONFIG_HOME: &str = "XDG_CONFIG_HOME";
+pub const XDG_CACHE_HOME: &str = "XDG_CACHE_HOME";
+pub const XDG_DATA_HOME: &str = "XDG_DATA_HOME";
+pub const XDG_RUNTIME_DIR: &str = "XDG_RUNTIME_DIR";
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
 #[serde(rename_all = "lowercase")]
 pub enum LogLevel {
@@ -266,25 +273,41 @@ impl Default for UnitsConfig {
 }
 
 pub fn config_dir() -> PathBuf {
-    dirs::config_dir()
+    env::var(XDG_CONFIG_HOME)
+        .ok()
+        .filter(|s| !s.is_empty())
+        .map(PathBuf::from)
+        .or_else(dirs::config_dir)
         .unwrap_or_else(|| PathBuf::from("~/.config"))
         .join("jolt")
 }
 
 pub fn cache_dir() -> PathBuf {
-    dirs::cache_dir()
+    env::var(XDG_CACHE_HOME)
+        .ok()
+        .filter(|s| !s.is_empty())
+        .map(PathBuf::from)
+        .or_else(dirs::cache_dir)
         .unwrap_or_else(|| PathBuf::from("~/.cache"))
         .join("jolt")
 }
 
 pub fn data_dir() -> PathBuf {
-    dirs::data_dir()
+    env::var(XDG_DATA_HOME)
+        .ok()
+        .filter(|s| !s.is_empty())
+        .map(PathBuf::from)
+        .or_else(dirs::data_dir)
         .unwrap_or_else(|| PathBuf::from("~/.local/share"))
         .join("jolt")
 }
 
 pub fn runtime_dir() -> PathBuf {
-    dirs::runtime_dir()
+    env::var(XDG_RUNTIME_DIR)
+        .ok()
+        .filter(|s| !s.is_empty())
+        .map(PathBuf::from)
+        .or_else(dirs::runtime_dir)
         .or_else(dirs::cache_dir)
         .unwrap_or_else(|| PathBuf::from("/tmp"))
         .join("jolt")

cli/src/daemon/service.rs

@@ -362,10 +362,15 @@ const SYSTEMD_SERVICE_NAME: &str = "jolt-daemon.service";
 
 #[cfg(target_os = "linux")]
 fn linux_service_path() -> PathBuf {
-    let config_dir = dirs::config_dir().unwrap_or_else(|| {
-        let home = std::env::var("HOME").unwrap_or_default();
-        PathBuf::from(home).join(".config")
-    });
+    let config_dir = std::env::var(crate::config::XDG_CONFIG_HOME)
+        .ok()
+        .filter(|s| !s.is_empty())
+        .map(PathBuf::from)
+        .or_else(dirs::config_dir)
+        .unwrap_or_else(|| {
+            let home = std::env::var("HOME").unwrap_or_default();
+            PathBuf::from(home).join(".config")
+        });
 
     config_dir.join("systemd/user").join(SYSTEMD_SERVICE_NAME)
 }

website/src/content/docs/docs/configuration.md

@@ -21,6 +21,25 @@ The config file is located at:
 ~/.config/jolt/config.toml
 ```
 
+### XDG Base Directory Support
+
+jolt respects the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/). If you set XDG environment variables, jolt will use them instead of the default paths:
+
+| Variable          | Default (macOS)                 | Default (Linux)  | Used for                   |
+| ----------------- | ------------------------------- | ---------------- | -------------------------- |
+| `XDG_CONFIG_HOME` | `~/Library/Application Support` | `~/.config`      | Config file, custom themes |
+| `XDG_DATA_HOME`   | `~/Library/Application Support` | `~/.local/share` | Database, history          |
+| `XDG_CACHE_HOME`  | `~/Library/Caches`              | `~/.cache`       | Temporary cache            |
+| `XDG_RUNTIME_DIR` | (falls back to cache)           | `/run/user/$UID` | Runtime files, logs        |
+
+For example, to store jolt's config in `~/.config` on macOS:
+
+```bash
+export XDG_CONFIG_HOME="$HOME/.config"
+```
+
+With this set, jolt will use `~/.config/jolt/config.toml` instead of `~/Library/Application Support/jolt/config.toml`.
+
 jolt creates this file automatically with default values on first run.
 
 ## Managing Config
@@ -155,11 +174,15 @@ Changes made in the config editor are saved immediately to the config file.
 
 Some settings can be overridden with environment variables:
 
-| Variable          | Description              |
-| ----------------- | ------------------------ |
-| `JOLT_CONFIG`     | Custom config file path  |
-| `JOLT_THEME`      | Override theme           |
-| `JOLT_APPEARANCE` | Override appearance mode |
+| Variable          | Description                                                                |
+| ----------------- | -------------------------------------------------------------------------- |
+| `JOLT_CONFIG`     | Custom config file path                                                    |
+| `JOLT_THEME`      | Override theme                                                             |
+| `JOLT_APPEARANCE` | Override appearance mode                                                   |
+| `XDG_CONFIG_HOME` | Override config directory (see [XDG support](#xdg-base-directory-support)) |
+| `XDG_DATA_HOME`   | Override data directory                                                    |
+| `XDG_CACHE_HOME`  | Override cache directory                                                   |
+| `XDG_RUNTIME_DIR` | Override runtime directory                                                 |
 
 Example: