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