git.shemshak.org - ~bandali/configs/blob - 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-init][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
 268 ** Custom file (=custom.el=)
 269
 270 I'm not planning on using the custom file much, but even so, I
 271 definitely don't want it mixing with =init.el=. So, here; let's give
 272 it 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
 286 Let's use [[https://github.com/purcell/exec-path-from-shell][exec-path-from-shell]] to make Emacs use the =$PATH= as set up
 287 in 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
 303 Start server if not already running. Alternatively, can be done by
 304 issuing =emacs --daemon= in the terminal, which can be automated with
 305 a systemd service or using =brew services start emacs= on macOS. I use
 306 Emacs as my window manager (via EXWM), so I always start Emacs on
 307 login; so starting the server from inside Emacs is good enough for me.
 308
 309 See [[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
 325 Set fringe to a small value so we don't have big borders in EXWM, but
 326 can 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
 334 Emacs disables some commands by default that could persumably be
 335 confusing 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
 343 Save what I copy into clipboard from other applications into Emacs'
 344 kill-ring, which would allow me to still be able to easily access it
 345 in case I kill (cut or copy) something else inside Emacs before
 346 yanking (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
 361 Lazy people would prefer to type fewer keystrokes, especially for yes
 362 or 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
 370 Firstly, let Emacs know that I'd like to have =*scratch*= as my
 371 startup buffer.
 372
 373 #+begin_src emacs-lisp
 374 (setq initial-buffer-choice t)
 375 #+end_src
 376
 377 Now let's customize the =*scratch*= buffer a bit. First off, I don't
 378 need the default hint.
 379
 380 #+begin_src emacs-lisp
 381 (setq initial-scratch-message nil)
 382 #+end_src
 383
 384 Also, let's use Text mode as the major mode, in case I want to
 385 customize it (=*scratch*='s default major mode, Fundamental mode,
 386 can't really be customized).
 387
 388 #+begin_src emacs-lisp
 389 (setq initial-major-mode 'text-mode)
 390 #+end_src
 391
 392 Inhibit 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
 398 I don't really need to see the startup screen or echo area message
 399 either.
 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
 409 Show either the file name or the buffer name (in case the buffer isn't
 410 visiting 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
 422 Emacs' default backup settings aren't that great. Let's use more
 423 sensible options. See documentation for the ~make-backup-file~
 424 variable.
 425
 426 #+begin_src emacs-lisp
 427 (setq backup-by-copying t
 428       version-control t)
 429 #+end_src
 430
 431 ** Packages
 432
 433 The packages in this section are absolutely essential to my everyday
 434 workflow, and they play key roles in how I do my computing. They
 435 immensely enhance the Emacs experience for me; both using Emacs, and
 436 customizing 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
 458 Roll 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
 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-init
 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