The default paths used to store configuration files and persistent data are not consistent across Emacs packages. This isn’t just a problem with third-party packages but even with built-in packages.
Some packages put these files directly in user-emacs-directory
or $HOME or in a subdirectory of either of the two or elsewhere.
Furthermore sometimes file names are used that don’t provide any
insight into what package might have created them.
This package sets out to fix this by changing the values of path
variables to put configuration files in no-littering-etc-directory
(defaulting to “etc/” under user-emacs-directory, thus usually
“$HOME/.config/emacs/etc/”) and persistent data files in
no-littering-var-directory (defaulting to “var/” under
user-emacs-directory, thus usually “$HOME/.config/emacs/var/”), and
by using descriptive file names and subdirectories when appropriate.
This is similar to a color-theme; a “path-theme” if you will.
We still have a long way to go until most built-in and many third-party path variables are properly “themed”. Like a color-theme, this package depends on user contributions to accomplish decent coverage. Pull requests are highly welcome (but please follow the conventions described below and in the pull request template).
This package does not automatically migrate existing files to their new locations, but unless you want to, you also do not have to do it completely by hand. The contributed migrate.org provides some guidance and tools to help with the migration.
Load the feature no-littering as early as possible in your init
file. Make sure you load it at least before you change any path
variables using some other method.
(require 'no-littering)If you would like to use base directories different from what
no-littering uses by default, then you have to set the respective
variables before loading the feature.
(eval-and-compile ; Ensure values don't differ at compile time.
(setq no-littering-etc-directory
(expand-file-name "config/" user-emacs-directory))
(setq no-littering-var-directory
(expand-file-name "data/" user-emacs-directory))
(require 'no-littering))Creating backups increases the odds that secret information, which would otherwise never be stored in clear text, is written to disk. Likewise backups increase the odds that leaked secrets persist longer.
This topic is beyond the scope of this documentation, but as the author of this package, I want to at least ensure that its use does not make matters worse.
For that reason, simply loading no-littering, does not theme the
built-in backup and auto-save functionality, and the third-party
undo-tree package.
A function no-littering-theme-backups is provided, which does theme
these features. Before calling that function from your init files,
you should read its docstring and implementation.
To put lock files into a single repository, you could use something like the following. See the docstring to learn about reasons why you might want to refrain from doing that.
(let ((dir (no-littering-expand-var-file-name "lock-files/")))
(make-directory dir t)
(setq lock-file-name-transforms `((".*" ,dir t))))If you use recentf then you might find it convenient to exclude all
of the files in the no-littering directories using something like
the following.
(require 'recentf)
(add-to-list 'recentf-exclude
(recentf-expand-file-name no-littering-var-directory))
(add-to-list 'recentf-exclude
(recentf-expand-file-name no-littering-etc-directory))Emacs will save customizations into your init.el file by default.
If you don’t want that, you might want to store them in a sibling file
or even in the etc/ directory:
(setq custom-file (expand-file-name "custom.el" user-emacs-directory))
;; or
(setq custom-file (no-littering-expand-etc-file-name "custom.el"))When using Emacs 29, the location of the native compilation cache can
be changed using a function, preferably in early-init.el:
(when (and (fboundp 'startup-redirect-eln-cache)
(fboundp 'native-comp-available-p)
(native-comp-available-p))
(startup-redirect-eln-cache
(convert-standard-filename
(expand-file-name "var/eln-cache/" user-emacs-directory))))The conventions do not cover every edge-case and are not set in stone. If you feel it is appropriate to diverge from what is outlined below, then do so, but provide justification in the commit message.
Likewise if you are unsure if you interpreted a convention correctly, just make a best effort, but mention it in the pull-request message, so we can improve the wording if necessary.
Generally there is no need to open an issue first; the maintainers can amend to your commit if necessary, or ask you to do so.
Each item below is prefixed with a checkbox to make it easier to not
forget about some of them. Unfortunately these checkboxes cannot
actually be checked on Github. Instead you have to either open the
README.org file in Emacs and then use C-c C-c to check a box, or use
the interactive checklist in a browser.
- [ ] File names are based on the name of the respective Emacs lisp variables and the name of the respective Emacs package.
- [ ] The name of the respective Emacs package should serve as the prefix of the file name, unless the file is in a subdirectory in which case the name of the subdirectory serves as the prefix.
- [ ] If the name of the package and the prefix of the variable do not match, then we prefer the name of the package.
- [ ] If the name of a path variable ends with
-file,-default-file,-directory,-default-directory, or something similar, then that suffix is usually dropped from the file name. - [ ] If applicable, the appropriate extension is added to the file
name so that files are visited using the appropriate major-modes
and also to provide a hint about the kind of data stored in the
file. E.g., if a file contains an S-expression, then the suffix
should be
.eld.(In the past we used
.elinstead, because.elddid not exist yet. Many themed files still use the.elsuffix, and I do not plan to update them to the preferred.eldsuffix any time soon. But for newly themed files.eldshould be preferred in most cases.)
- [ ] If a package has only one data file, then that is usually
placed in
no-littering-var-directoryitself. Likewise if a package has only one config file, then that is placed inno-littering-etc-directoryitself. - [ ] If a package has multiple data (or config files), then those
files are placed in a subdirectory of
no-littering-var-directory(orno-littering-etc-directory). - [ ] If a subdirectory is used for a package’s data (or config) file variables, then the name of the directory should match the name of the package in most cases. The subdirectory name may serve as the package prefix of the file name.
- [ ] If a package provides a “framework” for other packages to use,
then we may reuse its directories for other packages that make use
of that framework or otherwise “extend” the “main package”. E.g.,
we place all
helmrelated files inhelm/. - [ ] If a package only defines a single variable that specifies a
data (or config) directory, then the directory name should
nevertheless be just the package name. E.g., the path used for
sx-cache-directoryfrom thesxpackage issx/cache/, notsx-cache/. - [ ] However if the name of the directory variable implies that the
package won’t ever define any data (or config) files that won’t be
placed in that directory, then we use a top-level directory. E.g.,
when the name of the variable is
<package>-directory, in which case we would use just<package>/as the path.
- [ ] The code that sets the values of themed variables is split into two groups. The first group sets the value of variables that belong to packages that are part of Emacs, and the second group is used for variables that are defined by packages that are not part of Emacs.
- [ ] Each of these lists is sorted alphabetically (usually by variable name). Please keep it that way.
- [ ] We attempt to align the value forms inside different
setqforms. If the symbol part for a particular variable is too long to allow doing so, then don’t worry about it and just break the alignment. If it turns out that this happens very often, then we will adjust the alignment eventually.
- [ ] Please theme each package using a separate commit and use
commit messages of the form
foo: Theme foo-config-fileIn the commit message summary line, we do not quote variable names.
- [ ] If a package has several path variables, then you should theme them all in one commit.
- [ ] If the variable names do not fit nicely on the summary line,
then use a message such as:
foo: Theme variables Theme `foo-config-file', `foo-cache-directory', and `foo-persistent-file'.In the commit message body, we do quote variable names (using Emacs lisp docstring quoting, as shown above).
- [ ] When appropriate add statements like the following to the
commit message:
- This file is used to store an s-expression.
- This file is used to store raw text.
- This is the only configuration/data file of the package.
- This package does/doesn’t take care of creating the containing directory if necessary. (If the package does not do it, then you should also fix that and submit an pull-request in the package’s repository.)
- [ ] If you are uncertain, then be explicit about it by adding a comment to the pull-request.
- [ ] Please use a dedicated feature branch. See this explanation to learn why we ask for that.
- [ ] Please include a link to the package repository in the description of the pull-request.
