[emacs] fix post initialization TOC link on GitHub
[~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
267
268** Custom file (=custom.el=)
269
270I'm not planning on using the custom file much, but even so, I
271definitely don't want it mixing with =init.el=. So, here; let's give
272it it's own file. While at it, treat themes as safe.
273
274#+begin_src emacs-lisp
275(use-package custom
276 :no-require t
277 :config
278 (setq custom-file (no-littering-expand-etc-file-name "custom.el"))
279 (when (file-exists-p custom-file)
280 (load custom-file))
281 (setf custom-safe-themes t))
282#+end_src
283
284** Better =$PATH= handling
285
286Let's use [[https://github.com/purcell/exec-path-from-shell][exec-path-from-shell]] to make Emacs use the =$PATH= as set up
287in my shell.
288
289#+begin_src emacs-lisp
290;; (use-package exec-path-from-shell
291;; :defer 1
292;; :init
293;; (setq exec-path-from-shell-check-startup-files nil)
294;; :config
295;; (exec-path-from-shell-initialize)
296;; ;; while we're at it, let's fix access to our running ssh-agent
297;; (exec-path-from-shell-copy-env "SSH_AGENT_PID")
298;; (exec-path-from-shell-copy-env "SSH_AUTH_SOCK"))
299#+end_src
300
301** Server
302
303Start server if not already running. Alternatively, can be done by
304issuing =emacs --daemon= in the terminal, which can be automated with
305a systemd service or using =brew services start emacs= on macOS. I use
306Emacs as my window manager (via EXWM), so I always start Emacs on
307login; so starting the server from inside Emacs is good enough for me.
308
309See [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html#Emacs-Server][Using Emacs as a Server]].
310
311#+begin_src emacs-lisp
312(use-package server
313 :config (or (server-running-p) (server-mode)))
314#+end_src
315
316* Core
317:PROPERTIES:
318:CUSTOM_ID: core
319:END:
320
321** Defaults
322
323*** Smaller fringe
324
325Set fringe to a small value so we don't have big borders in EXWM, but
326can still see the =diff-hl= colors in the fringe.
327
328#+begin_src emacs-lisp
329(fringe-mode '(3 . 1))
330#+end_src
331
332*** Disable disabled commands
333
334Emacs disables some commands by default that could persumably be
335confusing for novice users. Let's disable that.
336
337#+begin_src emacs-lisp
338(setq disabled-command-function nil)
339#+end_src
340
341*** Kill-ring
342
343Save what I copy into clipboard from other applications into Emacs'
344kill-ring, which would allow me to still be able to easily access it
345in case I kill (cut or copy) something else inside Emacs before
346yanking (pasting) what I'd originally intended to.
347
348#+begin_src emacs-lisp
349(setq save-interprogram-paste-before-kill t)
350#+end_src
351
352*** Minibuffer
353
354#+begin_src emacs-lisp
355(setq enable-recursive-minibuffers t
356 resize-mini-windows t)
357#+end_src
358
359*** Lazy-person-friendly yes/no prompts
360
361Lazy people would prefer to type fewer keystrokes, especially for yes
362or no questions. I'm lazy.
363
364#+begin_src emacs-lisp
365(defalias 'yes-or-no-p #'y-or-n-p)
366#+end_src
367
368*** Startup screen and =*scratch*=
369
370Firstly, let Emacs know that I'd like to have =*scratch*= as my
371startup buffer.
372
373#+begin_src emacs-lisp
374(setq initial-buffer-choice t)
375#+end_src
376
377Now let's customize the =*scratch*= buffer a bit. First off, I don't
378need the default hint.
379
380#+begin_src emacs-lisp
381(setq initial-scratch-message nil)
382#+end_src
383
384Also, let's use Text mode as the major mode, in case I want to
385customize it (=*scratch*='s default major mode, Fundamental mode,
386can't really be customized).
387
388#+begin_src emacs-lisp
389(setq initial-major-mode 'text-mode)
390#+end_src
391
392Inhibit the buffer list when more than 2 files are loaded.
393
394#+begin_src emacs-lisp
395(setq inhibit-startup-buffer-menu t)
396#+end_src
397
398I don't really need to see the startup screen or echo area message
399either.
400
401#+begin_src emacs-lisp
402(advice-add #'display-startup-echo-area-message :override #'ignore)
403(setq inhibit-startup-screen t
404 inhibit-startup-echo-area-message user-login-name)
405#+end_src
406
407*** More useful frame titles
408
409Show either the file name or the buffer name (in case the buffer isn't
410visiting a file). Borrowed from Emacs Prelude.
411
412#+begin_src emacs-lisp
413(setq frame-title-format
414 '("" invocation-name " - "
415 (:eval (if (buffer-file-name)
416 (abbreviate-file-name (buffer-file-name))
417 "%b"))))
418#+end_src
419
420*** Backups
421
422Emacs' default backup settings aren't that great. Let's use more
423sensible options. See documentation for the ~make-backup-file~
424variable.
425
426#+begin_src emacs-lisp
427(setq backup-by-copying t
428 version-control t)
429#+end_src
430
431** Packages
432
433The packages in this section are absolutely essential to my everyday
434workflow, and they play key roles in how I do my computing. They
435immensely enhance the Emacs experience for me; both using Emacs, and
436customizing it.
437
438*** [[https://github.com/emacscollective/auto-compile][auto-compile]]
439
440#+begin_src emacs-lisp
441(use-package auto-compile
442 :demand t
443 :config
444 (auto-compile-on-load-mode)
445 (auto-compile-on-save-mode)
446 (setq auto-compile-display-buffer nil
447 auto-compile-mode-line-counter t
448 auto-compile-source-recreate-deletes-dest t
449 auto-compile-toggle-deletes-nonlib-dest t
450 auto-compile-update-autoloads t)
451 (add-hook 'auto-compile-inhibit-compile-hook
452 'auto-compile-inhibit-compile-detached-git-head))
453#+end_src
454
455*** TODO [[https://github.com/Kungsgeten/ryo-modal][ryo-modal]]
456
457#+begin_quote
458Roll your own modal mode
459#+end_quote
460
461*** [[https://github.com/ch11ng/exwm][EXWM]] (window manager)
462
463#+begin_src emacs-lisp
464;; (use-package exwm
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
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
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
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