man(1)

NAME

xdg-env - Print XDG Base Directory paths.

SYNOPSIS
xdg-env [-h|--help] [-V|--version] [-p|--package package] [-d|--defaults-only] [-a|--all] [XDG_VARS...]

DESCRIPTION

This manual only describes the CLI usage of xdg-env. This manual does not describe how to use the Python API.

xdg-env can be used to determine XDG Base Directories as specified by either their environment variable overrides or the defaults as defined by the XDG Base Directory specification. When xdg-env prints values, it first searches for their respective environment variables. If they cannot be found, then xdg-env will revert back to the specification defined default values.

OPTIONS

-h,--help
    Displays the help menu.

-V,--version
    Displays the installed version number.

-p,--package=PACKAGE
    Optional package name that is appended to some variables. See below.

-d,--defaults-only
    Ignore environment variables, and output default values only.

-a,--all
    Prints all XDG Base Directory environment variables in a shell-sourceable format.

The optional package argument can be supplied to append a package name to some directories. For instance, many applications place their config files under ${XDG_CONFIG_HOME}/pkgname where pgkname is the name of the application. Their config file may end up being something to the effect of ${XDG_CONFIG_HOME}/pkgname/file.cfg . xdg-env clearly deviates from the specification here, so if this functionality is not desired then the CLI option can be ignored. It does however provide a handy shortcut when package specific directories need to be referenced.

ENVIRONMENT

Per the XDG Base Directory specification, xdg-env will either return the value of the user defined environment variable or the default per the specification. The relevant environment variables with their default values are:

    XDG_DATA_HOME=${HOME}/.local/share

    XDG_CONFIG_HOME=${HOME}/.config

    XDG_CACHE_HOME=${HOME}/.cache

    XDG_RUNTIME_DIR=/run/user/$(id -u)

    XDG_DATA_DIRS=/usr/local/share/:/usr/share/

    XDG_CONFIG_DIRS=/etc/xdg

There are a couple of exceptions to these default values. In particular, they change if running xdg-env on MacOS or Windows to appropriately (though subjectively) similar directories.

On MacOS, the only real issue with the XDG Base Directory specification is that the specification's XDG_RUNTIME_DIR points to a problematic directory on a MacOS system. Therefore, MacOS deviates from the XDG Base Directory specification for the environment variable as such:

    XDG_RUNTIME_DIR=/tmp/run/user/$(id -u)

For Windows, xdg-env generally replaces ${HOME} with %APPDATA%. Additionally, the Windows port will not include a preceding '.' in directory names. That said, it may not make much sense to use the XDG Base Directory specification on Windows. xdg-env simply exposes a Windows interface to help support Python packages that require access to XDG Base Directory environment variables. The Windows defaults that differ from the XDG Base Directory specification are:

    XDG_DATA_HOME=%APPDATA%/local/share

    XDG_CONFIG_HOME=%APPDATA%/config

    XDG_CACHE_HOME=%APPDATA%/cache

    XDG_RUNTIME_DIR=%APPDATA%/run/user/${USERNAME}

    XDG_DATA_DIRS=%APPDATA%/usr/share

    XDG_CONFIG_DIRS=%APPDATA%/etc/xdg

FILES

xdg-env itself does not directly reference directories or files. It does however print the names of directories or files based on the values specified either by the user defined environment variables or the values in the XDG Base Directory specification. That said, xdg-env does comes with a completion script usually installed as:

    ${HOME}/.local/bin/xdg-env-completion.bash

Once sourced, tab completion for the shell works for xdg-env command line options in addition to existing package names needed for the -p or --package options. Tab completing package names comes from existing directories under

    ~/.cache/

    ~/.config/

    ~/.local/share/

EXIT STATUS

0   If the command runs successfully.

1   If the specific XDG variable is invalid.
        For example: XDG_CONFIG_PATH, which should be XDG_CONFIG_HOME.

2   If the CLI options cannot be parsed properly, or invalid options are specified.

BUGS
For the latest list of known bugs, please refer to the list of open Issues in the code repository's issue tracker. (https://gitlab.com/deliberist/xdgenvpy/-/issues)

HISTORY
A full description of the history is documented in the code repository's CHANGELOG.md. (https://gitlab.com/deliberist/xdgenvpy/-/blob/master/CHANGELOG.md)

AUTHOR
Michael Durso Jr. (rbprogrammer@gmail.com)

SEE ALSO
xdgenvpy(3), python(1)

Also refer to the formal XDG Base Directory specification. (https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)