Skip to content

Instantly share code, notes, and snippets.

@Earnestly

Earnestly/dotlocal.adoc

Last active December 9, 2023 08:34
Show Gist options
  • Star 13 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save Earnestly/84cf9670b7e11ae2eac6f753910efebe to your computer and use it in GitHub Desktop.
Save Earnestly/84cf9670b7e11ae2eac6f753910efebe to your computer and use it in GitHub Desktop.
Download ZIP
Raw
dotlocal.adoc
Standards
Table of Contents

The .local Convention

HOME/.local
|- bin
|- include
|- etc
|- share
|- lib
|- man
`- var
   |- cache
   `- log

Legacy

As a large body of work [1] has already been done to support the XDG Base Directory Specification (XBDS) [2] it would seem necessary to demonstrate how those efforts can be reused without placing futher burden on developers.

For users they need only export XDG_CONFIG_HOME and XDG_DATA_HOME according to the Filesystem Hierarchy Standard (FHS) [3] such that HOME/.local is used as the prefix instead of the root directory (/). E.g.:

export XDG_CONFIG_HOME=$HOME/.local/etc
export XDG_CACHE_HOME=$HOME/.local/var/cache

It’s pertinent to note that XDG_DATA_HOME need not be set as the default fall back is identical to the location used under the .local convention.

Rationale

The XBDS was created over seventeen years (2003) ago to address the narrow needs of the X Desktop Group (now https://www.freedesktop.org) and their related per-user configuration and data files. Since then many [4] projects have adopted the specification as a solution to the uncontrolled [5] dotfile situation users have grown to dislike. [6]

The .local convention attempts to reuse the symmetry found in /usr/local by replicating it locally under HOME/.local.

This feature enables more software to be supported such as interpreters which create their own libraries, includes, or binaries as the original choice of HOME/.config, HOME/.local/share, and HOME/.cache was too limited. Additionally this solves the problem of some developers having to assume local libraries and binaries can be installed to XDG_DATA_HOME/../lib and XDG_DATA_HOME/../bin.

One of the benefits of this structure is it enables software to be installed by simply using a different prefix, e.g.

make PREFIX="$HOME"/.local install

The project systemd has already provided an example of its ideal file system hierarchy [7] which includes examples such as HOME/.local/bin [8] but these are hard-coded and not part of the XBDS.

By using HOME/.local as the main prefix it obviates the need for two additional and unnecessary dotfiles; .config and .cache.

As a result the .local provides the majority of the benefits of the XBDS with less ambiguity as HOME/.local cannot be changed via environment, while still being fully compatible with software that already supports the existing standard.

1. https://wiki.archlinux.org/index.php/XDG_Base_Directory
2. https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
3. https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard
4. https://wiki.archlinux.org/index.php/XDG_Base_Directory
5. http://pub.gajendra.net/2012/09/dotfiles
6. https://www.reddit.com/r/linux/comments/971m0z/im_tired_of_folders_littering_my_home_directory/
7. https://www.freedesktop.org/software/systemd/man/file-hierarchy.html
8. https://www.freedesktop.org/software/systemd/man/file-hierarchy.html#~/.local/bin/
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment