[rc/{notmuch,offlineimap}] migrate to new literate setup
[~bandali/configs] / init.org
1 #+title: =aminb='s Literate Emacs Configuration
2 #+author: Amin Bandali
3 #+babel: :cache yes
4 #+property: header-args :tangle yes
5
6 * About
7 :PROPERTIES:
8 :CUSTOM_ID: about
9 :END:
10
11 This org file is my literate configuration for GNU Emacs, and is
12 tangled to [[./init.el][init.el]]. Packages are installed and managed using [[https://github.com/emacscollective/borg][Borg]].
13
14 ** Installation
15
16 I'd like to have a fully reproducible Emacs setup (part of the reason
17 why I store my configuration in this repository) but unfortunately out
18 of the box, that's not achievable with =package.el=, not currently
19 anyway. So, I've opted to use Borg. For what it's worth, I briefly
20 experimented with [[https://github.com/raxod502/straight.el][straight.el]], but found that it added about 2 seconds
21 to my init time; which is unacceptable for me: I use Emacs as my
22 window manager (via EXWM) and coming from bspwm, I'm too used to
23 having fast startup times.
24
25 * Contents :toc_1:noexport:
26
27 - [[#about][About]]
28 - [[#header][Header]]
29 - [[#initial-setup][Initial setup]]
30 - [[#core][Core]]
31 - [[#post-initialization][Post initialization]]
32 - [[#footer][Footer]]
33
34 * Header
35 :PROPERTIES:
36 :CUSTOM_ID: header
37 :END:
38
39 ** First line
40
41 #+begin_src emacs-lisp :comments none
42 ;;; init.el --- Amin Bandali's Emacs config -*- lexical-binding: t ; eval: (view-mode 1)-*-
43 #+end_src
44
45 Enable =view-mode=, which both makes the file read-only (as a reminder
46 that =init.el= is an auto-generated file, not supposed to be edited),
47 and provides some convenient key bindings for browsing through the
48 file.
49
50 ** License
51
52 #+begin_src emacs-lisp :comments none
53 ;; Copyright (C) 2018 Amin Bandali <amin@aminb.org>
54
55 ;; This program is free software: you can redistribute it and/or modify
56 ;; it under the terms of the GNU General Public License as published by
57 ;; the Free Software Foundation, either version 3 of the License, or
58 ;; (at your option) any later version.
59
60 ;; This program is distributed in the hope that it will be useful,
61 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
62 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
63 ;; GNU General Public License for more details.
64
65 ;; You should have received a copy of the GNU General Public License
66 ;; along with this program. If not, see <https://www.gnu.org/licenses/>.
67 #+end_src
68
69 ** Commentary
70
71 #+begin_src emacs-lisp :comments none
72 ;;; Commentary:
73
74 ;; Emacs configuration of Amin Bandali, computer scientist and functional
75 ;; programmer.
76
77 ;; THIS FILE IS AUTO-GENERATED FROM `init.org'.
78 #+end_src
79
80 ** Naming conventions
81
82 The conventions below were inspired by [[https://github.com/hlissner/doom-emacs][Doom]]'s conventions, found
83 [[https://github.com/hlissner/doom-emacs/blob/5dacbb7cb1c6ac246a9ccd15e6c4290def67757c/core/core.el#L3-L17][here]]. Naturally, I use my initials, =ab=, instead of =doom=.
84
85 #+begin_src emacs-lisp :comments none
86 ;; Naming conventions:
87 ;;
88 ;; ab-... public variables or non-interactive functions
89 ;; ab--... private anything (non-interactive), not safe for direct use
90 ;; ab/... an interactive function; safe for M-x or keybinding
91 ;; ab:... an evil operator, motion, or command
92 ;; ab|... a hook function
93 ;; ab*... an advising function
94 ;; ab@... a hydra command
95 ;; ...! a macro
96 #+end_src
97
98 * Initial setup
99 :PROPERTIES:
100 :CUSTOM_ID: initial-setup
101 :END:
102
103 #+begin_src emacs-lisp :comments none
104 ;;; Code:
105 #+end_src
106
107 ** Emacs initialization
108
109 I'd like to do a couple of measurements of Emacs' startup time. First,
110 let's see how long Emacs takes to start up, before even loading
111 =init.el=, i.e. =user-init-file=:
112
113 #+begin_src emacs-lisp
114 (defvar ab--before-user-init-time (current-time)
115 "Value of `current-time' when Emacs begins loading `user-init-file'.")
116 (message "Loading Emacs...done (%.3fs)"
117 (float-time (time-subtract ab--before-user-init-time
118 before-init-time)))
119 #+end_src
120
121 Also, temporarily increase ~gc-cons-threshhold~ and
122 ~gc-cons-percentage~ during startup to reduce garbage collection
123 frequency. Clearing the ~file-name-handler-alist~ seems to help reduce
124 startup time as well.
125
126 #+begin_src emacs-lisp
127 (defvar ab--gc-cons-threshold gc-cons-threshold)
128 (defvar ab--gc-cons-percentage gc-cons-percentage)
129 (defvar ab--file-name-handler-alist file-name-handler-alist)
130 (setq gc-cons-threshold (* 400 1024 1024) ; 400 MiB
131 gc-cons-percentage 0.6
132 file-name-handler-alist nil
133 ;; sidesteps a bug when profiling with esup
134 esup-child-profile-require-level 0)
135 #+end_src
136
137 Of course, we'd like to set them back to their defaults once we're
138 done initializing.
139
140 #+begin_src emacs-lisp
141 (add-hook
142 'after-init-hook
143 (lambda ()
144 (let ((elapsed (float-time (time-subtract (current-time)
145 ab--before-user-init-time))))
146 (message "Loading %s...done (%.3fs) [after-init]"
147 user-init-file elapsed))
148 (setq gc-cons-threshold ab--gc-cons-threshold
149 gc-cons-percentage ab--gc-cons-percentage
150 file-name-handler-alist ab--file-name-handler-alist)))
151 #+end_src
152
153 Increase the number of lines kept in message logs (the =*Messages*=
154 buffer).
155
156 #+begin_src emacs-lisp
157 (setq message-log-max 20000)
158 #+end_src
159
160 Optionally, we could suppress some byte compiler warnings like below,
161 but for now I've decided to keep them enabled. See documentation for
162 ~byte-compile-warnings~ for more details.
163
164 #+begin_src emacs-lisp
165 ;; (setq byte-compile-warnings
166 ;; '(not free-vars unresolved noruntime lexical make-local))
167 #+end_src
168
169 ** Package management
170
171 *** No =package.el=
172
173 I can do all my package management things with Borg, and don't need
174 Emacs' built-in =package.el=. Emacs 27 lets us disable =package.el= in
175 the =early-init-file= (see [[https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=24acb31c04b4048b85311d794e600ecd7ce60d3b][here]]).
176
177 #+begin_src emacs-lisp :tangle early-init.el
178 (setq package-enable-at-startup nil)
179 #+end_src
180
181 But since Emacs 27 isn't out yet (Emacs 26 is just around the corner
182 right now), and even when released it'll be long before most distros
183 ship in their repos, I'll still put the old workaround with the
184 commented call to ~package-initialize~ here anyway.
185
186 #+begin_src emacs-lisp
187 (setq package-enable-at-startup nil)
188 ;; (package-initialize)
189 #+end_src
190
191 *** Borg
192
193 #+begin_quote
194 Assimilate Emacs packages as Git submodules
195 #+end_quote
196
197 [[https://github.com/emacscollective/borg][Borg]] is at the heart of package management of my Emacs setup. In
198 short, it creates a git submodule in =lib/= for each package, which
199 can then be managed with the help of Magit or other tools.
200
201 #+begin_src emacs-lisp
202 (setq user-init-file (or load-file-name buffer-file-name)
203 user-emacs-directory (file-name-directory user-init-file))
204 (add-to-list 'load-path
205 (expand-file-name "lib/borg" user-emacs-directory))
206 (require 'borg)
207 (borg-initialize)
208 #+end_src
209
210 *** =use-package=
211
212 #+begin_quote
213 A use-package declaration for simplifying your .emacs
214 #+end_quote
215
216 [[https://github.com/jwiegley/use-package][use-package]] is an awesome utility for managing and configuring
217 packages (in our case especially the latter) in a neatly organized way
218 and without compromising on performance.
219
220 #+begin_src emacs-lisp
221 (require 'use-package)
222 (if nil ; set to t when need to debug init
223 (setq use-package-verbose t
224 use-package-expand-minimally nil
225 use-package-compute-statistics t
226 debug-on-error t)
227 (setq use-package-verbose nil
228 use-package-expand-minimally t))
229 #+end_src
230
231 *** Epkg
232
233 #+begin_quote
234 Browse the Emacsmirror package database
235 #+end_quote
236
237 Epkg provides access to a local copy of the [[https://emacsmirror.net][Emacsmirror]] package
238 database, low-level functions for querying the database, and a
239 =package.el=-like user interface for browsing the available packages.
240
241 #+begin_src emacs-lisp
242 (use-package epkg
243 :defer t)
244 #+end_src
245
246 ** No littering in =~/.emacs.d=
247
248 #+begin_quote
249 Help keeping ~/.emacs.d clean
250 #+end_quote
251
252 By default, even for Emacs' built-in packages, the configuration files
253 and persistent data are all over the place. Use =no-littering= to help
254 contain the mess.
255
256 #+begin_src emacs-lisp
257 (use-package no-littering
258 :demand t
259 :config
260 (savehist-mode 1)
261 (add-to-list 'savehist-additional-variables 'kill-ring)
262 (save-place-mode 1)
263 (setq auto-save-file-name-transforms
264 `((".*" ,(no-littering-expand-var-file-name "auto-save/") t))))
265 #+end_src
266
267 ** Custom file (=custom.el=)
268
269 I'm not planning on using the custom file much, but even so, I
270 definitely don't want it mixing with =init.el=. So, here; let's give
271 it it's own file. While at it, treat themes as safe.
272
273 #+begin_src emacs-lisp
274 (use-package custom
275 :no-require t
276 :config
277 (setq custom-file (no-littering-expand-etc-file-name "custom.el"))
278 (when (file-exists-p custom-file)
279 (load custom-file))
280 (setf custom-safe-themes t))
281 #+end_src
282
283 ** Better =$PATH= handling
284
285 Let's use [[https://github.com/purcell/exec-path-from-shell][exec-path-from-shell]] to make Emacs use the =$PATH= as set up
286 in my shell.
287
288 #+begin_src emacs-lisp
289 (use-package exec-path-from-shell
290 :defer 1
291 :init
292 (setq exec-path-from-shell-check-startup-files nil)
293 :config
294 (exec-path-from-shell-initialize)
295 ;; while we're at it, let's fix access to our running ssh-agent
296 (exec-path-from-shell-copy-env "SSH_AGENT_PID")
297 (exec-path-from-shell-copy-env "SSH_AUTH_SOCK"))
298 #+end_src
299
300 ** Server
301
302 Start server if not already running. Alternatively, can be done by
303 issuing =emacs --daemon= in the terminal, which can be automated with
304 a systemd service or using =brew services start emacs= on macOS. I use
305 Emacs as my window manager (via EXWM), so I always start Emacs on
306 login; so starting the server from inside Emacs is good enough for me.
307
308 See [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html#Emacs-Server][Using Emacs as a Server]].
309
310 #+begin_src emacs-lisp
311 (use-package server
312 :config (or (server-running-p) (server-mode)))
313 #+end_src
314
315 * Core
316 :PROPERTIES:
317 :CUSTOM_ID: core
318 :END:
319
320 ** Defaults
321
322 *** Smaller fringe
323
324 Might want to set the fringe to a smaller value, especially if using
325 EXWM. I'm fine with the default for now.
326
327 #+begin_src emacs-lisp
328 ;; (fringe-mode '(3 . 1))
329 #+end_src
330
331 *** Disable disabled commands
332
333 Emacs disables some commands by default that could persumably be
334 confusing for novice users. Let's disable that.
335
336 #+begin_src emacs-lisp
337 (setq disabled-command-function nil)
338 #+end_src
339
340 *** Kill-ring
341
342 Save what I copy into clipboard from other applications into Emacs'
343 kill-ring, which would allow me to still be able to easily access it
344 in case I kill (cut or copy) something else inside Emacs before
345 yanking (pasting) what I'd originally intended to.
346
347 #+begin_src emacs-lisp
348 (setq save-interprogram-paste-before-kill t)
349 #+end_src
350
351 *** Minibuffer
352
353 #+begin_src emacs-lisp
354 (setq enable-recursive-minibuffers t
355 resize-mini-windows t)
356 #+end_src
357
358 *** Lazy-person-friendly yes/no prompts
359
360 Lazy people would prefer to type fewer keystrokes, especially for yes
361 or no questions. I'm lazy.
362
363 #+begin_src emacs-lisp
364 (defalias 'yes-or-no-p #'y-or-n-p)
365 #+end_src
366
367 *** Startup screen and =*scratch*=
368
369 Firstly, let Emacs know that I'd like to have =*scratch*= as my
370 startup buffer.
371
372 #+begin_src emacs-lisp
373 (setq initial-buffer-choice t)
374 #+end_src
375
376 Now let's customize the =*scratch*= buffer a bit. First off, I don't
377 need the default hint.
378
379 #+begin_src emacs-lisp
380 (setq initial-scratch-message nil)
381 #+end_src
382
383 Also, let's use Text mode as the major mode, in case I want to
384 customize it (=*scratch*='s default major mode, Fundamental mode,
385 can't really be customized).
386
387 #+begin_src emacs-lisp
388 (setq initial-major-mode 'text-mode)
389 #+end_src
390
391 Inhibit the buffer list when more than 2 files are loaded.
392
393 #+begin_src emacs-lisp
394 (setq inhibit-startup-buffer-menu t)
395 #+end_src
396
397 I don't really need to see the startup screen or echo area message
398 either.
399
400 #+begin_src emacs-lisp
401 (advice-add #'display-startup-echo-area-message :override #'ignore)
402 (setq inhibit-startup-screen t
403 inhibit-startup-echo-area-message user-login-name)
404 #+end_src
405
406 *** More useful frame titles
407
408 Show either the file name or the buffer name (in case the buffer isn't
409 visiting a file). Borrowed from Emacs Prelude.
410
411 #+begin_src emacs-lisp
412 (setq frame-title-format
413 '("" invocation-name " - "
414 (:eval (if (buffer-file-name)
415 (abbreviate-file-name (buffer-file-name))
416 "%b"))))
417 #+end_src
418
419 *** Backups
420
421 Emacs' default backup settings aren't that great. Let's use more
422 sensible options. See documentation for the ~make-backup-file~
423 variable.
424
425 #+begin_src emacs-lisp
426 (setq backup-by-copying t
427 version-control t)
428 #+end_src
429
430 ** Packages
431
432 The packages in this section are absolutely essential to my everyday
433 workflow, and they play key roles in how I do my computing. They
434 immensely enhance the Emacs experience for me; both using Emacs, and
435 customizing it.
436
437 *** [[https://github.com/emacscollective/auto-compile][auto-compile]]
438
439 #+begin_src emacs-lisp
440 (use-package auto-compile
441 :demand t
442 :config
443 (auto-compile-on-load-mode)
444 (auto-compile-on-save-mode)
445 (setq auto-compile-display-buffer nil
446 auto-compile-mode-line-counter t
447 auto-compile-source-recreate-deletes-dest t
448 auto-compile-toggle-deletes-nonlib-dest t
449 auto-compile-update-autoloads t)
450 (add-hook 'auto-compile-inhibit-compile-hook
451 'auto-compile-inhibit-compile-detached-git-head))
452 #+end_src
453
454 *** TODO [[https://github.com/Kungsgeten/ryo-modal][ryo-modal]]
455
456 #+begin_quote
457 Roll your own modal mode
458 #+end_quote
459
460 *** [[https://github.com/ch11ng/exwm][EXWM]] (window manager)
461
462 #+begin_src emacs-lisp
463 (use-package exwm
464 :demand t
465 :config
466 (require 'exwm-config)
467 (exwm-config-default)
468 (require 'exwm-systemtray)
469 (exwm-systemtray-enable)
470 (require 'exwm-randr)
471 (exwm-randr-enable))
472 #+end_src
473
474 *** [[https://orgmode.org/][Org mode]]
475
476 #+begin_quote
477 Org mode is for keeping notes, maintaining TODO lists, planning
478 projects, and authoring documents with a fast and effective plain-text
479 system.
480 #+end_quote
481
482 In short, my favourite way of life.
483
484 #+begin_src emacs-lisp
485 (setq org-src-tab-acts-natively t
486 org-src-preserve-indentation nil
487 org-edit-src-content-indentation 0)
488 #+end_src
489
490 *** [[https://magit.vc/][Magit]]
491
492 #+begin_quote
493 It's Magit! A Git porcelain inside Emacs.
494 #+end_quote
495
496 Not just how I do git, but /the/ way to do git.
497
498 #+begin_src emacs-lisp
499 (use-package magit
500 :defer t
501 :bind (("s-g" . magit-status)
502 ("C-x g" . magit-status)
503 ("C-x M-g" . magit-dispatch-popup))
504 :config
505 (magit-add-section-hook 'magit-status-sections-hook
506 'magit-insert-modules
507 'magit-insert-stashes
508 'append))
509 #+end_src
510
511 *** [[https://github.com/abo-abo/swiper][Ivy]] (and friends)
512
513 #+begin_quote
514 Ivy - a generic completion frontend for Emacs, Swiper - isearch with
515 an overview, and more. Oh, man!
516 #+end_quote
517
518 There's no way I could top that, so I won't attempt to.
519
520 **** Ivy
521
522 #+begin_src emacs-lisp
523 (use-package ivy
524 :bind
525 (:map ivy-minibuffer-map
526 ([escape] . keyboard-escape-quit)
527 ("C-j" . ivy-next-line)
528 ("C-k" . ivy-previous-line)
529 ([S-up] . ivy-previous-history-element)
530 ([S-down] . ivy-next-history-element)
531 ("DEL" . ivy-backward-delete-char))
532 :config
533 (ivy-mode 1))
534 #+end_src
535
536 **** Swiper
537
538 #+begin_src emacs-lisp
539 (use-package swiper
540 :bind (([remap isearch-forward] . swiper)
541 ([remap isearch-backward] . swiper)))
542 #+end_src
543
544 **** Counsel
545
546 #+begin_src emacs-lisp
547 (use-package counsel
548 :bind (([remap execute-extended-command] . counsel-M-x)
549 ([remap find-file] . counsel-find-file)
550 ("s-r" . counsel-recentf)
551 :map minibuffer-local-map
552 ("C-r" . counsel-minibuffer-history))
553 :config
554 (counsel-mode 1)
555 (defalias 'locate #'counsel-locate))
556 #+end_src
557
558 * Borg's =layer/essentials=
559
560 TODO: break this giant source block down into individual org sections.
561
562 #+begin_src emacs-lisp
563 (use-package dash
564 :config (dash-enable-font-lock))
565
566 (use-package diff-hl
567 :config
568 (setq diff-hl-draw-borders nil)
569 (global-diff-hl-mode)
570 (add-hook 'magit-post-refresh-hook 'diff-hl-magit-post-refresh t))
571
572 (use-package dired
573 :defer t
574 :config (setq dired-listing-switches "-alh"))
575
576 (use-package eldoc
577 :when (version< "25" emacs-version)
578 :config (global-eldoc-mode))
579
580 (use-package help
581 :defer t
582 :config (temp-buffer-resize-mode))
583
584 (progn ; `isearch'
585 (setq isearch-allow-scroll t))
586
587 (use-package lisp-mode
588 :config
589 (add-hook 'emacs-lisp-mode-hook 'outline-minor-mode)
590 (add-hook 'emacs-lisp-mode-hook 'reveal-mode)
591 (defun indent-spaces-mode ()
592 (setq indent-tabs-mode nil))
593 (add-hook 'lisp-interaction-mode-hook #'indent-spaces-mode))
594
595 (use-package man
596 :defer t
597 :config (setq Man-width 80))
598
599 (use-package paren
600 :config (show-paren-mode))
601
602 (use-package prog-mode
603 :config (global-prettify-symbols-mode)
604 (defun indicate-buffer-boundaries-left ()
605 (setq indicate-buffer-boundaries 'left))
606 (add-hook 'prog-mode-hook #'indicate-buffer-boundaries-left))
607
608 (use-package recentf
609 :demand t
610 :config (add-to-list 'recentf-exclude "^/\\(?:ssh\\|su\\|sudo\\)?:"))
611
612 (use-package savehist
613 :config (savehist-mode))
614
615 (use-package saveplace
616 :when (version< "25" emacs-version)
617 :config (save-place-mode))
618
619 (use-package simple
620 :config (column-number-mode))
621
622 (progn ; `text-mode'
623 (add-hook 'text-mode-hook #'indicate-buffer-boundaries-left))
624
625 (use-package tramp
626 :defer t
627 :config
628 (add-to-list 'tramp-default-proxies-alist '(nil "\\`root\\'" "/ssh:%h:"))
629 (add-to-list 'tramp-default-proxies-alist '("localhost" nil nil))
630 (add-to-list 'tramp-default-proxies-alist
631 (list (regexp-quote (system-name)) nil nil)))
632
633 (use-package undo-tree
634 :config
635 (global-undo-tree-mode)
636 (setq undo-tree-mode-lighter ""))
637 #+end_src
638
639 * Post initialization
640 :PROPERTIES:
641 :CUSTOM_ID: post-initialization
642 :END:
643
644 Display how long it took to load the init file.
645
646 #+begin_src emacs-lisp
647 (message "Loading %s...done (%.3fs)" user-init-file
648 (float-time (time-subtract (current-time)
649 ab--before-user-init-time)))
650 #+end_src
651
652 * Footer
653 :PROPERTIES:
654 :CUSTOM_ID: footer
655 :END:
656
657 #+begin_src emacs-lisp :comments none
658 ;;; init.el ends here
659 #+end_src