Codebase list no-littering-el / 4269870
New upstream version 0.5.7 Lev Lamberov 6 years ago
3 changed file(s) with 474 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
+4
-0
.mailmap less more
0 Benjamin Frank <ben+github@pipsfrank.de>
1 Diego A. Mundo <diegoamundo@gmail.com>
2 Diego A. Mundo <diegoamundo@gmail.com> <therockmandolinist@users.noreply.github.com>
3 Justin Burkett <justin@burkett.cc>
+159
-0
README.md less more
0 Help keeping `~/.emacs.d` clean
1 ===============================
2
3 The default paths used to store configuration files and persistent
4 data are not consistent across Emacs packages. This isn't just a
5 problem with third-party packages but even with built-in packages.
6
7 Some packages put these files directly in `user-emacs-directory`
8 or `$HOME` or in a subdirectory of either of the two or elsewhere.
9 Furthermore sometimes file names are used that don't provide any
10 insight into what package might have created them.
11
12 This package sets out to fix this by changing the values of path
13 variables to put files in either `no-littering-etc-directory`
14 (defaulting to `~/.emacs.d/etc/`) or `no-littering-var-directory`
15 (defaulting to `~/.emacs.d/var/`), and by using descriptive file
16 names and subdirectories when appropriate. This is similar to a
17 color-theme; a "path-theme" if you will.
18
19 We still have a long way to go until most built-in and many
20 third-party path variables are properly "themed". Like a color-theme,
21 this package depends on user contributions to accomplish decent
22 coverage. Pull requests are highly welcome.
23
24 Usage
25 -----
26
27 Load the feature `no-littering` as early as possible in your init
28 file. Make sure you load it at least before you change any path
29 variables using some other method.
30
31 (require 'no-littering)
32
33 If you would like to use base directories different from what
34 `no-littering` uses by default, then you have to set the respective
35 variables before loading the feature.
36
37 (setq no-littering-etc-directory
38 (expand-file-name "config/" user-emacs-directory))
39 (setq no-littering-var-directory
40 (expand-file-name "data/" user-emacs-directory))
41 (require 'no-littering)
42
43 ### Suggested Settings
44
45 If you use `recentf` then you might find it convenient to exclude all
46 of the files in the `no-littering` directories using something like
47 the following.
48
49 (require 'recentf)
50 (add-to-list 'recentf-exclude no-littering-var-directory)
51 (add-to-list 'recentf-exclude no-littering-etc-directory)
52
53 #### Auto-save settings
54
55 One of the most common types of files that Emacs creates automatically
56 is auto-save files. By default, these appear in the current directory
57 of a visited file. No-littering does not change this, but you can add
58 the following code to your `init.el` file to store these files in the
59 var directory:
60
61 (setq auto-save-file-name-transforms
62 `((".*" ,(no-littering-expand-var-file-name "auto-save/") t))))
63
64 Conventions
65 -----------
66
67 ### File names
68
69 1. File names are based on the name of the respective Emacs lisp
70 variables and the name of the respective Emacs package.
71
72 2. The name of the respective Emacs package should serve as the
73 prefix of the file name, unless the file is in a subdirectory in
74 which case the name of the subdirectory serves as the prefix.
75
76 3. If the name of the package and the prefix of the variable do not
77 match, then we prefer the name of the package.
78
79 4. If the name of a path variable ends with `-file`, `-default-file`,
80 `-directory`, `-default-directory`, or something similar, then that
81 suffix is usually dropped from the file name.
82
83 5. If applicable, the appropriate extension is added to the file name
84 so that files are visited using the appropriate major-modes and
85 also to provide a hint about the kind of data stored in the file.
86 E.g. if a file contains an S-expression, then the suffix should be
87 `*.el`.
88
89 ### File location and subdirectories
90
91 1. If a package has only one data file, then that is usually placed in
92 `no-littering-var-directory` itself. Likewise if a package has
93 only one config file, then that is placed in
94 `no-littering-etc-directory` itself.
95
96 2. If a package has multiple data (or config files), then those files
97 are placed in a subdirectory of `no-littering-var-directory` (or
98 `no-littering-etc-directory`).
99
100 3. If a subdirectory is used for a package's data (or config) file
101 variables, then the name of the directory should match the name of
102 the package in most cases. The subdirectory name may serve as the
103 package prefix of the file name.
104
105 4. A package that provides a "framework" for other packages to use,
106 then we may reuse its directories for other packages that make use
107 of that framework or otherwise "extend" the "main package".
108 E.g. we place all `helm` related files in `helm/`.
109
110 5. If a package only defines a single variable that specifies a data
111 (or config) directory, then the directory name should
112 nevertheless be just the package name. E.g. the path used for
113 `sx-cache-directory` from the `sx` package is `sx/cache/`, not
114 `sx-cache/`.
115
116 6. However if the name of the directory variable implies that the
117 package won't ever define any data (or config) files that won't be
118 placed in that directory, then we use a top-level directory. E.g.
119 when the name of the variable is `<package>-directory`, in which
120 case we would use just `<package>/` as the path.
121
122 ### Ordering and alignment
123
124 1. The code that sets the values of themed variables is split into two
125 groups. The first group sets the value of variables that belong to
126 packages that are part of Emacs, and the second group is used for
127 variables that are defined by packages that are not part of Emacs.
128
129 2. Each of these lists is sorted alphabetically (usually by variable
130 name). Please keep it that way.
131
132 3. We attempt to align the value forms inside different `setq` forms.
133 If the symbol part for a particular variable is too long to allow
134 doing so, then don't worry about it and just break the alignment.
135 If it turns out that this happens very often, then we will adjust
136 the alignment eventually.
137
138 ### Commit messages
139
140 1. Please theme each package using a separate commit and use commit
141 messages of the form "<package>: theme <variable".
142
143 2. If a package has several path variables, then you should theme them
144 all in one commit.
145
146 3. If the variable names do not fit nicely on the summary line, then
147 use a message such as:
148
149 ```
150 foo: theme variables
151
152 Theme `foo-config-file', `foo-cache-directory',
153 and `foo-persistent-file'.
154 ```
155
156 <!-- Local Variables: -->
157 <!-- fill-column: 70 -->
158 <!-- End: -->
+311
-0
no-littering.el less more
0 ;;; no-littering.el --- help keeping ~/.emacs.d clean
1
2 ;; Copyright (C) 2016-2017 Jonas Bernoulli
3
4 ;; Author: Jonas Bernoulli <jonas@bernoul.li>
5 ;; Homepage: https://github.com/tarsius/no-littering
6 ;; Package-Requires: ((cl-lib "0.5"))
7
8 ;; This file is not part of GNU Emacs.
9
10 ;; This file is free software; you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation; either version 3, or (at your option)
13 ;; any later version.
14
15 ;; This file is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
19
20 ;; For a full copy of the GNU General Public License
21 ;; see https://www.gnu.org/licenses.
22
23 ;;; Commentary:
24
25 ;; Help keeping ~/.emacs.d clean.
26
27 ;; The default paths used to store configuration files and persistent
28 ;; data are not consistent across Emacs packages. This isn't just a
29 ;; problem with third-party packages but even with built-in packages.
30
31 ;; Some packages put these files directly in `user-emacs-directory'
32 ;; or $HOME or in a subdirectory of either of the two or elsewhere.
33 ;; Furthermore sometimes file names are used that don't provide any
34 ;; insight into what package might have created them.
35
36 ;; This package sets out to fix this by changing the values of path
37 ;; variables to put files in either `no-littering-etc-directory'
38 ;; (defaulting to "~/.emacs.d/etc/") or `no-littering-var-directory'
39 ;; (defaulting to "~/.emacs.d/var/"), and by using descriptive file
40 ;; names and subdirectories when appropriate. This is similar to a
41 ;; color-theme; a "path-theme" if you will.
42
43 ;; We still have a long way to go until most built-in and many third-
44 ;; party path variables are properly "themed". Like a color-theme,
45 ;; this package depends on user contributions to accomplish decent
46 ;; coverage. Pull requests are highly welcome.
47
48 ;; Usage:
49
50 ;; Load the feature `no-littering' as early as possible in your init
51 ;; file. Make sure you load it at least before you change any path
52 ;; variables using some other method.
53 ;;
54 ;; (require 'no-littering)
55
56 ;; If you would like to use base directories different from what
57 ;; `no-littering' uses by default, then you have to set the respective
58 ;; variables before loading the feature.
59 ;;
60 ;; (setq no-littering-etc-directory
61 ;; (expand-file-name "config/" user-emacs-directory))
62 ;; (setq no-littering-var-directory
63 ;; (expand-file-name "data/" user-emacs-directory))
64 ;; (require 'no-littering)
65
66 ;; Conventions:
67
68 ;; * File names
69 ;;
70 ;; 1. File names are based on the name of the respective Emacs Lisp
71 ;; variables and the name of the respective Emacs package.
72 ;;
73 ;; 2. The name of the respective Emacs package should serve as the
74 ;; prefix of the file name, unless the file is in a subdirectory in
75 ;; which case the name of the subdirectory serves as the prefix.
76 ;;
77 ;; 3. If the name of the package and the prefix of the variable do not
78 ;; match, then we prefer the name of the package.
79 ;;
80 ;; 4. If the name of a path variable ends with `-file`, `-default-file`,
81 ;; `-directory`, `-default-directory`, or something similar, then that
82 ;; suffix is usually dropped from the file name.
83 ;;
84 ;; 5. If applicable, the appropriate extension is added to the file name
85 ;; so that files are visited using the appropriate major-modes and
86 ;; also to provide a hint about the kind of data stored in the file.
87 ;; E.g. if a file contains an S-expression, then the suffix should be
88 ;; `*.el`.
89
90 ;; * File location and subdirectories
91 ;;
92 ;; 1. If a package has only one data file, then that is usually placed in
93 ;; `no-littering-var-directory` itself. Likewise if a package has
94 ;; only one config file, then that is placed in
95 ;; `no-littering-etc-directory` itself.
96 ;;
97 ;; 2. If a package has multiple data (or config files), then those files
98 ;; are placed in a subdirectory of `no-littering-var-directory` (or
99 ;; `no-littering-etc-directory`).
100 ;;
101 ;; 3. If a subdirectory is used for a package's data (or config) file
102 ;; variables, then the name of the directory should match the name of
103 ;; the package in most cases. The subdirectory name may serve as the
104 ;; package prefix of the file name.
105 ;;
106 ;; 4. A package that provides a "framework" for other packages to use,
107 ;; then we may reuse its directories for other packages that make use
108 ;; of that framework or otherwise "extend" the "main package".
109 ;; E.g. we place all `helm` related files in `helm/`.
110 ;;
111 ;; 5. If a package only defines a single variable that specifies a data
112 ;; (or config) directory, then the directory name should
113 ;; nevertheless be just the package name. E.g. the path used for
114 ;; `sx-cache-directory` from the `sx` package is `sx/cache/`, not
115 ;; `sx-cache/`.
116 ;;
117 ;; 6. However if the name of the directory variable implies that the
118 ;; package won't ever define any data (or config) files that won't be
119 ;; placed in that directory, then we use a top-level directory. E.g.
120 ;; when the name of the variable is `<package>-directory`, in which
121 ;; case we would use just `<package>/` as the path.
122
123 ;; * Ordering and alignment
124 ;;
125 ;; 1. The code that sets the values of themed variables is split into two
126 ;; groups. The first group sets the value of variables that belong to
127 ;; packages that are part of Emacs, and the second group is used for
128 ;; variables that are defined by packages that are not part of Emacs.
129 ;;
130 ;; 2. Each of these lists is sorted alphabetically (usually by variable
131 ;; name). Please keep it that way.
132 ;;
133 ;; 3. We attempt to align the value forms inside different `setq` forms.
134 ;; If the symbol part for a particular variable is too long to allow
135 ;; doing so, then don't worry about it and just break the alignment.
136 ;; If it turns out that this happens very often, then we will adjust
137 ;; the alignment eventually.
138
139 ;; * Commit messages
140 ;;
141 ;; 1. Please theme each package using a separate commit and use commit
142 ;; messages of the form "<package>: theme <variable".
143 ;;
144 ;; 2. If a package has several path variables, then you should theme them
145 ;; all in one commit.
146 ;;
147 ;; 3. If the variable names do not fit nicely on the summary line, then
148 ;; use a message such as:
149 ;;
150 ;; foo: theme variables
151 ;;
152 ;; Theme `foo-config-file', `foo-cache-directory',
153 ;; and `foo-persistent-file'.
154
155 ;;; Code:
156
157 (require 'cl-lib)
158
159 (defvar no-littering-etc-directory
160 (expand-file-name (convert-standard-filename "etc/") user-emacs-directory)
161 "The directory where packages place their configuration files.
162 This variable has to be set before `no-littering' is loaded.")
163
164 (defvar no-littering-var-directory
165 (expand-file-name (convert-standard-filename "var/") user-emacs-directory)
166 "The directory where packages place their persistent data files.
167 This variable has to be set before `no-littering' is loaded.")
168
169 (defun no-littering-expand-etc-file-name (file)
170 "Expand filename FILE relative to `no-littering-etc-directory'."
171 (expand-file-name (convert-standard-filename file)
172 no-littering-etc-directory))
173
174 (defun no-littering-expand-var-file-name (file)
175 "Expand filename FILE relative to `no-littering-var-directory'."
176 (expand-file-name (convert-standard-filename file)
177 no-littering-var-directory))
178
179 (cl-letf (((symbol-function 'etc)
180 (symbol-function #'no-littering-expand-etc-file-name))
181 ((symbol-function 'var)
182 (symbol-function #'no-littering-expand-var-file-name)))
183 (with-no-warnings ; many of these variables haven't been defined yet
184
185 ;;; Built-in packages
186
187 (setq abbrev-file-name (var "abbrev.el"))
188 (setq auto-insert-directory (etc "auto-insert/"))
189 (setq auto-save-list-file-prefix (var "auto-save/sessions/"))
190 (setq backup-directory-alist (list (cons "." (var "backup/"))))
191 (setq bookmark-default-file (var "bookmark-default.el"))
192 (eval-after-load 'desktop
193 `(make-directory ,(var "desktop/") t))
194 (setq desktop-path (list (var "desktop/")))
195 (setq eshell-directory-name (var "eshell/"))
196 (eval-after-load 'eww
197 `(make-directory ,(var "eww/") t))
198 (setq eww-bookmarks-directory (var "eww/"))
199 (setq gamegrid-user-score-file-directory (var "gamegrid-user-score/"))
200 (setq ido-save-directory-list-file (var "ido-save-directory-list.el"))
201 (setq image-dired-db-file (var "image-dired/db.el"))
202 (setq image-dired-dir (var "image-dired/"))
203 (setq image-dired-gallery-dir (var "image-dired/gallery/"))
204 (setq image-dired-temp-image-file (var "image-dired/temp-image"))
205 (setq image-dired-temp-rotate-image-file (var "image-dired/temp-rotate-image"))
206 (eval-after-load 'newsticker
207 `(make-directory ,(var "newsticker/") t))
208 (setq newsticker-cache-filename (var "newsticker/cache.el"))
209 (setq newsticker-dir (var "newsticker/data/"))
210 (setq nsm-settings-file (var "nsm-settings.el"))
211 (eval-after-load 'org
212 `(make-directory ,(var "org/") t))
213 (setq org-clock-persist-file (var "org/clock-persist.el"))
214 (setq org-id-locations-file (var "org/id-locations.el"))
215 (setq org-registry-file (var "org/registry.el"))
216 (setq recentf-save-file (var "recentf-save.el"))
217 (setq save-place-file (var "save-place.el"))
218 (setq savehist-file (var "savehist.el"))
219 (setq semanticdb-default-save-directory (var "semantic/"))
220 (setq shared-game-score-directory (var "shared-game-score/"))
221 (setq tramp-auto-save-directory (var "tramp/auto-save/"))
222 (setq tramp-persistency-file-name (var "tramp/persistency.el"))
223 (setq url-cache-directory (var "url/cache/"))
224 (setq url-configuration-directory (var "url/configuration/"))
225
226 ;;; Third-party packages
227
228 (setq ac-comphist-file (var "ac-comphist.el"))
229 (setq anaconda-mode-installation-directory (etc "anaconda-mode/"))
230 (eval-after-load 'bbdb
231 `(make-directory ,(var "bbdb/") t))
232 (setq bbdb-file (var "bbdb/bbdb.el"))
233 (setq bbdb-vcard-directory (var "bbdb/vcard/"))
234 (setq bm-repository-file (var "bm-repository.el"))
235 (eval-after-load 'bookmark+-1
236 `(make-directory ,(var "bmkp/") t))
237 (setq bmkp-current-bookmark-file (var "bmkp/current-bookmark.el"))
238 (setq bmkp-last-bookmark-file (var "bmkp/last-bookmark.el"))
239 (eval-after-load 'company-statistics
240 `(make-directory ,(var "company/") t))
241 (setq company-statistics-file (var "company/statistics.el"))
242 (eval-after-load 'elfeed
243 `(make-directory ,(var "elfeed/") t))
244 (setq elfeed-db-directory (var "elfeed/db/"))
245 (setq elfeed-enclosure-default-dir (var "elfeed/enclosures/"))
246 (eval-after-load 'x-win
247 (let ((session-dir (var "emacs-session/")))
248 `(progn
249 (make-directory ,session-dir t)
250 (defun emacs-session-filename (session-id)
251 "Construct a filename to save the session in based on SESSION-ID.
252 This function overrides the one on `x-win' to use `no-littering'
253 directories."
254 (expand-file-name session-id ,session-dir)))))
255 (setq emms-directory (var "emms/"))
256 (eval-after-load 'emojify
257 `(make-directory ,(var "emojify/") t))
258 (setq emojify-emojis-dir (var "emojify/"))
259 (eval-after-load 'helm
260 `(make-directory ,(var "helm/") t))
261 (setq helm-adaptive-history-file (var "helm/adaptive-history.el"))
262 (setq helm-github-stars-cache-file (var "helm/github-stars-cache.el"))
263 (setq historian-save-file (var "historian-save.el"))
264 (setq irony-user-dir (var "irony/"))
265 (setq jabber-avatar-cache-directory (var "jabber/avatar-cache"))
266 (eval-after-load 'jabber
267 `(make-directory ,(var "jabber/avatar-cache/") t))
268 (setq jabber-history-dir (var "jabber/history"))
269 (eval-after-load 'jabber
270 `(make-directory ,(var "jabber/history/") t))
271 (setq mc/list-file (var "mc-list.el"))
272 (setq multi-compile-history-file (var "multi-compile-history.el"))
273 (setq org-gcal-dir (var "org/gcal/"))
274 (eval-after-load 'org-caldav
275 `(make-directory ,(var "org/caldav/save") t))
276 (setq org-caldav-backup-file (var "org/caldav/backup.org"))
277 (setq org-caldav-save-directory (var "org/caldav/save"))
278 (setq pcache-directory (var "pcache/"))
279 (setq persistent-scratch-save-file (var "persistent-scratch.el"))
280 (setq persp-save-dir (var "persp-mode/"))
281 (eval-after-load 'projectile
282 `(make-directory ,(var "projectile/") t))
283 (setq projectile-cache-file (var "projectile/cache.el"))
284 (setq projectile-known-projects-file (var "projectile/known-projects.el"))
285 (setq request-storage-directory (var "request/storage/"))
286 (setq rmh-elfeed-org-files (list (var "elfeed/rmh-elfeed.org")))
287 (setq runner-init-file (var "runner-init.el"))
288 (setq save-kill-file-name (var "save-kill.el"))
289 (setq save-visited-files-location (var "save-visited-files-location"))
290 (setq smex-save-file (var "smex-save.el"))
291 (setq speed-type-gb-dir (var "speed-type/"))
292 (eval-after-load 'sx
293 `(make-directory ,(var "sx/cache/") t))
294 (setq sx-cache-directory (var "sx/cache/"))
295 (setq undo-tree-history-directory-alist (list (cons "." (var "undo-tree-hist/"))))
296 (setq user-emacs-ensime-directory (var "ensime/"))
297 (eval-after-load 'xkcd
298 `(make-directory ,(var "xkcd/") t))
299 (setq xkcd-cache-dir (var "xkcd/"))
300 (eval-after-load 'yasnippet
301 `(make-directory ,(etc "yasnippet/snippets/") t))
302 (setq yas-snippet-dirs (list (etc "yasnippet/snippets/")
303 'yas-installed-snippets-dir))
304 ))
305
306 (provide 'no-littering)
307 ;; Local Variables:
308 ;; indent-tabs-mode: nil
309 ;; End:
310 ;;; no-littering.el ends here