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.
- user.Current — the operating system's answer: the process token's profile directory on Windows, the passwd entry on Unix. This outranks the environment deliberately, following OpenSSH, which expands `~` from the account database and does not consult `HOME` at all. Where the two disagree — under `sudo`, or in a process someone handed a `HOME` — the account is the user, and the variable is a claim about the user.
- os.UserHomeDir — the environment's answer, under whichever variable name the platform uses. It is the rescue for users the account database cannot see: built without cgo, user.Current parses `/etc/passwd` and nothing else, so an LDAP, SSSD, or systemd-homed user resolves through the environment or not at all. Releases are built `CGO_ENABLED=0`, which makes this rung load-bearing rather than theoretical.
- 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.
Home is resolved, never injected ¶
Rung 2 outranking rung 3 means setting `HOME` does not move the home directory for any user the account database can see — which is nearly all of them. Code that needs to *redirect* a home-rooted location has two honest options: set the role's `XDG_*` variable, which rung 1 honors; or take the path as a parameter. Tests especially: a test that sets `HOME` and believes it has sandboxed anything is mistaken.
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
- func UserHomePath(elem ...string) 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 before the environment.
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 user account nor the environment yields a home directory. No anchor of any kind can be honored in that environment.
Returns:
- `string`: the home directory, never empty and never relative.
func UserHomePath ¶
UserHomePath joins `elem` onto UserHomeDir.
The home-directory analog of ConfigPath and its siblings, for the locations the specification does not name: a dot-directory owned by another tool (`~/.ssh`), an installation prefix (`~/.local`), or the tail of a path the user wrote with a leading `~`.
Parameters:
- `elem`: path elements below the home directory; none yields the home directory itself.
Returns:
- `string`: the joined path, always absolute.
Types ¶
This section is empty.
Source Files