Documentation
¶
Overview ¶
Package xdg resolves the XDG base directories, rooted at the user's home directory on every platform.
This is the single place to ask where user-scoped files belong, and the single way to resolve the home directory. No other package resolves home for itself: naming `HOME` — or `USERPROFILE` — anywhere else is what made the same logical location resolve to two different places on Windows.
Layout ¶
The standard XDG directory names, rooted at home, on every platform: `~/.config`, `~/.local/share`, `~/.local/state`, `~/.cache`, plus `~/.local/bin` for the de-facto XDG_BIN_HOME extension. The `XDG_*` variables override, as the specification requires. Windows gets no special case — it receives `%USERPROFILE%\.config` and friends rather than `%LOCALAPPDATA%`.
That is a deliberate divergence from the cross-platform directory libraries (Go's `adrg/xdg`, Python's `platformdirs`, Rust's `dirs`), which map the XDG roles onto Windows Known Folders. It follows git, Microsoft's own OpenSSH port, Docker, kubectl, cargo, Starship and WezTerm instead, so that people working across platforms meet one layout rather than three.
Resolving home ¶
A ladder, because no single source always answers:
- The role's `XDG_*` variable, when it names an **absolute** path. A relative value is invalid and ignored, per the specification, so resolution continues as though it were unset.
- os.UserHomeDir — the environment's answer, under whichever variable name the platform uses. It is a switch on GOOS, so it reads exactly one name per platform and never the others.
- user.Current — the operating system's answer: the process token's profile directory on Windows, the passwd entry on Unix. Reached when the environment is silent, which happens to services and scheduled tasks on Windows.
- Nothing left. That is an environment in which no anchor can be honored, so it asserts rather than returning a path no caller could use.
A fully configured environment never reaches rung 2: set every `XDG_*` variable absolutely and home is never consulted at all.
No runtime directory ¶
`XDG_RUNTIME_DIR` is deliberately absent. The specification gives it no default and tells applications without it to "fall back to a replacement directory with similar capabilities" — user-owned, 0700, lifetime bound to the session. That is precisely the session scratch directory (`op.RuntimeEnvironment.Scratch`), which exists on every platform and is removed when the session closes. An accessor here would report "unset" on macOS and Windows while the correct answer sat one call away under a better name.
Index ¶
- func BinHome() string
- func BinPath(elem ...string) string
- func CacheHome() string
- func CachePath(elem ...string) string
- func ConfigDirs() []string
- func ConfigHome() string
- func ConfigPath(elem ...string) string
- func DataDirs() []string
- func DataHome() string
- func DataPath(elem ...string) string
- func StateHome() string
- func StatePath(elem ...string) string
- func UserHomeDir() string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BinHome ¶
func BinHome() string
BinHome returns the base directory for user-specific executables.
`XDG_BIN_HOME` is a de-facto extension rather than part of the base specification, but `~/.local/bin` is where self-installation puts binaries and where shells expect to find them.
Returns:
- `string`: the value of `XDG_BIN_HOME` when absolute, else `~/.local/bin`.
func BinPath ¶
BinPath joins `elem` onto BinHome.
Parameters:
- `elem`: path elements below the base directory; the application name is simply the first of them.
Returns:
- `string`: the joined path.
func CacheHome ¶
func CacheHome() string
CacheHome returns the base directory for user-specific non-essential data.
Returns:
- `string`: the value of `XDG_CACHE_HOME` when absolute, else `~/.cache`.
func CachePath ¶
CachePath joins `elem` onto CacheHome.
Parameters:
- `elem`: path elements below the base directory; the application name is simply the first of them.
Returns:
- `string`: the joined path.
func ConfigDirs ¶
func ConfigDirs() []string
ConfigDirs returns the preference-ordered directories to search for configuration, after ConfigHome.
Returns:
- `[]string`: the absolute entries of `XDG_CONFIG_DIRS`, else the specification's default of `/etc/xdg`.
func ConfigHome ¶
func ConfigHome() string
ConfigHome returns the base directory for user-specific configuration.
Returns:
- `string`: the value of `XDG_CONFIG_HOME` when absolute, else `~/.config`.
func ConfigPath ¶
ConfigPath joins `elem` onto ConfigHome.
Parameters:
- `elem`: path elements below the base directory; the application name is simply the first of them.
Returns:
- `string`: the joined path.
func DataDirs ¶
func DataDirs() []string
DataDirs returns the preference-ordered directories to search for data files, after DataHome.
Returns:
- `[]string`: the absolute entries of `XDG_DATA_DIRS`, else the specification's defaults.
func DataHome ¶
func DataHome() string
DataHome returns the base directory for user-specific data files.
Returns:
- `string`: the value of `XDG_DATA_HOME` when absolute, else `~/.local/share`.
func DataPath ¶
DataPath joins `elem` onto DataHome.
Parameters:
- `elem`: path elements below the base directory; the application name is simply the first of them.
Returns:
- `string`: the joined path.
func StateHome ¶
func StateHome() string
StateHome returns the base directory for state that should persist between restarts but is not portable.
Logs, history, and recently-used lists live here rather than in DataHome.
Returns:
- `string`: the value of `XDG_STATE_HOME` when absolute, else `~/.local/state`.
func StatePath ¶
StatePath joins `elem` onto StateHome.
Parameters:
- `elem`: path elements below the base directory; the application name is simply the first of them.
Returns:
- `string`: the joined path.
func UserHomeDir ¶
func UserHomeDir() string
UserHomeDir returns the user's home directory, asking the operating system when the environment is silent.
Rungs 2 through 4 of the ladder described in the package documentation. Callers wanting a standard location should use the base accessors instead; this exists for the cases that genuinely mean *the home directory* — a deploy target, or expanding a leading `~` in user input.
Panics when neither the environment nor the user account yields a home directory, which requires the platform's home variable to be unset, the user account to be unreadable, and — on Unix built without cgo — no matching `/etc/passwd` entry. No anchor of any kind can be honored in that environment.
Returns:
- `string`: the home directory, never empty and never relative.
Types ¶
This section is empty.
Source Files