[rc] add rc.org for centralized literate configs
[~bandali/configs] / init.org
CommitLineData
180cab37
AB
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
25* Contents :toc_1:noexport:
26
27- [[#about][About]]
28- [[#header][Header]]
29- [[#initial-setup][Initial setup]]
30- [[#core][Core]]
967b0a82 31- [[#post-initialization][Post initialization]]
180cab37
AB
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
45Enable =view-mode=, which both makes the file read-only (as a reminder
46that =init.el= is an auto-generated file, not supposed to be edited),
47and provides some convenient key bindings for browsing through the
48file.
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
82The 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
109I'd like to do a couple of measurements of Emacs' startup time. First,
110let'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
121Also, temporarily increase ~gc-cons-threshhold~ and
122~gc-cons-percentage~ during startup to reduce garbage collection
123frequency. Clearing the ~file-name-handler-alist~ seems to help reduce
124startup 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
137Of course, we'd like to set them back to their defaults once we're
138done 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
153Increase the number of lines kept in message logs (the =*Messages*=
154buffer).
155
156#+begin_src emacs-lisp
157(setq message-log-max 20000)
158#+end_src
159
160Optionally, we could suppress some byte compiler warnings like below,
161but 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
173I can do all my package management things with Borg, and don't need
174Emacs' built-in =package.el=. Emacs 27 lets us disable =package.el= in
175the =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
181But since Emacs 27 isn't out yet (Emacs 26 is just around the corner
182right now), and even when released it'll be long before most distros
183ship in their repos, I'll still put the old workaround with the
184commented 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
194Assimilate 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
198short, it creates a git submodule in =lib/= for each package, which
199can 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
213A 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
217packages (in our case especially the latter) in a neatly organized way
218and 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
234Browse the Emacsmirror package database
235#+end_quote
236
237Epkg provides access to a local copy of the [[https://emacsmirror.net][Emacsmirror]] package
238database, 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
249Help keeping ~/.emacs.d clean
250#+end_quote
251
252By default, even for Emacs' built-in packages, the configuration files
253and persistent data are all over the place. Use =no-littering= to help
254contain 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
180cab37
AB
267** Custom file (=custom.el=)
268
269I'm not planning on using the custom file much, but even so, I
270definitely don't want it mixing with =init.el=. So, here; let's give
271it 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
285Let's use [[https://github.com/purcell/exec-path-from-shell][exec-path-from-shell]] to make Emacs use the =$PATH= as set up
286in my shell.
287
288#+begin_src emacs-lisp
7538956f
AB
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"))
180cab37
AB
298#+end_src
299
300** Server
301
302Start server if not already running. Alternatively, can be done by
303issuing =emacs --daemon= in the terminal, which can be automated with
304a systemd service or using =brew services start emacs= on macOS. I use
305Emacs as my window manager (via EXWM), so I always start Emacs on
306login; so starting the server from inside Emacs is good enough for me.
307
308See [[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
2f8102f0
AB
324Might want to set the fringe to a smaller value, especially if using
325EXWM. I'm fine with the default for now.
180cab37
AB
326
327#+begin_src emacs-lisp
2f8102f0 328;; (fringe-mode '(3 . 1))
180cab37
AB
329#+end_src
330
331*** Disable disabled commands
332
333Emacs disables some commands by default that could persumably be
334confusing 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
342Save what I copy into clipboard from other applications into Emacs'
343kill-ring, which would allow me to still be able to easily access it
344in case I kill (cut or copy) something else inside Emacs before
345yanking (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
360Lazy people would prefer to type fewer keystrokes, especially for yes
361or 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
369Firstly, let Emacs know that I'd like to have =*scratch*= as my
370startup buffer.
371
372#+begin_src emacs-lisp
373(setq initial-buffer-choice t)
374#+end_src
375
376Now let's customize the =*scratch*= buffer a bit. First off, I don't
377need the default hint.
378
379#+begin_src emacs-lisp
380(setq initial-scratch-message nil)
381#+end_src
382
383Also, let's use Text mode as the major mode, in case I want to
384customize it (=*scratch*='s default major mode, Fundamental mode,
385can't really be customized).
386
387#+begin_src emacs-lisp
388(setq initial-major-mode 'text-mode)
389#+end_src
390
391Inhibit 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
397I don't really need to see the startup screen or echo area message
398either.
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
408Show either the file name or the buffer name (in case the buffer isn't
409visiting 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
421Emacs' default backup settings aren't that great. Let's use more
422sensible options. See documentation for the ~make-backup-file~
423variable.
424
425#+begin_src emacs-lisp
426(setq backup-by-copying t
427 version-control t)
428#+end_src
429
430** Packages
431
432The packages in this section are absolutely essential to my everyday
433workflow, and they play key roles in how I do my computing. They
434immensely enhance the Emacs experience for me; both using Emacs, and
435customizing 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
457Roll your own modal mode
458#+end_quote
459
460*** [[https://github.com/ch11ng/exwm][EXWM]] (window manager)
461
462#+begin_src emacs-lisp
2f8102f0
AB
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))
180cab37
AB
472#+end_src
473
474*** [[https://orgmode.org/][Org mode]]
475
476#+begin_quote
477Org mode is for keeping notes, maintaining TODO lists, planning
478projects, and authoring documents with a fast and effective plain-text
479system.
480#+end_quote
481
482In 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
493It's Magit! A Git porcelain inside Emacs.
494#+end_quote
495
496Not 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
514Ivy - a generic completion frontend for Emacs, Swiper - isearch with
515an overview, and more. Oh, man!
516#+end_quote
517
518There's no way I could top that, so I won't attempt to.
519
520**** Ivy
521
522#+begin_src emacs-lisp
f7752223
AB
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))
180cab37
AB
534#+end_src
535
536**** Swiper
537
538#+begin_src emacs-lisp
f7752223
AB
539(use-package swiper
540 :bind (([remap isearch-forward] . swiper)
541 ([remap isearch-backward] . swiper)))
180cab37
AB
542#+end_src
543
544**** Counsel
545
546#+begin_src emacs-lisp
f7752223
AB
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))
180cab37
AB
556#+end_src
557
558* Borg's =layer/essentials=
559
560TODO: 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:
967b0a82 641:CUSTOM_ID: post-initialization
180cab37
AB
642:END:
643
644Display 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