More vc stuff, and this week's rabbit hole was git worktrees (Bozhidar Batsov's Working with Git Worktrees in Magit is what sent me down this particular rabbit hole!). It was an itch that manifested itself while reading this blog and mainly seeing that worktrees seemed to make a good deal of sense to me (especially as I am quite a subversion veteran). I have always felt uncomfortable with the default git in-situ branch switching and prefer to branch develop away from the mainline in a physical separate directory and this is just what worktrees facilitate. So how to do this with built-in vc-mode tools?, well as always this requires a little work and yes, I could use Magit, but I'm seeing how far I can push the built in vc.

The funny thing is that vc already understands worktrees perfectly well: a worktree is just a directory holding a .git pointer file instead of a .git folder, vc-git resolves that transparently, and diffs, commits and vc-dir all quietly do the right thing per worktree. What vc cannot do is actually seemingly manage them. There is no command to create one, switch between them, move one, list them, or throw one away, and the branch side is nearly as thin. Magit does all of this beautifully, of course - but I am stubborn about staying inside core Emacs where I can, so I spent an evening teaching vc-dir some new tricks. And yes, I do understand that vc in Emacs is in fact a generic abstraction and works well across all different types of version control, hence the reduction to a core subset of general source code commands, with a few extra added on of course for those obvious missing pieces, but I want to add the less obvious pieces, and certainly for git, worktrees is probably going to be one of them. Right lets get on with this and write some code!

Everything funnels through one small worker that shells out via vc-git-command and then drops you straight into vc-dir in the new tree:

Here is what I implemented:

;;
;; -> vc-git-worktree-core
;;
(defun my/vc-git-branches ()
  "Return a list of local branch names in the current git repository."
  (let ((root (vc-git-root default-directory)))
    (when root
      (with-temp-buffer
        (let ((default-directory root))
          (vc-git-command (current-buffer) 0 nil
                          "branch" "--format=%(refname:short)"))
        (split-string (buffer-string) "\n" t)))))

(defun my/vc-git--worktree-root ()
  "Return the git worktree root for `default-directory'.
Signal a `user-error' when not inside a Git repository."
  (or (vc-git-root default-directory)
      (user-error "Not in a Git repository")))

(defun my/vc-git-worktree-entries ()
  "Return the worktrees of the current repository as a list of plists.
Each plist has keys :path, :head, :branch, :detached, :bare,
:locked and :prunable, parsed from `git worktree list --porcelain'."
  (let ((root (my/vc-git--worktree-root))
        entries current)
    (with-temp-buffer
      (let ((default-directory root))
        (vc-git-command (current-buffer) 0 nil
                        "worktree" "list" "--porcelain"))
      (goto-char (point-min))
      (while (not (eobp))
        (let ((line (buffer-substring-no-properties
                     (line-beginning-position) (line-end-position))))
          (cond
           ((string-prefix-p "worktree " line)
            (when current (push current entries))
            (setq current (list :path (substring line 9))))
           ((string-prefix-p "HEAD " line)
            (setq current (plist-put current :head (substring line 5))))
           ((string-prefix-p "branch " line)
            (let ((ref (substring line 7)))
              (setq current
                    (plist-put current :branch
                               (if (string-prefix-p "refs/heads/" ref)
                                   (substring ref 11)
                                 ref)))))
           ((string= line "detached")
            (setq current (plist-put current :detached t)))
           ((string= line "bare")
            (setq current (plist-put current :bare t)))
           ((string-prefix-p "locked" line)
            (setq current
                  (plist-put current :locked
                               (if (> (length line) 6)
                                   (substring line 7)
                                 t))))
           ((string-prefix-p "prunable" line)
            (setq current
                  (plist-put current :prunable
                               (if (> (length line) 8)
                                   (substring line 9)
                                 t))))))
        (forward-line 1)))
    (when current (push current entries))
    (nreverse entries)))

(defun my/vc-git--default-worktree-path (root branch)
  "Return a default new-worktree path for BRANCH next to ROOT.
The default is a sibling directory of ROOT prefixed with the project
name, e.g. <parent>/myproj-feature for branch feature of myproj.
Slashes in BRANCH become dashes so hierarchical branches cannot
collide; an empty BRANCH falls back to <project>-worktree."
  (let ((project (file-name-nondirectory
                  (directory-file-name (expand-file-name root)))))
    (expand-file-name
     (concat project "-"
             (if (string-empty-p branch)
                 "worktree"
               (replace-regexp-in-string "/" "-" branch)))
     (file-name-directory (directory-file-name (expand-file-name root))))))

(defun my/vc-git-worktree-add (path branch &optional new-branch start-point)
  "Create a Git worktree at PATH checking out BRANCH, then open `vc-dir'.
An empty BRANCH checks out HEAD.  With prefix argument NEW-BRANCH,
create BRANCH as a new branch from START-POINT (defaulting to HEAD)
instead of checking out an existing branch or revision."
  (interactive
   (let* ((root (my/vc-git--worktree-root))
          (branches (or (my/vc-git-branches) '()))
          (make-new (if current-prefix-arg t nil))
          (branch (if make-new
                      (read-string "New branch name: ")
                    (completing-read "Checkout branch (empty = HEAD): "
                                     branches nil nil)))
          (default-path (my/vc-git--default-worktree-path root branch))
          (path (read-file-name "Worktree location: "
                                (file-name-directory default-path)
                                nil nil
                                (file-name-nondirectory default-path)))
          (start (and make-new
                      (completing-read "Start point: "
                                       (delete-dups
                                        (append (list "HEAD") branches
                                                (my/vc-git-tags)))
                                       nil nil nil nil "HEAD"))))
     (list (expand-file-name path) branch make-new start)))
  (my/vc-git-worktree--create path branch new-branch start-point))

(defun my/vc-git-worktree--create (path branch new-branch start-point)
  "Create a Git worktree at PATH and open `vc-dir' there.
BRANCH names an existing branch or revision, unless NEW-BRANCH is
non-nil, in which case BRANCH is created from START-POINT first."
  (let ((root (my/vc-git--worktree-root))
        (expanded (expand-file-name path)))
    (let ((default-directory root))
      (cond
       (new-branch
        (when (string-empty-p branch)
          (user-error "New branch name must not be empty"))
        (vc-git-command nil 0 nil "worktree" "add" "-b" branch expanded
                        (if (string-empty-p start-point) "HEAD" start-point)))
       ((string-empty-p branch)
        (vc-git-command nil 0 nil "worktree" "add" expanded))
       (t
        (vc-git-command nil 0 nil "worktree" "add" expanded branch))))
    (message "Created worktree %s" expanded)
    (vc-dir expanded)))

(defun my/vc-git-worktree-checkout (path branch)
  "Check out existing BRANCH in a new worktree at PATH, then open `vc-dir'.
The Magit-style `magit-worktree-checkout' first action: the location
defaults to a sibling directory named <project>-<branch>."
  (interactive
   (let* ((root (my/vc-git--worktree-root))
          (branches (or (my/vc-git-branches) '()))
          (branch (completing-read "Checkout branch in new worktree: "
                                   branches nil nil))
          (default-path (my/vc-git--default-worktree-path root branch))
          (path (read-file-name "Worktree location: "
                                (file-name-directory default-path)
                                nil nil
                                (file-name-nondirectory default-path))))
     (list (expand-file-name path) branch)))
  (when (string-empty-p branch)
    (user-error "Branch must not be empty"))
  (my/vc-git-worktree--create path branch nil nil))

(defun my/vc-git-worktree-branch (path branch start-point)
  "Create new BRANCH from START-POINT in a new worktree at PATH.
Then open `vc-dir'.  The Magit-style `magit-worktree-branch' first
action: the location defaults to a sibling directory named <project>-<branch>."
  (interactive
   (let* ((root (my/vc-git--worktree-root))
          (branches (or (my/vc-git-branches) '()))
          (branch (read-string "New branch name: "))
          (start (completing-read "Start point: "
                                  (delete-dups
                                   (append (list "HEAD") branches
                                           (my/vc-git-tags)))
                                  nil nil nil nil "HEAD"))
          (default-path (my/vc-git--default-worktree-path root branch))
          (path (read-file-name "Worktree location: "
                                (file-name-directory default-path)
                                nil nil
                                (file-name-nondirectory default-path))))
     (list (expand-file-name path) branch start)))
  (my/vc-git-worktree--create path branch t start-point))

(defun my/vc-git-worktree-move (path new-path)
  "Move the Git worktree at PATH to NEW-PATH (`git worktree move').
Interactively, prompt for a worktree, defaulting to the current one."
  (interactive
   (let* ((entries (my/vc-git-worktree-entries))
          (paths (mapcar (lambda (e) (plist-get e :path)) entries))
          (current (my/vc-git--worktree-root)))
     (unless paths (user-error "No Git worktrees found"))
     (let ((path (completing-read "Move worktree: " paths
                                  nil t nil nil current)))
       (list path (read-file-name
                   "Move to: "
                   (file-name-directory
                    (directory-file-name (expand-file-name path)))
                   nil nil)))))
  (let* ((root (my/vc-git--worktree-root))
         (expanded (expand-file-name path))
         (target (expand-file-name new-path)))
    (let ((default-directory root))
      (vc-git-command nil 0 nil "worktree" "move" expanded target))
    (message "Moved worktree %s to %s" expanded target)
    (when (derived-mode-p 'vc-dir-mode) (vc-dir-refresh))))

(defun my/vc-git-worktree-switch (path)
  "Interactively select an existing Git worktree and open `vc-dir' in it."
  (interactive
   (let* ((entries (my/vc-git-worktree-entries))
          (table (mapcar (lambda (e)
                           (cons (plist-get e :path) e))
                         entries))
          (current (my/vc-git--worktree-root)))
     (unless table (user-error "No Git worktrees found"))
     (let ((completion-extra-properties
            (list :annotation-function
                  (lambda (cand)
                    (let ((e (cdr (assoc cand table))))
                      (when e
                        (concat "  ["
                                (or (plist-get e :branch)
                                    (and (plist-get e :detached)
                                         "detached")
                                    "?")
                                (when (plist-get e :bare) ", bare")
                                "]")))))))
       (list (completing-read "Switch to worktree: " table
                              nil t nil nil current)))))
  (vc-dir path))

(defun my/vc-git-worktree-remove (path &optional force)
  "Remove the Git worktree at PATH, prompting first for confirmation.
With prefix argument FORCE, pass --force to git.
Interactively, prompt for a worktree, defaulting to the current one."
  (interactive
   (let* ((entries (my/vc-git-worktree-entries))
          (paths (mapcar (lambda (e) (plist-get e :path)) entries))
          (current (my/vc-git--worktree-root)))
     (unless paths (user-error "No Git worktrees found"))
     (list (completing-read "Remove worktree: " paths
                            nil t nil nil current)
           (if current-prefix-arg t nil))))
  (let* ((root (my/vc-git--worktree-root))
         (expanded (expand-file-name path))
         (main-root (plist-get (car (my/vc-git-worktree-entries)) :path))
         (here (file-truename default-directory))
         (gone (file-truename expanded)))
    (when (yes-or-no-p (format "Remove worktree %s%s? "
                               expanded (if force " (forced)" "")))
      (let ((default-directory root))
        (if force
            (vc-git-command nil 0 nil "worktree" "remove" "--force" expanded)
          (vc-git-command nil 0 nil "worktree" "remove" expanded)))
      (message "Removed worktree %s" expanded)
      (when (derived-mode-p 'vc-dir-mode)
        (if (string-prefix-p gone here)
            (vc-dir (or main-root root))
          (vc-dir-refresh))))))

(defun my/vc-git-worktree-prune ()
  "Prune stale Git worktree metadata (`git worktree prune')."
  (interactive)
  (let ((root (my/vc-git--worktree-root)))
    (let ((default-directory root))
      (vc-git-command nil 0 nil "worktree" "prune"))
    (message "Pruned worktrees in %s" root)
    (when (derived-mode-p 'vc-dir-mode) (vc-dir-refresh))))

(defvar-local my/vc-git-worktree-list--root nil
  "Repository root shown in the current worktree list buffer.")

(defvar my/vc-git-worktree-list-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map (kbd "RET") #'my/vc-git-worktree-list-visit)
    (define-key map (kbd "g") #'my/vc-git-worktree-list)
    (define-key map (kbd "q") #'quit-window)
    map)
  "Keymap for `my/vc-git-worktree-list-mode'.")

(define-derived-mode my/vc-git-worktree-list-mode special-mode "Worktrees"
  "Major mode for listing Git worktrees.
\\{my/vc-git-worktree-list-mode-map}")

(defun my/vc-git-worktree-list-visit ()
  "Open `vc-dir' for the worktree on the current line."
  (interactive)
  (let* ((here (line-number-at-pos))
         (btn (or (button-at (point))
                  (save-excursion
                    (beginning-of-line)
                    (next-button (point) t))))
         (ok (and btn (= here (line-number-at-pos (button-start btn))))))
    (if ok
        (vc-dir (button-label btn))
      (user-error "No worktree on this line"))))

(defun my/vc-git-worktree-list ()
  "List Git worktrees of the current repository in a dedicated buffer.
RET on a path opens `vc-dir' there; `g' refreshes the list, `q' quits."
  (interactive)
  (let* ((root (if (derived-mode-p 'my/vc-git-worktree-list-mode)
                   (or my/vc-git-worktree-list--root
                       (my/vc-git--worktree-root))
                 (my/vc-git--worktree-root)))
         (default-directory root)
         (entries (my/vc-git-worktree-entries)))
    (unless entries (user-error "No Git worktrees found"))
    (with-current-buffer (get-buffer-create "*vc-git worktrees*")
      (let ((inhibit-read-only t))
        (erase-buffer)
        (my/vc-git-worktree-list-mode)
        (setq my/vc-git-worktree-list--root root)
        (setq default-directory root)
        (insert (format "Worktrees for %s\n\n" root))
        (dolist (e entries)
          (let* ((path (plist-get e :path))
                 (head (or (plist-get e :head) ""))
                 (short (if (> (length head) 7) (substring head 0 7) head))
                 (flags (string-join
                         (delq nil
                               (list (when (plist-get e :bare) "bare")
                                     (when (plist-get e :detached) "detached")
                                     (when (plist-get e :locked) "locked")
                                     (when (plist-get e :prunable)
                                       "prunable")))
                         ",")))
            (insert-button path
                           'action (lambda (btn)
                                      (vc-dir (button-label btn)))
                           'follow-link t)
            (insert (format "  [%s] %s%s\n"
                            (or (plist-get e :branch) "HEAD")
                            short
                            (if (string-empty-p flags)
                                ""
                              (concat " (" flags ")")))))))
      (goto-char (point-min))
      (pop-to-buffer (current-buffer)))))

(with-eval-after-load 'vc-dir
  (define-key vc-dir-mode-map (kbd "Z a") #'my/vc-git-worktree-add)
  (define-key vc-dir-mode-map (kbd "Z b") #'my/vc-git-worktree-checkout)
  (define-key vc-dir-mode-map (kbd "Z c") #'my/vc-git-worktree-branch)
  (define-key vc-dir-mode-map (kbd "Z g") #'my/vc-git-worktree-switch)
  (define-key vc-dir-mode-map (kbd "Z k") #'my/vc-git-worktree-remove)
  (define-key vc-dir-mode-map (kbd "Z l") #'my/vc-git-worktree-list)
  (define-key vc-dir-mode-map (kbd "Z m") #'my/vc-git-worktree-move)
  (define-key vc-dir-mode-map (kbd "Z p") #'my/vc-git-worktree-prune))

Some interactive commands: Z a for the general case, Z b for checking out an existing branch, Z c for a new branch from a start point, plus Z m to move a tree, Z g to switch between them with branch annotations in the completion, Z k to remove one (prefix forces, and a vc-dir sitting inside the removed tree falls back to the main root rather than dying), Z p to prune stale metadata, and Z l for a listing buffer where RET jumps to vc-dir. The letters deliberately mirror Magit's own worktree map, so Z b, Z c, Z g, Z m and Z k all do what a Magit user's fingers expect; Z a, Z p and Z l are extras with no Magit equivalent. The same set hangs off C-x v z … globally.

So the whole loop, start to finish, never leaves vc: Z c to spin up the worktree, hack away, C-x v v to commit, Z g back to main, merge the branch, and Z k to remove the worktree.

If any of this sounds useful, the pattern to steal is a small one: vc-git-command with default-directory bound to the worktree root does almost all of the heavy lifting, and vc-dir on the resulting path gives you the status buffer for free. The rest is just prompts and keybindings.

The Emacs Carnival theme for September is "Games". Enjoy! Other really cool uses of graphics in Emacs: org-timegrid, poimap, canvas-minimap.

Also, public service announcement: doomemacs.com is not affiliated with doomemacs.org (see this Github discussion). Just in case someone reading this happens to be the person who made doomemacs.com, please consider setting up a redirect to doomemacs.org for more awesomeness and less confusion. Thank you!

And a reminder: EmacsConf - 2026 - Call for Participation target date for proposals Sept 18, conference is online Dec 12-13. Hope to see you there!

• Upcoming events (iCal file, Org):
  • London Emacs (in person): Emacs London meetup https://www.meetup.com/london-emacs-hacking/events/316294538/ Tue Sep 8 1800 Europe/London
  • Emacs Berlin: In-Person-Only Emacs-Berlin Stammtisch https://emacs-berlin.org/ Tue Sep 8 1900 Europe/Berlin
  • OrgMeetup (virtual) https://orgmode.org/worg/orgmeetup.html Wed Sep 9 0900 America/Vancouver - 1100 America/Chicago - 1200 America/Toronto - 1600 Etc/UTC - 1800 Europe/Berlin - 2130 Asia/Kolkata – Thu Sep 10 0000 Asia/Singapore
  • Atelier Emacs Montpellier (in person) https://lebib.org/date/atelier-emacs Fri Sep 11 1800 Europe/Paris
  • PDX Emacs (in person) https://pdx.social/@howard/117147689957341583 - Tue Sept 15 6:00 pm in Portland, OR
  • M-x Research: TBA https://m-x-research.github.io/ Wed Sep 16 0800 America/Vancouver - 1000 America/Chicago - 1100 America/Toronto - 1500 Etc/UTC - 1700 Europe/Berlin - 2030 Asia/Kolkata - 2300 Asia/Singapore
• Beginner:
  • What's in the Emacs newcomers-presets theme? (April 2026, Irreal)
• Emacs configuration:
  • Guide to Deferred Package Loading with use-package (Optimizing Emacs Startup) (Reddit, Irreal)
  • auto-side-windows now on MELPA (Reddit)
  • Emacs Meep-mode Model Editing (57:41) modal editing
  • Casual Suite 3.0 (@kickingvegas@sfba.social)
  • wakib-emacs: Emacs for the rest of us: v2 released! (Reddit)
  • Bedrock 2.0 released! (Reddit)
• Emacs Lisp:
  • Extending imenu for elisp (YouTube, Reddit, @benleis@mathstodon.xyz)
• Appearance:
  • Zoom in/out slider on the modeline (Reddit)
  • the emacs theme I use: N Λ N O Theme (06:24)
  • [Theme] Vulkanite: 26 atmospheric dark theme variants for Emacs with Kanagawa-inspired balance (Reddit)
  • Protesilaos: Emacs: doric-themes version 1.3.0 (Irreal)
• Navigation:
  • windmove tinkering (@ljwrites@writeout.ink)
  • auto-tab-groups: tab groups that open and close with your commands (now on MELPA) (Reddit)
  • poimap.el - Visual buffer map with points of interest (Reddit)
  • canvas-minimap: a pixel-based minimap using Emacs 32's canvas image type (Reddit)
• Writing:
  • Lars Ingebrigtsen: Emacs Canz Spell Goodly Know
  • Thysrael/markdown-ts-appear: Reveal Markdown source at point and preview math in Emacs markdown-ts-mode · GitHub (@thysrael)
• Org Mode:
  • My Note Taking Setup With Emacs Org-Mode (33:26)
  • Writing year in review: My 2022 writing habit on Emacs | Semi-author-ized writer (@ljwrites@writeout.ink)
  • A beautiful SVG weekly calendar for Emacs, backed by Org files, with full mouse and keyboard support and an optional day strip for Org Agenda (Reddit)
  • Emacs Org-Mode PDF Quicksheet now available in PEL (Reddit)
  • org-draw is now available on MELPA! (YouTube, Reddit)
  • Improving the styling of emacs tables with tabularray (programming.dev)
  • org-table-widget: I finally found a way to make Org tables easier to read without changing how I edit them (Reddit)
  • Org development:
    • Factor out export-and-show in ox-latex.el and ox-beamer.el
• Coding:
  • James Dyer: Git Worktrees Without Leaving Built-in VC
  • Emacs Redux: Working with Git Worktrees in Magit
  • Dave Pearson: next-gh-pr.el v1.1.0
  • Joar von Arndt: Emacs does not need LSP
  • Magnus: Emacs salmagundi, 2026-09-06 emacs-multi-compile, consult-kith for jumping to tests/etc.
  • Xdebug for PHP on Emacs with Dape | Artful Robot (@artfulrobot@floss.social)
  • gaudy-cl: Colorful semantic font-locking for Common Lisp (Reddit)
• Shells:
  • cooked - a comint based terminal emulator (Reddit)
• Evil mode:
  • evil-twin: key-chords that actually behave under evil-mode (Reddit)
• Multimedia:
  • New package: supersonic.el (Music player for subsonic-compatible servers) (Reddit)
  • Integrating Emacs with Music Player (01:32:18)
  • Bioscoop demo: split screen to visualize color grading - YouTube (@danielsz.bsky.social)
• Fun:
  • andros/nonogram.el: Play nonogram puzzles (also known as picross, griddlers or hanjie) in Emacs (@andros@activity.andros.dev)
  • Raymond Zeitler: Games: The Emacs Carnival Post For September 2026
    • Sacha Chua: Emacs Carnival September 2026: Games
    • Playing with Emacs | Dilip's Log
  • Process Footage: Randomized Greeting from Dipskits Greets Me at My Terminal (05:23)
• LLMs:
  • Pimacs - An Emacs UI for Pi · Anantha Kumaran
  • El Yayster — a resident LLM that inhabits Emacs (HN)
• Community:
  • BEWARE: doomemacs.com is not associated with doomemacs (Reddit)
  • Question about things that surprised you about Emacs.
  • Emacs in fifty keystrokes five years later (2026 edition featuring meow and agent-shell)
  • Sacha Chua: Emacs Chat 30: Fabrice Niessen (en français, partie 2) (YouTube, 01:05:56)
  • Talking About Stuff I Use on Linux (not a dev, just a human perspective) (01:00:02) Doom Emacs at 15:24
• Other:
  • Jeremy Friesen: How I’m Feeling Emacs Command
  • The Emacs Security Settings that might Silently Compromise your System (Reddit)
  • I finally got Emacs to render Markdown tables properly (md-mode 0.4.1) — and I think the same trick can work for Org tables (Reddit)
  • epub-reader: an EPUB reader for Emacs that reflows, breaks CJK lines properly, and keeps highlights across re-layout (Reddit)
  • Marcin Borkowski: Pasting primary selection from keyboard
  • thkoch2001/rau: Emacs/Wayland based Window Manager in pure elisp with the help of River (HN)
  • Building Emacs into a systemd-sysext — Alex Carney (@alcarney@mastodon.social)
• Emacs development:
  • emacs-devel:
    • Re: master e630bc4fd72: ; Fix some recently added docs. - Dmitry Gutov - xref docs?
  • Improve presentation of query-replace-show-preview
  • Let 'query-replace-show-preview' be a function (bug#81583)
  • Make log-edit-headers-separator inherit from separator-line
  • Merge branch 'xref-find-by-kind'
• New packages:
  • agent-shell-math-renderer: Display-math rendering for agent-shell (MELPA)
  • api-credit: AI API balance in the modeline (MELPA)
  • auto-tab-groups: Simple auto tab group creator for specified commands (MELPA)
  • cursorfree: Complex editing through voice (MELPA)
  • material-icons: Material Icon Theme integration (MELPA)
  • metropolis-light-theme: Light theme based on the Metropolis Beamer palette (MELPA)
  • mode-line-path: Abbreviate file paths in the mode line (MELPA)
  • nix3: Frontend to experimental commands of Nix (MELPA)
  • org-roam-gt: Improvements for org-roam (MELPA)
  • pilish: Emacs frontend for pi coding agent (MELPA)
  • surveyor: Survey your code with LLM-generated diagrams (MELPA)

Links from reddit.com/r/emacs, r/orgmode, r/spacemacs, Mastodon #emacs, Bluesky #emacs, Hacker News, lobste.rs, programming.dev, lemmy.world, lemmy.ml, planet.emacslife.com, YouTube, the Emacs NEWS file, Emacs Calendar, and emacs-devel. Thanks to Andrés Ramírez for emacs-devel links. Do you have an Emacs-related link or announcement? Please e-mail me at sacha@sachachua.com. Thank you!

You can e-mail me at sacha@sachachua.com.

Like many nerds, I feel so embarrassed whenever I see that I’ve misspelled something. But some years back when I started producing text in huge amounts for things like the Eclipse Comics read-through I realised that my options were: 1) Remain neurotic about this stuff and produce one blog post per week, or 2) Start caring less and produce a lot of blog posts.

I think I made the correct decision — I just don’t have time to proff-read all this stuff, so typos will abound. It’s just not feasible to put as much work into that stuff as you’d do for a properly published article. The reader gets what they pay for.

But now there’s a way to have your delicious cake and eat it too — just ask an LLM for help.

NOOOO! *audience runs in slow motion towards camera*

I know, I know. Whenever I read somebody in deep AI psychosis who thinks they’re being AI sceptical saying “well, of course you shouldn’t let the LLM write your articles. Instead I let it do the research, and then I make it provide an outline, and then I write some text based on that, and then it does formats and restates what I wrote. IT”S A WHOLE DIFFERENT THING! I WROTE IT!!!!”

No. You should never let an LLM do those things: Not the research, not the outline, not the formatting, not anything. Reading the output of LLMs is abhorrent to people. You should never subject anybody to an LLM generated text, even if you’ve done “quality control”.

LLM-generated text gives people the ick. It’s better to have an awkwardly phrased article you’ve written yourself than subjecting somebody to a Claude text. It’s not just the ick — it’s the horror.

However, you can use LLMs for spell- and grammer check:

I’ve whipped up a li’l minor mode for Emacs (and put it on Microsoft Github). The default prompt is very clear that I want the LLM to do nothing but copy edits — no structural changes, and no other helpful suggestions. Just fix grammer and tippos.

And then you can interactively go through the fixes and toggle back to the original ones if you disagree.

Yes, yes, sure — Grammarly, etc — stuff like this already exists. But I just don’t like using them. I use the built-in Emacs spellcheck, but it doesn’t catch everything. Having an LLM give the text a quick once-over for obvious mistakes seems nice.

While testing this minor mode now, I see that LLMs haven’t changed as much as I thought — they’ve gotten so much better on programming the last half year, it’s incredible. For stuff like this, though, it’s still pretty unreliable. Any two runs won’t necessarily fix up the same thing, or the same thing the same way. And getting it (I’m using Claude Sonnet 5) to output it in the requested form is not reliable at all — I’ve been reformulating the prompt, trying to get it to output it in the format I the mode needs, and… I think I’m at 95% now?

So, like all with all non-programming tasks, LLMs are still pretty much toys. But useful ones! For instance, this blog post is totally free of errors.

As many of you know, my idea of a theme is to set the background to “oldlace” and the cursor to red. For the rest of it, I just take what Emacs gives me. That sounds pretty haphazard but it works out pretty well. It has enough contrast to be easy to read without searing my eyeballs and has enough syntax highlighting to be useful without being overpowering.

Prot (Protesilaos Stavrou) has a much more refined sense for these things. He considers what colors go well to together and things like contrast levels. Just the oposite of my “do with me what you will” approach. Nevertheless, I mostly don’t bother much with formally defined themes although I do occasionally like to take a look at them.

The reason for this post is Prot’s latest release of his Doric Themes. They’re sort of minimalist, like my non-theme theme but still very nice looking if you don’t want your Emacs screen to look like an arcade. The doric-almond variation is, in particular, very similar to my color scheme. Mine has a little more contrast: the foreground text is a bit darker and the keywords in my code buffers are a blue that’s slightly brighter than doric-almond’s light green. Still, it’s a theme that I’d be comfortable with if I hadn’t taken the easy way.

Some people have multiple themes and change them according to the time of day, their mood, the phase of the moon, or whatever. I’d hate that probably for the same reason that I don’t do well with trying to use different editors: I’d always be confused as to what’s what.

If you’re looking for a minimalist theme and my method seems too minimal, take a look at Prot’s Doric Themes. There are several variations in both light and dark mode.

Language-server-protocol (lsp) is standard to communicate information about a current programming project to an editor integration, powered by a “language server” for the specific programming language. Emacs has two major implementations of this editor functionality: eglot (built-in) and lsp-mode. Getting this set up is usually one of the first things that new users will want to do, but in my experience one can get by for a surprisingly long time using Emacs without needing to reach for eglot or lsp-mode. That is because many of the functions that lsp-servers provide can be provided by Emacs through other means.

As someone who quite often moves between different programming languages, I find the need to set up each lsp-server to a bit clunky. Despite being presented as a simple one-stop solution, you often need to research exactly what server to use, how to set it up, and to tailor it to your machine in some ways. For me, this only makes sense in a few languages that I use often, and even then it might not be the first thing I take care of.

(defun cape-language (&optional interactive)
    (interactive (list t))
    (if interactive
        (cape-interactive #'cape-language)
      (cape-wrap-super #'cape-dabbrev #'cape-dict)))

(add-hook 'completion-at-point-functions #'cape-history)
(add-hook 'completion-at-point-functions #'cape-keyword)
(add-hook 'completion-at-point-functions #'cape-file)
(add-hook 'completion-at-point-functions #'cape-language)
(add-hook 'completion-at-point-functions #'cape-abbrev)

(use-package etags-regen
  :config
  (setq etags-regen-ignores
        '("*.pyc" ".git" ".venv" "venv" "node_modules"))
  (etags-regen-mode 1))

(setq xref-show-xrefs-function #'consult-xref
      xref-show-definitions-function #'consult-xref)

James Cherti has another excellent post, this time on optimizing Emacs startup with use-package. The idea is that many configurations load a substantial number of packages and that this can cause a significant increase in startup time.

Most of you know by now that we here at the Irreal bunker refuse to worry about that because, after all, we hardly ever restart Emacs. Still, plenty of people do worry about it and there’s nothing wrong with learning a few easy to implement principles that will speedup Emacs startup without having to obsess about tiny details.

The TL;DR is to get use-package to defer loading of packages until they are actually needed. Most Emacers who aren’t complete n00bs already know this. The question is, how exactly, to specify the use-package commands to achieve that.

The obvious answers aren’t the right ones. For example, the :defer keyword seems like the natural answer but Cherti explains why this isn’t usually necessary and that it doesn’t do what you probably think it does. It’s much better to use one of the commands that implicitly defer loading but also arrange for autoloading the required functions when they’re needed.

Cherti also explains how to get use-package to add logging information to the *Messages* buffer to help with understanding the load process. There’s a lot of information in Cherti’s post and it serves as a handy reference for how to use use-package to control the loading of packages at startup time. If you’re at all worried about startup time or just want to understand how to use use-package to control package loading, take a look at his post.

One of the things I love about the Emacs community is people's sense of humour and whimsy. There's a grand tradition of people hiding Easter eggs in software, a bit of hidden fun that might make someone smile. But isn't this just bloat and frivolity? One might argue that the code that lets us play M-x tetris, dunnet, or doctor in Emacs is a waste of time and space compared to More Serious Things, but on the other hand, the Tetris source code could be a good jumping-off point if you find yourself wanting to make an interactive real-time simulation that displays graphical results. Want something more modern? Maybe DOOM on Emacs! Besides, the code for games isn't actually loaded until you choose to play it. It's okay for something to be fun by itself instead of needing to be productive. There's something wonderful about a tool that people choose not just for work but also for enjoyment.

Our adventure can start with Fun and Games in Emacs - Mastering Emacs or Emacs Is A Gaming Platform for Windows, Mac and Linux - YouTube, which cover a lot of classic built-ins. Here's a barrage of ideas; skip or explore anything you want: Pretend you're on a typewriter or turn on power mode or make c-c-combos. Go on to draw some ASCII art with artist-mode or with Emacs Lisp, and add some box shadows because why not. Maybe even use it to tell the time. Turn ASCII art into PNGs. Have fun with obscure calendars. Use kaomojis or write weird text. Explore the screensavers in zone and let them sprinkle characters through your buffer, take over your other frames, or teach you something new. Watch snow or a fireplace. Rotate cubes in ASCII or with hardware-accelerated graphics. Why limit yourself to cubes? Still, if you do want to stick to cubes, you can solve them. Go ahead, animate something. Play roleplaying games (also check out Howard Abrams's 2023 talk), rogue-likes, multi-user dungeons, classics, chess, trading, Klondike and lots of other card games, a racing game, Minesweeper, 2048, Boomshine, a Gameboy emulator (this other one handles NES). Simulate cities or physics or pets (here's another one) or life. Have fun with so many cats: timers, scrollcats, screensavers. Not a cat person? There's a parrot version and a fish version. Read comics or make memes. Guess words or find them. Learn other alphabets. Make art. You can even turn your Emacs into a Geiger counter for garbage collection.

Then take a step back and marvel at this community of people who try things out, tinker, follow that crazy idea that won't let go of them, and share what they came up with. If you write Emacs Lisp (or want to learn), rummage around in the source code for ideas on how to do things. See if you have any ideas that tickle your fancy. You might be able to get Emacs to do things text editors don't usually do! =)

You can e-mail me at sacha@sachachua.com.

These are my minimalist themes. They use few colours and will appear mostly monochromatic in many contexts. Styles involve the careful use of typography, such as italics and bold italics.

If you want maximalist themes in terms of colour, check my ef-themes package. For something in-between, which I would consider the best “default theme” for a text editor, opt for my modus-themes.

• Package name (GNU ELPA): doric-themes
• Sample pictures: https://protesilaos.com/emacs/doric-themes-pictures
• Git repository: https://github.com/protesilaos/doric-themes
• Backronym: Doric Only Really Intensifies Conservatively … themes.

Below are the release notes.

Version 1.3.0 on 2026-09-04

New theme screenshots

All sample images are updated to the current version and cover all the Doric themes: https://protesilaos.com/emacs/doric-themes-pictures.

New doric-lilac and doric-borage themes

I drew inspiration for both themes from plants that exist around my house. They both use the same colours in different shades and sequence. doric-lilac has a light background while doric-borage has a dark background.

More commands to load a theme

The commands doric-themes-rotate-light and doric-themes-rotate-dark are convenience wrappers of doric-themes-rotate. As their name suggests, they are restricted to one kind of theme in the collection.

Similarly, doric-themes-load-random-light and doric-themes-load-random-dark are variants of doric-themes-load-random.

Thanks to Lucas Jiménez for making this suggestion in issue 28: https://github.com/protesilaos/doric-themes/issues/28.

Broader face coverage

The following packages have some new faces or I tweaked them to look better with the rest of the theme.

• completion-preview
• elfeed
• erc
• flymake
• gnus
• mu4e
• query-replace

Minor refinements to palette values

I made several small tweaks to several themes. The changes are probably too fine to notice or they should now look correct enough to be unnoticeable.

As an Emacs user, your configuration can easily grow from a few lightweight adjustments to a massive, hundred-package IDE. Without careful management, Emacs startup time can degrade from sub-second execution to several seconds, or minutes, in the worst cases. Eager package loading is one common source of startup overhead. This guide explains how Emacs loads libraries, how use-package configures package loading, and how deferred loading can reduce startup time.

Before we dive in, please consider sharing this article on your website, blog, Mastodon, Reddit, X, Linkedin, or other social media platforms.

Why does Emacs startup get slow?

A naive package declaration looks like this:

;; The kirigami Emacs package provides a unified method to fold and unfold
;; text in Emacs across a diverse set of Emacs modes.
(use-package kirigami)

By default, this causes use-package to load the package during initialization, unless the declaration contains a deferring keyword or another option that changes the loading behavior.

Conceptually, the eager loading is equivalent to:

(require 'kirigami)

The require function ensures that a feature is loaded.

When many packages are loaded this way, the time spent loading and evaluating their code contributes to increasing startup time.

What is Autoloading?

Autoloading registers a function without immediately loading the library that defines it. The library is loaded only when the function is called. For example:

;; Simplified representation of an autoload registration
(autoload 'kirigami-global-mode "kirigami" "Global mode for Kirigami." t)

If M-x kirigami-global-mode invokes the autoload, Emacs loads the kirigami.el library ("kirigami", the second argument), and then calls the actual kirigami-global-mode function. This allows the library's startup cost to be deferred until the function is actually needed.

Explicit vs. implicit deferral in use-package

The use-package macro makes package configuration and loading declarative. By default, a declaration is eager, meaning the package is loaded immediately while Emacs processes the configuration during startup, rather than waiting until the package is needed. A deferring keyword or another loading mechanism can postpone loading until later.

The explicit :defer keyword

Deferral using :defer t (Not necessary)

Note: Explicitly using :defer t is often unnecessary. Keywords such as :commands, :bind, :hook, :commands, and :mode establish loading triggers automatically. These keywords are discussed below.

If a package does not have another loading trigger, :defer t prevents use-package from loading it immediately:

(use-package kirigami
  :defer t)

This prevents the package from being required during startup. Without an autoload or another loading trigger, the package will remain unloaded until something else loads it.

Idle deferral: Numeric argument (Not ideal)

A numeric value to :defer schedules the package to be loaded after Emacs has been idle for the specified number of seconds:

;; Load kirigami after Emacs has been idle for 20 seconds
(use-package kirigami
  :defer 20)

Note: This is not ideal because loading a heavy package after a few seconds will block the event loop and can cause a freeze in the user interface. If multiple packages are deferred via idle timers, they can trigger sequentially during a single idle period, increasing the delay. To prevent unprompted blocking operations, it is best practice to configure explicit autoloads, such as :hook, :bind, :commands, or :mode. (These keywords are discussed below.)

Implicit deferral: Autoload triggers (Recommended solution)

Instead of manually adding :defer t to every use-package declaration, you can use trigger keywords to configure deferred loading automatically. These keywords generate autoloads, ensuring the package evaluates only when you interact with its components:

• :commands: Generates autoloads for specific interactive commands. Emacs loads the package when you execute the command (for example, via M-x).
• :bind: Maps keys to commands and automatically creates autoloads for them.
• :hook: Adds a package function to a hook and arranges for deferred loading.
• :mode: Adds a file-pattern entry to auto-mode-alist and defers loading until the mode is needed.

Example: Autoloading on major mode file extensions

Instead of loading Markdown mode immediately, use :mode to defer it until you open a .md file:

(use-package markdown-mode
  :mode ("\\.md\\'" . markdown-mode))

Note: Specifying :defer t is unnecessary here, as :mode automatically defers package loading.

Example: Autoloading on keybindings

The :bind keyword maps keys to commands and automatically creates autoloads for them. The package remains deferred until you press one of the defined key combinations:

(use-package embark
  :bind
  (("C-." . embark-act)       
   ("C-;" . embark-dwim)       
   ("C-h B" . embark-bindings)))

Example: Autoloading specific commands

If you do not want to define global keybindings but still need to defer loading until a command is called interactively (for example, via M-x), use the :commands keyword. This generates the necessary autoloads:

(use-package embark
  :commands (embark-act
             embark-dwim
             embark-bindings))

Example: Autoloading on hook execution

Instead of eagerly loading outline-indent-minor-mode (indentation-based code folding) at startup, you can configure Emacs to load and activate it on demand. This ensures the package evaluates only when a python-mode, python-ts-mode, or yaml-ts-mode buffer is opened:

;; The outline-indent Emacs package provides a minor mode for
;; indentation-based code folding.
(use-package outline-indent
  :commands (outline-indent-minor-mode
             outline-indent-backward-same-level
             outline-indent-forward-same-level)
  :hook ((python-mode . outline-indent-minor-mode)
         (python-ts-mode . outline-indent-minor-mode)
         (yaml-ts-mode . outline-indent-minor-mode))
  :custom
  (outline-indent-ellipsis " ▼"))

This also loads outline-indent when you invoke the command manually via M-x outline-indent-minor-mode, outline-indent-backward-same-level, or outline-indent-forward-same-level.

Note: There is no need to specify :defer t separately. The :hook keyword adds outline-indent-minor-mode to python-mode-hook, python-ts-mode-hook, and yaml-ts-mode-hook.

The unconditional use-package :init block

Code inside the use-package :init section is evaluated before the package is loaded. An autoloaded function called from :init can itself cause the package to load immediately, defeating the intended deferral. Therefore, :init is generally appropriate for settings that must be established before the package loads, while package-dependent function calls belong in :config or another deferred trigger (e.g., with-eval-after-load).

(Similarly, code inside the :preface block evaluates before package loading, but it also executes during byte-compilation. This distinction makes :preface the correct location for code required to satisfy the byte-compiler, such as defvar statements, helper macro definitions, or declare-function calls that prevent compiler warnings for deferred libraries.)

Forcing immediate load with :demand

With global deferral enabled, you will occasionally encounter packages that must be loaded immediately (e.g., themes, keybinding managers, or daemon-side servers). You can override global deferral on an individual basis using :demand t:

(use-package tomorrow-night-deepblue-theme
  :demand t ; Force immediate loading
  :config
  ;; Load the tomorrow-night-deepblue theme
  (load-theme 'tomorrow-night-deepblue t))

Note: If a declaration specifies both :demand t and :defer t (or triggers), :demand t takes precedence and forces eager loading.

The use-package :after keyword

The use-package :after keyword allows you to defer the initialization of a package until one or more specified target packages have been fully loaded. This is practical for:

• Add-on packages that extend a base minor mode.
• Integration packages that bridge two distinct tools together.

Consider embark-consult, a package that integrates embark with consult. You only need the embark-consult package after embark and consult are loaded:

(use-package embark-consult
  :after (embark consult))

In this scenario, embark-consult remains entirely inactive during startup. Emacs won't evaluate the embark-consult configuration until it has successfully loaded both embark and consult.

Forcing immediate loading

Consider this configuration:

(use-package kirigami
  :defer t
  :custom
  (kirigami-show-menu-bar t)
  (kirigami-show-context-menu t)
  :init
  (kirigami-global-mode 1)) ; This forces immediate loading

Although :defer t is present, evaluating (kirigami-global-mode 1) during :init triggers the autoload for kirigami-global-mode. The package is therefore loaded during initialization, defeating the intended deferral.

Loading after the Emacs init phase

If you prefer to load a package after the init phase, use the :hook keyword:

(use-package kirigami
  :custom
  (kirigami-show-menu-bar t)
  (kirigami-show-context-menu t)
  :hook (after-init . kirigami-global-mode)) ; Activate after init

Using :hook (after-init . kirigami-global-mode) adds the mode to after-init-hook. This ensures the package remains deferred while Emacs evaluates the rest of your init file, guaranteeing the mode is active before the editor is ready for user interaction.

Global laziness: use-package-always-defer (Not recommended)

You can configure use-package to automatically assume :defer t for declarations that do not otherwise establish eager loading:

(setq use-package-always-defer t) ; NOT RECOMMENDED

This changes the default behavior so that use-package declarations are deferred unless a declaration explicitly requires immediate loading or establishes another loading mechanism.

Note: Global deferral breaks packages that rely on background execution, global hooks, or immediate side effects to function correctly. You will find yourself tracking down silent failures and adding :demand t throughout your initialization file to force eager loading for things like themes, modeline managers, and daemon servers. Instead of relying on a blanket setting that obscures the loading state, setting use-package-always-defer to nil and explicitly deferring packages where appropriate results in a more deterministic setup.

Diagnostics and verification

To check whether a package feature has been provided in the current Emacs session, use the featurep function. For example, for the kirigami package:

(featurep 'kirigami)

• Evaluates to nil when the feature has not been provided.
• Evaluates to t when the feature has been provided.

Debugging and macro expansion optimization

If you need to diagnose loading order or macro expansion issues, use-package provides built-in settings to help debugging and performance.

Setting use-package-expand-minimally to t causes the use-package macro to generate less boilerplate code. If you byte-compile your initialization file, this reduces the size of the compiled file and can yield slight performance improvements:

(setq use-package-expand-minimally t)

Setting use-package-verbose to t forces use-package to log package loading events to the *Messages* buffer. This is useful for verifying whether deferred packages are loading when expected:

(setq use-package-verbose t)

Setting use-package-enable-imenu-support to t causes imenu to see use-package declarations. This allows you to quickly jump to specific use-package blocks using M-x imenu:

(setq use-package-enable-imenu-support t)

By default, the :hook keyword automatically appends -hook if you omit it. Setting use-package-hook-name-suffix to nil disables this behavior. Disabling this forces you to write fully qualified hook names (e.g., (python-mode-hook . outline-indent-minor-mode)):

(setq use-package-hook-name-suffix nil) ; NOT RECOMMENDED

Note: It is not recommended to set use-package-hook-name-suffix to nil if you maintain a pre-existing configuration that relies on the default implicit behavior. Modifying this variable globally instantly breaks every existing :hook (mode . function) declaration that omits the -hook suffix. Unless you are building a configuration from scratch or can rewrite and validate every hook assignment in a single pass, leaving the default behavior intact is the most practical decision.

Startup profiling: measuring the impact

To benchmark startup optimizations, measure startup at a point later than the end of init-file processing.

Benchmarking startup

For an accurate startup-time measurement, read:
Measuring Emacs startup time more accurately than the built-in emacs-init-time

Profiling individual packages

use-package can collect loading statistics. Enable statistics gathering after use-package has been loaded but before the use-package declarations are evaluated:

(setq use-package-compute-statistics t)

After restarting Emacs, execute: M-x use-package-report

This displays a tabulated buffer with timing information for the use-package phases.

Advanced profiling with benchmark-init

While use-package-report offers insights into declarative package loading, the third-party package benchmark-init (available on MELPA) provides a more granular view of the entire Emacs startup process. It tracks the time spent loading individual files and executing functions across the whole initialization sequence, allowing you to see exactly where you can influence startup time.

Related links

• The use-package documentation
• Emacs startup - Why setq beats setopt, customize-set-variable, and use-package :custom?

Evan Hahn has an amusing post about the Vim UserGettingBored autocmd. Autocmds in Vim are essentially like hook functions in Emacs. They get fired when certain events happen in the editor.

Way back before Vim 6.0, Bram Moolenaar added the UserGettingBored autocmd to the Vim documentation. It was a joke and the command didn’t actually do anything—or rather, it was never invoked and didn’t really exist. It was like an Emacs hook that was documented but didn’t actually occur. The documentation said “When the user hits CTRL-C. Just Kidding.” In 2013 the documentation changed to “When the user presses the same key 42 times. Just kidding! :-)” and, there were various other tweaks along the way. Finally, in 2022 an unofficial plugin was created by Mike Smith that actually implemented the autocmd and did something. You can read what it was in Hahn’s post.

None of this matters at all, of course, except to provide evidence that Vim users can be as whimsical as us Emacs users. You probably won’t see anything like this in VSCode. It wouldn’t be “professional”.

A quick little update to next-gh-pr.el. Since writing the first version I've found it to be really useful, but I've also bumped into one small issue. Sometimes I'll create a draft PR before I remember to start the changelog entry, and so then I want to insert the current PR link rather than the next one.

Now, sure, I can just go and copy the URL and create the link in the changelog, but where's the fun in that when I can solve the problem in Emacs Lisp? So, with this in mind, I've just updated the package so that, with a prefix argument to the command, it will include a link for the latest PR rather than for the next one.

This does, of course, make the name a little less correct, but I'm not going to rename the package or the command for this one minor difference in intent.

I wanted to write a short update to my Emacs pinky / RSI situation.

I am still using my Kinesis Freestyle Edge keyboard. I think I’ve decided on the Glove80 as a replacement, but the price and the inability to easily return it are giving me second thoughts. Its style is very different, and I know I will have a hard time adjusting. Still as someone pointed out to me it’s not like I’m forced to throw away my current keyboard, which is true. I see myself using my Kinesis for work on the Mac while trying the new Glove80 on Linux for blog posts and more leisure-time typing.

I’ve made a few adjustments, however:

First, the spread between the two halves is much wider. This is something I was considering when I first got this keyboard, but I didn’t follow through with it. I got used to the wider split within a couple of days. It does make my shoulders feel better and more natural, especially when I’m standing at my desk. With that, I also started using the keyboard’s full tenting capability at all times: I used to have the keyboard flatter when sitting down.

The mouse is in the middle, and since I use it for quick bursts between otherwise typing sessions, it’s fine. When I game, I move it back to the right. I can basically ignore the entire right half of my keyboard while gaming, since most of the action happens on the left.

Gone is the Caps Lock as Ctrl. Caps is just Caps again. I’m still pressing it now and then out of habit, but for the most part, I switched back to using the original Control keys. I try to force myself to use my thumb, which means I have to curve my thumb into my left palm if I use the left side, or I just go all the way to the right and use my Ctrl key there. This is the most difficult part because it’s not just muscle memory: the Ctrl key is out of the way, and it can slow me down.

I also realized that the Windows key, which also acts as the Command key on my Mac, should be way more prominent than this keyboard allows. Thanks to PopClip on the Mac, I don’t use it much for copy-pasting on macOS (and since you have to use your mouse anyway to highlight text in Emacs, having PopClip is just a natural extension that I’m happy to have).

Speaking of the mouse, I know some of you will wrinkle your nose in disgust — but I started using it more in Emacs. Sometimes when I want to select text further down or up from where I am with the mark, it’s just easier to grab it and highlight the text this way instead of using the keyboard. I am also in the process of rediscovering the menus in Emacs (yes, those menus that all of you Emacs gurus love to hide), especially when it comes to reminding myself of useful shortcuts I keep forgetting — like registers, the mark ring, and other org-mode tricks I keep forgetting about.

My pinky still annoys me, but less. I seem to have this habit now of letting it hover over the keyboard instead of resting on the shift key. It’s almost as if I lost my ability to place my left hand correctly and naturally at times. It’s one of the things I hope the Glove80 might help with.

As the result of a long standing discussion on the Emacs devel list, Emacs 31 comes with what amounts to a starter kit called newcomers-presets¹. The idea is to provide newcomers with a set of useful configurations to help them ease into Emacs. It is, however, much more than training wheels for n00bs. The presets described in it are ones that most experienced Emacs users are already using.

I know this because last April Sacha Chua wrote a splendid post that describes what’s in it. I somehow missed it back when she first posted it but she mentioned it in the latest Emacs News. As I’ve said before, I don’t usually write about things that she’s already covered in Emacs News but I broke that rule yesterday so I might as well break it again, especially since her post is especially worth your attention.

When newcomers-presets was first introduced I didn’t pay too much attention to it but then Prot recommended it for experienced users as well as beginners. The problem was that I was unclear on what exactly it did. Then I saw the reference to Chua’s post. It has a comprehensive list of what it does along with a explanation for each setting.

I won’t be using it because I’m not a fan of starter kits for experienced users and because even if I like everything in it today, it could change tomorrow. It’s better, in my opinion, to see what’s in it and add the things you think are useful to your own configuration. Chua includes a handy “Copy code” button with each item to make that easy.

I’ll admit that until fairly recently I had no idea git worktrees existed. They’ve been part of git for a decade¹ and I never once needed them. Feature branches did the job just fine - create a branch, do the work, merge it, delete it, and start over.

What finally introduced me to worktrees was, of all things, AI coding agents. Tools like Claude Code create a worktree for each task, so several agents (or several sessions of the same agent) can work on the same repo in parallel without stepping on each other - or on you. Suddenly my projects directory was full of cider-this and cider-that siblings, and I figured I should understand what’s actually going on there.

Worktrees vs Branches

A branch is just a movable pointer to a commit, and making one is basically free. The catch is that a repository has a single working directory, so working on two branches means switching that directory back and forth. You know the routine: stash your half-done work (or commit it), check out the other branch, do the thing, check out the first branch again, unstash. It works, but it’s tedious, and it gets worse when the two branches leave your project in different build states and every switch means recompiling half the world.

A worktree gives you an additional working directory attached to the same repository:

$ git worktree add ../cider-smart-targeting -b smart-form-targeting

Now ~/projects/cider-smart-targeting is a full checkout of that branch, while your main checkout stays exactly where it was. The object database, refs, stashes and remotes are all shared - a worktree is not a clone, so fetching in one is fetching in all, and creating one is nearly instant. Each worktree gets its own HEAD and index, and git enforces one simple rule: a branch can only be checked out in one worktree at a time.

When are they worth it? Whenever two things need to happen at the same time: a long test run on one branch while you work on another, reviewing a PR without disturbing your half-done work, or - the reason everyone is talking about them these days - AI agents doing their thing in isolation. The price is pretty modest: your working files exist on disk more than once, and anything that isn’t tracked by git (dependencies, build caches, node_modules and friends) has to be set up again in each worktree.

If branches have never felt limiting to you, that’s fine - they didn’t for me either, for over a decade. Worktrees are one of those features you don’t miss until your workflow changes.

What About Jujutsu?

While we’re on the topic of working copies - the most interesting thing happening in version control right now is Jujutsu (jj), a git-compatible VCS that makes the problem worktrees solve mostly go away. In jj the working copy is a commit, snapshotted automatically as you work. There’s no staging area and no stash, because there’s no uncommitted state that could be lost or get in the way - switching contexts is always safe. It also has proper support for parallel working directories (jj workspace), plus an operation log that makes practically everything undoable. That last bit is part of why the AI agent crowd has taken an interest in it too.

You can use jj on top of an existing git repository (they call this a colocated repo), and your colleagues - and Magit - will keep seeing a normal git repo. I’m still just an observer here, but it’s clearly a project to keep an eye on.

Worktrees in Magit

Back to Emacs land. Magit has had worktree support for years, hiding behind Z:

The best part is that there’s nothing else to learn. Each worktree gets its own Magit status buffer, and every Magit command operates on the worktree the current buffer belongs to. Z g is the only switching mechanism you need, and even that is just a shortcut for visiting another status buffer.

A few practical tips from my (admittedly recent) experience:

• By default the status buffer doesn’t list your worktrees. Fix that with:

(magit-add-section-hook 'magit-status-sections-hook
                        #'magit-insert-worktrees
                        nil t)

Now every status buffer shows all worktrees of the repo, and you can hit RET on any of them to jump there.

• Create worktrees as siblings of the main checkout with descriptive names (cider-smart-targeting next to cider), not nested inside it - nesting confuses grep, find and plenty of other tools.

• Magit’s branch selection annotates branches that are checked out in another worktree with the worktree’s path, and refuses to check them out a second time (that’s git’s rule, not Magit being difficult). If you ever wondered why a branch “won’t check out”, that’s usually why.

• Each worktree is its own project as far as project.el (or Projectile) is concerned, so project switching, per-project buffers and search all work naturally.

• Anything that’s not tracked by git doesn’t come along for the ride. You’ll have to install dependencies once per worktree and start with a cold build cache. For Elisp that costs you nothing; for a big JVM or JS project it’s the main downside of the whole approach.

• When you’re done with a worktree, delete it with Z k (or with git worktree remove from the command line). If you just delete the directory by hand, git worktree prune will clean up the leftover bookkeeping.

Closing Thoughts

These days my workflow with agents usually looks like this: an agent does its work in a worktree, I review the changes there in Magit (often while another task is running in a second worktree), and the worktree goes away once the branch is merged. Maybe one day I’ll find other uses for worktrees - we’ll see.

Are you using git worktrees - and did you discover them the same roundabout way I did? I’d love to hear about it in the comments!

That’s all I have for you today. Keep hacking (in parallel)!

Nous avons parlé en direct avec Fabrice Niessen d'Emacs pour la deuxième fois. Voici ses notes.

Correction : J'ai voulu dire Speaches (un serveur de reconnaissance vocale) au lieu de speechd (un serveur de synthèse vocale)

Voici notre conversation précédente : Emacs Chat 28: Fabrice Niessen (en français)

You can e-mail me at sacha@sachachua.com.

Emacs ships with default settings intended for backward compatibility and convenience over strict security. The following settings enforce TLS certificate verification, reduce unintended ffap network lookups, restrict the evaluation of potentially unsafe local file, and directory variables, automated package review system, and protect authentication credentials stored by Emacs.

Network and communication security

By default, Emacs prompts the user interactively if a connection appears untrustworthy. You can additionally require certificate validation to fail at the TLS library level, causing invalid certificates to result in a connection error.

Requiring certificate validation at the TLS layer reduces the possibility of accidentally accepting an invalid certificate in response to an interactive warning.

Define these variables in your early-init.el to ensure the settings are established before startup code initiates network connections:

(setq gnutls-verify-error t)
(setq tls-checktrust t)
(setq gnutls-min-prime-bits 3072)

• gnutls-verify-error: Controls GnuTLS certificate verification. Setting this to t makes any certificate validation failure fatal.
• tls-checktrust: Controls external TLS binaries. Setting this to t ensures certificate validation is enforced if Emacs falls back to using external tools.
• gnutls-min-prime-bits: Defines the minimum acceptable size for Diffie-Hellman key exchange primes. Setting this to 3072 rejects handshakes using primes smaller than 3072 bits.

The benefit of strictly enforcing connection security at the TLS layer is preventing the accidental acceptance of invalid certificates or weak cryptography.

Find file at point network requests

The ffap (Find File At Point) package scans text around point to identify file paths, URLs, and hostnames. This triggers when you invoke an ffap command, most commonly find-file-at-point, which replaces standard C-x C-f if you have (ffap-bindings) enabled, while your cursor is resting on or near a string of text that resembles a domain name.

Setting ffap-machine-p-known to 'reject prevents FFAP from probing hostnames with known domains:

(setq ffap-machine-p-known 'reject)

The tradeoff is that ffap will no longer automatically recognize hostnames as remote connection targets, meaning you must enter remote host paths explicitly.

Encrypting auth sources

Emacs' auth-source uses files such as ~/.authinfo and ~/.netrc to store authentication credentials that other Emacs packages can retrieve when connecting to remote services. For example:

• Tramp: Passwords for remote server access.
• Gnus and Message: Credentials for mail retrieval (IMAP, POP3) and transmission (SMTP).

An auth-source entry can contain information such as a hostname, username, password, port, or protocol. Because these files may contain sensitive credentials, storing them as plain text exposes them to any process or user that can read the file.

To enforce the exclusive use of an encrypted file and prevent accidental plain-text credential storage, redefine the authentication sources list:

(setq auth-sources '("~/.authinfo.gpg"))

Additional security configurations:

• To encrypt the file using specific GPG public keys, define the recipients using auth-source-gpg-encrypt-to:

(setq auth-source-gpg-encrypt-to '("your.email@example.com"))

• Emacs can cache passwords to minimize prompt interruptions. The cache expiration can be configured using auth-source-cache-expiry:

(setq auth-source-cache-expiry 3600)

Clear auth-source cache when the user is idle

The auth-source library uses password cache to store authentication data in memory. By default, auth-source-do-cache is enabled (t) and auth-source-cache-expiry is set to 7200 seconds (2 hours). You can restrict this credential exposure using idle timers, targeted cache clearing, or by disabling the cache entirely.

Use an idle timer to purge credentials after a period of inactivity instead of waiting for the absolute cache expiry limit:

(defun my-security-clear-caches ()
  "Clear all cached authentication data managed by auth-source."
  (when (fboundp 'auth-source-forget-all-cached)
    (auth-source-forget-all-cached)))

(run-with-idle-timer 900 t #'my-security-clear-caches)

The benefit is that it limits memory exposure to 15 minutes of idle time. The tradeoff is that background operations requiring authentication may fail or block while awaiting a passphrase when returning to the editor.

Symbol shorthand code execution

Emacs 28.1 added a feature called symbol shorthands (read-symbol-shorthands). A vulnerability exists in Emacs versions 28.1 through 31 pretest where this feature can be abused to trigger arbitrary code execution simply by opening a specially crafted file. The malicious execution occurs immediately, even before the file contents are displayed.

The exploit relies on Emacs evaluating symbol shorthands during unsafe intern calls in vc-find-backend-function and c-compose-keywords-list. Emacs 31.1 mitigates the vulnerability. Earlier versions, including affected Emacs 31 pretest versions, remain vulnerable unless the mitigation is applied manually.

For users on Emacs 31 pretest or older, you can implement a mitigation by defining an advice function that locally disables symbol shorthands and applying it around the vulnerable operations.

(defun my-suppress-shorthands (orig &rest args)
  "Call ORIG function with ARGS while binding `read-symbol-shorthands' to nil.
ORIG is the original function being advised.
ARGS is the list of arguments passed to the original function.
This acts as advice to prevent arbitrary code execution via symbol shorthands
during unsafe operations like interning symbols on file open."
  (let (read-symbol-shorthands)
    (apply orig args)))

;; A workaround patch (Commit 8466eb44) was applied to the emacs-31 release
;; branch on August 5, 2026. Early pretest versions of Emacs 31 do not
;; include this mitigation.
(when (< emacs-major-version 32)
  (advice-add 'vc-find-backend-function :around #'my-suppress-shorthands)

  (with-eval-after-load 'cc-fonts
    (advice-add 'c-compose-keywords-list :around #'my-suppress-shorthands)))

This protects the editor from silent code execution attacks embedded in untrusted source files without requiring an upgrade to an unreleased Emacs version. The tradeoff is that it modifies core function behavior via advice, though the impact on version control and C/C++ fontification performance is negligible.

Package Management

Emacs 31.1 added package-review-policy, an automated package review system, allowing inspection of upstream code changes before installation:

(setq package-review-policy t)

Setting package-review-policy to t causes Emacs to require a review of packages before installation or upgrade. The package is unpacked into a temporary review directory, where the source can be compared with the previous installation (diff), and reviewed. The package is installed only if the review succeeds.

The main downside is that updates can no longer run in the background. Having to review diffs by hand gets tedious when upgrading multiple packages at once.

Securing .dir-locals.el and local variables

Emacs automatically applies project-specific configurations through file-local and directory-local (.dir-locals.el) variables when opening a file or directory. While this feature ensures consistent settings across environments, it can cause security risks and persistent prompt fatigue when editing source code. Malicious .dir-locals.el files or file-local variables containing eval forms can execute arbitrary Lisp code if Emacs is configured to evaluate them, or if the user explicitly approves the relevant prompt. This article outlines configurations for securing file-local and .dir-locals.el variables:
Emacs .dir-locals.el and Local Variables - Securing and Reducing Prompts.

I do a lot of writing, almost all of it in Emacs so I’m always happy to see how other people use our editor of choice for writing. The latest example I’ve found is from JTR over at The Art Of Not Asking Why. His post considers some simple expansion functions in Emacs.

He starts off with dictionaries. As many of you know, I’ve been a Webster 1913 dictionary user ever since James Somers explained why I (and you) should be. I have gone through many iterations of integrating it into Emacs but have converged on the same solution that JTR uses: the built in dictionary-search function built into Emacs that we both have configured to use the online collection dict.org, although I still have a local copy from my previous iterations.

The dict.org collection is nice because it contains several dictionaries besides Webster’s, and dictionary-search will return entries from all of them that have the word you’re looking for. The best part is that it’s trivial to set up You don’t have to download dictionaries or packages. You simply set a variable saying you want to use dict.org and that’s it. There are some nuances with that so be sure to read JTR’s post or the documentation.

JTR’s post is worth reading just for his dictionary advice but there’s more.

Next he briefly discusses Hippie Expand, a way of completing words based on a list of functions that you can specify. I’ve been using it for a long time, but his list of completion functions was more complete than mine so I stole it.

Finally, he considers ispell. If you’ve been following along, you’ll know that I recently started using Jinx instead of ispell but JTR showed me a couple of things I didn’t know about. I’ve always used ispell with flyspell so I never learned some of its extra tricks. One of those is a sort of fuzzy search for a word you’re not sure how to spell. That happens to me a lot so I was glad to find out about ispell’s ability to handle it.

The other thing you can do with ispell is to use it as a quick way of doing a replace. Take a look at JTR’s post for more on both those functions.

JTR’s post is from last week so Sacha will doubtless cover it before you see this but I had a lot to say about it so I decided to write about it anyway. It’s definitely worth a careful reading.

In late April of this year, I’ve began experiencing a heightened anxiety. I started therapy then later taking anti-anxiety medication. I worked to change some of my behaviors. And started writing even more personal journal entries.

Last Friday I found a list of feelings and responses that resonated with me:

• Angry: Lift weights
• Stressed: Go for a walk
• Procrastinating: Set a 10-minute timer
• Sad: Get sunlight
• Can’t focus: Clean your workspace
• Negative thoughts: Write 3 gratitudes
• Stuck: Change your environment
• Financial stress: Build an emergency fund
• Low energy: Fix your sleep
• Overthinking: Journal it out
• Lonely: Call someone
• No motivation: Start with 2 minutes
• Anxiety: Slow your breathing
• Brain fog: Drink water and move
• Low confidence: Keep small promises
• Lost: Define one clear goal

Twice I’ve looked to that list and found the emotions I was feeling and took action from the responses. The second time I found myself digging back through my journal to find the entry and pick how I was feeling.

And I realized, that I could encode this as an Emacs 📖 function and when I found myself needing to interrogate my “feels” I could type M-x how-im-feeling and get a set of responses I could then use to take action.

Here’s the how-im-feeling command and supporting variable:

(defvar how-im-feeling-responses
  '(("Angry" . "Lift weights")
    ("Stressed" . "Go for a walk")
    ("Procrastinating" . "Set a 10-minute timer")
    ("Sad" . "Get sunlight")
    ("Can't focus" . "Clean your workspace")
    ("Negative thoughts" . "Write 3 gratitudes")
    ("Stuck" . "Change your environment")
    ("Financial stress" . "Build an emergency fund")
    ("Low energy" . "Fix your sleep")
    ("Overthinking" . "Journal it out")
    ("Lonely" . "Call someone")
    ("No motivation" . "Start with 2 minutes")
    ("Anxiety" . "Slow your breathing")
    ("Brain fog" . "Drink water and move")
    ("Low confidence" . "Keep small promises")
    ("Lost" . "Define one clear goal"))
  "How I'm feeling and a simple response to move with that feeling")

(defun how-im-feeling ()
  "Prompt for how I'm feeling and respond with what to do."
  (interactive)
  (let ((feels
         (completing-read-multiple "I'm Feeling: "
                                   how-im-feeling-responses
                                   #'completing-read-omit-p
                                   t))
        (concatter
         (lambda (feel)
           (format "- *%s:* %s"
                   feel
                   (alist-get feel
                              how-im-feeling-responses
                              nil nil #'string=)))))
    (insert
     (format "I'm feeling:\n\n%s\n"
             (mapconcat concatter feels "\n")))))

(defun completing-read-omit-p (thusfar)
  "Omit completions THUSFAR given."
  (let ((input
         (butlast (split-string
                   (minibuffer-contents-no-properties)
                   crm-separator)))
        (test
         (car (last (split-string thusfar crm-separator)))))
    (not (member test input))))

Wrapping Up

Now, when I’m feeling the feels, I have another strategy for approaching and addressing those feels. The prompts don’t provide direct answers but instead nudge me towards moving with and through those feels. All in service of helping me cope with anxiety.

I don't play games within Emacs. Instead I enjoy learning about the many functions and modes it has. I even derived a Tip of the Day that displays help on a randomly-chosen function. I invoke it at startup; there's a non-zero probability that I'll spend 15 minutes or so exploring the function it provides.

I get the impression that I'm not the only one who enjoys Emacs this way. When I read others' postings, I see references to "customize," "configure," "init file," "rabbit hole." I'm pretty sure I also came across a few posts that contained this: "my ex-spouse made me chose between him/her and Emacs." Often, reading these posts is enjoyable in itself.

I enjoy writing and blogging, too. I started my first journal when I was 13 years old. My answer to "What book would you choose if stranded on an uninhabited island?¹" would be "a blank notebook that comes with a pencil." I also enjoy interacting with the Emacs community. It's as if this "Ray on Emacs" blog provides entertainment squared. This can be expressed mathematically as E2, where E is entertainment and 2 is two.

While researching this topic, I was surprised at how many games we can choose from, even in plain vanilla. Naive folks might scoff at programmers who write games for Emacs. But they don't understand that games demonstrate Emacs' capabilities. I suspect the underlying motivation is that writing games for Emacs is fun. It's a challenge that leads to accomplishment.²

I'm looking forward to reading submissions to Emacs Carnival September 2026 and trying some games. participate is Humor not to necessary.³

¹ aka "Desert Island" see Uninhabited island on Wikipedia

² Folks in the MS-DOS USENETs would joke about writing Batch Files that could do calculus. At least I think it was a joke.

³ "Humor is not necessary to participate" (as evidenced by this post).

Lexical binding: If you've recently updated to Emacs 31, you might have gotten warnings about lexical-binding in your packages or personal Emacs Lisp configuration. You can check your packages to see if the package authors have updated them. For your personal Emacs Lisp configuration, consider adding

;;; -*- lexical-binding: t -*-

to the top line. If that makes your code stop working correctly when you restart Emacs, set it to nil instead with:

;;; -*- lexical-binding: nil -*-

to get it to work for now. Additional resources:

• Selecting Lisp Dialect in the Elisp info manual
• Lexical scoping and dynamic scoping in Emacs Lisp | Yoo Box

Emacs Carnival: Check out the entries for August in "The Search for Knowledge" and stay tuned for September's topic, "Games."

• Emacs 31:
  • Emacs 31.1 is released! (Reddit, HN, HN, HN, Irreal, lobste.rs) - including this again from last week
  • Mickey Petersen: What's New in Emacs 31.1? (Reddit, HN) - including this again from last week
  • Android builds of Emacs 31.1 now available
  • Emacs 31.1 binaries now available for Windows (Reddit)
• Upcoming events (iCal file, Org):
  • EmacsATX: Emacs Social https://www.meetup.com/emacsatx/events/316121976/ Thu Sep 3 1600 America/Vancouver - 1800 America/Chicago - 1900 America/Toronto - 2300 Etc/UTC – Fri Sep 4 0100 Europe/Berlin - 0430 Asia/Kolkata - 0700 Asia/Singapore
  • M-x Research: TBA https://m-x-research.github.io/ Fri Sep 4 0800 America/Vancouver - 1000 America/Chicago - 1100 America/Toronto - 1500 Etc/UTC - 1700 Europe/Berlin - 2030 Asia/Kolkata - 2300 Asia/Singapore
  • Emacs.si (in person): Emacs.si meetup #9 2026 (v #živo) https://dogodki.kompot.si/events/8711d3f8-b0d7-48bf-a64b-8cd48eed728c Mon Sep 7 1900 CET
  • London Emacs (in person): Emacs London meetup https://www.meetup.com/london-emacs-hacking/events/316294538/ Tue Sep 8 1800 Europe/London
  • Emacs Berlin: In-Person-Only Emacs-Berlin Stammtisch https://emacs-berlin.org/ Tue Sep 8 1900 Europe/Berlin
  • OrgMeetup (virtual) https://orgmode.org/worg/orgmeetup.html Wed Sep 9 0900 America/Vancouver - 1100 America/Chicago - 1200 America/Toronto - 1600 Etc/UTC - 1800 Europe/Berlin - 2130 Asia/Kolkata – Thu Sep 10 0000 Asia/Singapore
  • Atelier Emacs Montpellier (in person) https://lebib.org/date/atelier-emacs Fri Sep 11 1800 Europe/Paris
• Beginner:
  • [Article] What's in the Emacs 31 newcomers-presets theme? by Sacha Chua (Reddit)
  • No instales otro editor hasta ver esta guía de Emacs en Linux (17:25)
  • Introduction to the GOAT IDE - Vanilla Emacs (14:09)
• Emacs configuration:
  • Andros Fenollosa: How I organize my Emacs configuration (Irreal)
  • Chris Maiorana: Don’t go bankrupt, go local (Irreal)
  • James Cherti: Securing and reducing prompts for Emacs .dir-locals.el and local variables
  • Measuring Emacs Startup Time More Accurately Than the Built-in emacs-init-time Function (Reddit)
  • Guard.el on Melpa (Reddit)
• Emacs Lisp:
  • Tip about using unread-command-events to simulate keyboard input (@mark@mastodon.fixermark.com)
  • Doom Emacs: debugging a yasnippet issue with edebug (01:16:31)
  • Emacs Warning (files): Missing ‘lexical-binding’ cookie (19:34)
• Appearance:
  • cursor-breathe-mode.el - animate cursor and make it "breathe" (@etenil@toot.cat)
  • New Package (minibuffer-frame) (Reddit)
  • Configuring Emacs Scrolling for Better Performance and Usability (Reddit, Irreal)
  • Larp. Emacs Rice 🦄 (12:45, and also Larp. Emacs Rice FIX 🤎📜🧸 03:11)
• Navigation:
  • Improved hierarchical imenu entries for elisp - fold defun/use-package under sections (@benleis@mathstodon.xyz)
  • kirigami.el 1.2.0 - A unified way to fold and unfold code and text in Emacs​ (Reddit)
  • easysession.el 1.3.0: Persist and Restore Emacs sessions​ (Reddit)
• Hyperbole:
  • Hyperbole HyRolo: Search, Retrieve and Insert Records, Not Lines (YouTube 25:47, (Reddit)
• Dired:
  • James Cherti: Fixing Emacs Dired Defaults: Settings for Better File Management (Reddit)
• Writing:
  • TAONAW - Emacs and Org Mode: Emacs Config Gems - Part 5 dict, hippie-expand, ispell (Irreal)
  • An unofficial guide to markdown-ts-mode on Emacs 31 (Reddit, HN)
  • Emacs Treesitter Markdown Mode - First Impressions (17:47)
  • mado/emado update: static binaries, fuzzy matching, and more (Reddit) - markdown organizer for Emacs
  • Emacs Redux: Meet Utterson, my Jekyll blogging helper
  • Irreal: Fixing Define-word
• Denote:
  • Donovan R.: My way of handling knowledge (Emacs Carnival - The Search for Knowledge)
• Org Mode:
  • Org Mode requests: [FR] Include :var expansion in expanded noweb references (was: ob-clojure :var header argument not work when src block is noweb called by another src block)
  • Emacs Carnival Aug 2026: Information management and knowledge graphs
    • Carnaval d'Emacs d'août 2026 : la gestion d'information et les graphes de connaissances
  • Automatically insert a checkbox into the new Org list item if the current item has one, even with M-RET (org-meta-return) (@stackeffect@social.tchncs.de) (acts like M-S-RET, org-insert-todo-heading)
  • Updated my ob-glsl module to use Emacs 32 Canvas for animation (Reddit)
  • Org development:
    • lisp/org-capture.el: Accept omitted or nil headline for the file+headline
    • lisp/org-capture.el: Accept omitted or nil olp for file+olp+datetree and file+olp
    • org: Add org-submit-feature-request and org-submit-patch commands
    • ol: Add new custom variable org-link-preview-include-descriptive
• Completion:
  • Protesilaos: Emacs: completion-preview-mode and the Completions buffer (Emacs 31) (YouTube 09:18, Reddit)
  • Silence the bell during minibuffer completions that may not be strict - minibuffer-completion-help (@ross@rossabaker.com)
  • Snippets + completion read
• Coding:
  • Configuring Python Development in Emacs: Eglot, Pylsp, and Dynamic Ruff Integration (Reddit)
  • Configuring Emacs Eglot for Optimal Performance (Reddit)
  • How to remove Eglot from the mode line (@jamescherti)
  • envrc.el package - Rewrite to support optional async or time-limited direnv invocation by purcell · Pull Request #130 · purcell/envrc · GitHub (@sanityinc@hachyderm.io)
  • Meta Redux: Smarter Form Targeting Is Not Coming to CIDER (previous)
• Shells:
  • Tip about using -a (–alternate-editor) so you can use emacsclient even without having started daemon mode (@citizen428@chaos.social)
  • What kind of wizardry is possible in M-x shell?
• Web:
  • andros/kagi-search.el: Browse Kagi search results inside Emacs, in a plain buffer, without a graphical browser and without JavaScript (@andros@activity.andros.dev)
  • browsel has been renamed to browser-gt and is now available on MELPA (v0.95). (Reddit)
• Mail, news, and chat:
  • Andros Fenollosa: A year of Org Social, my social network
• Multimedia:
  • bartbunting/emacsvox: An experiment in modernization of Emacspeak · GitHub (@pixelate@tweesecake.social)
  • Charles Choi: Announcing shazam.el (Reddit)
• Fun:
  • RFC: card-games (MELPA) - thirty-five single and multi-player games for emacs (1.0.92:rc2)
  • Uniline goes 2.5 dimensions - followup
• LLMs:
  • seewhydee/dsh-emacs-bridge: Deepseek Harness to Emacs bridge · GitHub (@cyd@kopiti.am)
  • Using LLMs to make the Emacs Web Browser Great Again (16:32)
  • ellm - Plain text LLM agent (Reddit)
  • [New package] openclaw-sessions: monitor multiple OpenClaw TUI sessions from Emacs (Reddit)
• Community:
  • Fortnightly Tips, Tricks, and Questions — 2026-08-25 / week 34
  • why I prefer emacs over vim (for writing & lisp programming) (06:50)
  • Emacs Chat 30: Fabrice Niessen (en français, partie 2) (01:05:56)
• Other:
  • caffeinated-compile: prevent sleeping on MacOS (@Viiru@corteximplant.com)
  • Marcin Borkowski: Transforming yanked text
• Emacs development:
  • Recognize comment-prefixed headings in outlines
  • Mark timezone-world-timezones obsolete
  • Mark math-tzone-name obsolete
  • ; * etc/NEWS: Announce IME support on w32 TTY frames. (Bug#81495)
  • viper-ex: Implement z command
  • ; * etc/NEWS: Announce addition of 'uuid' library.
  • Add button to diff failed erts-file test output in ERT
  • * lisp/dired.el (dired-jump-map): Remove key 'j' bound to 'dired-jump'.
• New packages:
  • consult-magit: Switch and manage magit buffers with consult (MELPA)
  • cperl-mode: Perl code editing commands (GNU ELPA)
  • eglotx: Native LSP multiplexer for Eglot (MELPA)
  • full-gtd: Complete Getting Things Done (GTD) workflow for org-mode (MELPA)
  • gptel-inline: Persistent gptel session that follows you around (MELPA)
  • latex-to-svg-backend: Content-addressed LaTeX-to-SVG image rendering (MELPA)
  • magent: AI coding agent (MELPA)
  • org-draw: Draw into Org from a browser (MELPA)
  • org-relative-date: Live relative-date overlays on org timestamps (MELPA)
  • project-nix-store: Project backend for Nix-like store (NonGNU ELPA)

Links from reddit.com/r/emacs, r/orgmode, r/spacemacs, Mastodon #emacs, Bluesky #emacs, Hacker News, lobste.rs, programming.dev, lemmy.world, lemmy.ml, planet.emacslife.com, YouTube, the Emacs NEWS file, Emacs Calendar, and emacs-devel. Thanks to Andrés Ramírez for emacs-devel links. Do you have an Emacs-related link or announcement? Please e-mail me at sacha@sachachua.com. Thank you!

You can e-mail me at sacha@sachachua.com.

Emacs automatically applies project-specific configurations through file-local and directory-local (.dir-locals.el) variables when opening a file or directory. While this feature ensures consistent settings across environments, it can cause security risks and persistent prompt fatigue when editing source code. Malicious .dir-locals.el files or file-local variables containing eval forms can execute arbitrary Lisp code if Emacs is configured to evaluate them, or if the user approves the relevant prompt by mistake.

This article outlines configurations for securing file-local and directory-local variables while reducing prompts.

Allowing safe local variables

The enable-local-variables variable controls how Emacs handles file-local variables. File-local variables are configurations embedded directly within a file. Here is an example of a file-local variables:

;; Local variables:
;; fill-column: 100
;; byte-compile-warnings: (not free-vars)
;; End:

To mitigate security risks and prevent interactive prompts, set enable-local-variables to :safe by adding the following to your init file:

(setq enable-local-variables :safe)

The benefit is that Emacs applies only verified safe values while silently dropping risky ones, reducing prompt fatigue without requiring manual confirmation. The tradeoff is that non-standard but safe project variables will be ignored unless their values are explicitly recognized as safe, for example through safe-local-variable-values or the safe-local-variable property.

Note: Setting enable-local-variables to nil disables normal processing of local variables entirely. (Specific settings, such as lexical-binding, remain active via the permanently-enabled-local-variables list.)

Whitelisting specific local variables

When you set enable-local-variables to :safe, Emacs silently ignores unverified variables. To prevent custom project variables from being ignored, you can explicitly mark specific variable/value pairs as safe using safe-local-variable-values, or define a predicate with the safe-local-variable property:

;; Whitelist a specific variable and value: Add the pair directly to the list.
(add-to-list 'safe-local-variable-values '(my-custom-variable . "expected-value"))

;; Whitelist a variable based on a predicate type: Define a property that
;; validates the variable type to accept any matching value.
(put 'my-custom-variable 'safe-local-variable #'stringp)

;; Whitelist a variable with a predicate: Only allow "hello" or "world"
;; as safe values.
(put 'my-custom-variable 'safe-local-variable
     (lambda (val)
       "Return t if VAL is 'hello' or 'world'."
       (member val '("hello" "world"))))

Whitelisting specific directories

The safe-local-variable-directories variable allows you to designate specific paths where all directory-local variables are automatically considered safe. When a directory is added to this list, Emacs trusts every variable defined in its .dir-locals.el file without prompting. Note that this setting applies exclusively to directory-local variables and completely ignores file-local variables.

(add-to-list 'safe-local-variable-directories "/path/to/trusted/project/")

Disabling Local Eval Forms

The enable-local-eval variable controls whether Emacs processes eval forms in file-local and directory-local variable definitions. Unlike ordinary local variable assignments, eval can cause Emacs to evaluate arbitrary Lisp code when processing the local variables.

If your workflow does not require dynamic project configurations, you should disable this feature by setting this variable to nil:

(setq enable-local-eval nil)

The tradeoff is that useful evaluation forms, such as project-specific configurations dynamically generated through eval, will not execute.

Keeping default values for security

Emacs comes with the following defaults for local environment handling. Sticking with these defaults is already a good choice:

(setq enable-dir-local-variables t)  ; Apply directory-local variables.
(setq enable-remote-dir-locals nil)  ; Prevent loading dir-locals over TRAMP.

• enable-dir-local-variables: This enables the use of directory-local variables (.dir-locals.el). Note that Emacs also reads .dir-locals-2.el if present, and non-file buffers like Dired can inherit these settings.
• enable-remote-dir-locals: Leaving this as nil prevents Emacs from loading directory-local variables from remote filesystems. This avoids applying potentially untrusted remote .dir-locals.el settings and avoids the additional work required to search for them.

August Emacs carnival is about the search for knowledge. While I take notes and link them, I don't use Emacs. I've been on the Obsidian train pretty much since it came out with a short deviation into Craft.

I've loved the plugins that Obsidian has, but those plugins are also it's downfall. I used the Long Form plugin for a while, but then stopped and move that writing to Emacs because the plugin was loosing my data any time I tried to use it. But despite my love for Emacs, I haven't moved my notes over to it and I have no plans on moving my notes over to Emacs.

Currently Obsidian has around 9,000 individual files across my notes and writing. It's saved in a portable markdown format. Obsidian's sync service works flawlessly all the time and the mobile apps are good.

On the Emacs side, every few weeks I have some issue with Syncthing that means I need to sort out some type of sync conflict and because of this I really only add content from my phone via Beorg to my inbox.org file. I don't edit other files if I can help it, the risk is simply to high that I'll have some huge mess to sort out when I get back to my desktop.

The main reason I don't switch is that I don't think that migrating tools is the big productivity boost that most people think it is. Yes the Emacs vim key bindings are better than what Obsidian provides. Yes I can very easily hack Emacs to do whatever I want, but Obsidian does everything I need already. So moving my notes to Emacs would most likely be me finding Emacs more fun right now than Obsidian because it's new.

I've wondered about accessing Obsidian from Emacs so I have Emacs goodness in my Obisidian, but even that feels like me searching for a reason to use Emacs where I don't really need it.

If you want to read how I setup Obsidian, my 2026 walkthrough is still how I do it.

Chris Maiorana has a useful post on directory local variables. The idea is that rather than putting a lot of context specific configuration in your init.el file, you can put those configurations in a .dir-locals.el file and they will be set only when you open a file in that directory.

I really like the idea of directory local variables but it has never worked well for me. That’s mainly because I usually wanted to execute some code using the eval keyword. That always causes some problems involving a stack overflow, no matter how simple the code is. Lately, I’ve been using them a lot in conjunction with Jinx, which has the nice feature of adding words to the local file or local directory in addition to the other usual options.

I find that really useful for my blogging. I can add post specific words to the post source file itself or I can add them to all posts in my blog directory. Maiorana uses then to set things like compilation settings, fill and wrap settings, and indentation styles.

If you have different workflows with different setting needs, directory local variables is a very nice way of dealing with them. Of course, not everything should go in a directory local variable. Some things apply to all your buffers and should go in your init.el but for those things that are specific to particular workflows, directory local variables are just what you need.

This article presents a set of Emacs Dired configuration changes to enhance file management. The configurations sort directories before files for easier navigation, hide dotfiles, reduce unnecessary confirmation prompts, prevent UI lockups caused by network latency, among other improvements. Each configuration explains the behavior of the relevant setting, its benefits, and its tradeoffs, making it easier to determine which changes are appropriate.

Keeping Dired clean by hiding dotfiles

Using dired-omit-mode helps hide hidden files and directories, such as .git or .DS_Store, by applying a specific regular expression. The tradeoff is that required configuration files are hidden by default, forcing you to toggle dired-omit-mode off to see them. Disabling dired-omit-verbose prevents the mode from displaying status messages when omitting files.

(setq dired-omit-verbose nil)
(setq dired-omit-files (concat "\\`[.]\\'"
                               "\\|\\.\\(?:elc\\|a\\|o\\|pyc\\|pyo\\|swp\\|class\\)\\'"
                               "\\|^\\.DS_Store\\'"
                               "\\|^\\.\\(?:svn\\|git\\)\\'"
                               "\\|^flycheck_.*"
                               "\\|^flymake_.*"))

(add-hook 'dired-mode-hook #'dired-omit-mode)

To hide all hidden files whose names begin with a dot, add the following regular expression to the dired-omit-files variable:

(setq dired-omit-files (concat dired-omit-files "\\|^\\."))

Hiding details

Enabling dired-hide-details-mode automatically hides file details such as permissions, size, and modification dates.

(add-hook 'dired-mode-hook #'dired-hide-details-mode)

Sorting directories first

The following code snippet configures Dired to sort directories before files. The benefit is improved navigation, as folders are grouped at the top of the buffer, matching standard file managers. The tradeoff is a deviation from strict alphabetical sorting, which can disorient users accustomed to raw UNIX or Linux ls output.

(setq ls-lisp-verbosity nil
      ls-lisp-dirs-first t)

(when (eq system-type 'darwin)
  (setq dired-use-ls-dired nil)) ; macOS/BSD ls

(let ((args "--group-directories-first -ahlv"))
  (when (or (eq system-type 'darwin) (eq system-type 'berkeley-unix))
    (if-let* ((gls (executable-find "gls")))
        (setq insert-directory-program gls)
      (setq args nil)))
  (when args
    (setq dired-listing-switches args)))

Killing the current Dired buffer upon navigating into a different directory

Setting dired-kill-when-opening-new-dired-buffer to t (Emacs >= 28.1) causes Dired to automatically kill the current Dired buffer upon navigating into a different directory. The benefit is a cleaner buffer list, as it prevents leaving behind a trail of open buffers when traversing deep directory hierarchies. The tradeoff is the loss of buffer state. Navigating back to a parent directory requires generating a new buffer, which erases previous cursor positions, active file marks, and modified subdirectory visibility.

(setq dired-kill-when-opening-new-dired-buffer t)

Version control integration

Enabling dired-vc-rename-file causes Dired to perform file renames through the underlying version control system when supported, using the vc-rename-file function. The benefit is accurate version control history during Dired rename operations. The tradeoff is that VC renames can introduce slight latency on very large repositories.

(setq dired-vc-rename-file t)

Simplifying deletion confirmations

This configuration accelerates file cleanup by reducing the number of manual prompts required to delete files and directories.

(setq dired-deletion-confirmer 'y-or-n-p
      dired-recursive-deletes 'top
      dired-clean-confirm-killing-deleted-buffers nil)

• Setting dired-deletion-confirmer to 'y-or-n-p: Changes the deletion prompt to accept a single 'y' or 'n' keypress instead of requiring you to type the full word 'yes'.
• Setting dired-recursive-deletes to 'top: By default, deleting a non-empty directory in Dired can be a tedious process because Emacs will prompt you to confirm the deletion of every single nested subdirectory as it traverses down the tree. Setting this variable to 'top establishes a practical balance between speed and safety. Emacs will ask for your confirmation exactly once for the top-level directory you have marked. Once you confirm that initial prompt, it silently and recursively deletes all nested files and folders inside that tree without any further interruptions.
• Setting dired-clean-confirm-killing-deleted-buffers to nil: Suppresses the prompt that asks for permission to close Dired buffers associated with directories you just deleted, closing them automatically instead. This makes sense because once a directory is removed from the disk, any open buffer pointing to it becomes orphaned and unusable. Automatically killing these dead buffers keeps your buffer list clean, as deleting the directory already establishes your intent to remove it from your workflow entirely.

The benefit is faster file management and fewer repetitive keystrokes. The tradeoff is an elevated risk of accidental data loss, as the safety barrier to executing destructive operations is significantly lowered.

Removing disk space indicator

Disabling dired-free-space (Emacs >= 29.1) removes disk space indicator from Dired buffers. The tradeoff is that you lose quick visibility into remaining disk capacity.

(setq dired-free-space nil)

Restricting vertical cursor movement

Setting dired-movement-style to 'bounded-files (Emacs >= 29.1) restricts vertical movement to file lines in the Dired buffer. When point reaches the first or last file line, further vertical movement stops instead of moving to other non-file lines. The benefit is increased navigation efficiency. When scrolling rapidly to the top or bottom of a directory, the cursor stops exactly on the first or last file or directory, avoiding empty space or metadata lines. The tradeoff is that placing the cursor on the directory header to copy its path requires alternative navigation commands, as standard vertical movement keys will no longer reach it.

(setq dired-movement-style 'bounded-files)

Managing recursive copies and destination directories

These variables force Dired to copy directories recursively by default without prompting, while explicitly asking for confirmation before creating new, non-existent destination directories. The benefit is bulk copying combined with a safety check against typos in destination paths. The tradeoff is that large, deeply nested directory structures might be copied unintentionally since the recursive copying happens automatically.

(setq dired-recursive-copies 'always
      dired-create-destination-dirs 'ask)

Efficient auto-reverting for dired buffers

Configuring dired-auto-revert-buffer to use dired-directory-changed-p causes Dired to automatically revert the buffer when the listed directory has changed. The benefit is improved efficiency because Dired does not unconditionally rebuild the listing. The tradeoff is that changes that do not modify the directory itself, such as in-place edits to existing files, might not trigger an automatic refresh.

(setq dired-auto-revert-buffer 'dired-directory-changed-p)

Note: On Unix-like filesystems, a directory's mtime (modification time) is updated when its directory entries change. This occurs when a file or subdirectory is created, deleted, or renamed within the directory. Modifying the data inside an existing file updates the file's mtime, but does not update the mtime of its parent directory.

Reverting destination buffers after file operations

This configuration automatically updates destination Dired buffers after file operations like copying or renaming, but uses a custom predicate to skip remote directories. The benefit is automatic synchronization of local Dired buffers without performing the same operation on remote directories, avoiding unnecessary TRAMP network activity and associated latency. The tradeoff is that remote directory buffers require a manual refresh to reflect recent file transfers.

(setq dired-do-revert-buffer (lambda (dir)
                               (not (file-remote-p dir))))

Enabling mouse drag-and-drop

Setting dired-mouse-drag-files to t (Emacs >= 29.1) allows you to click and drag files directly from a Dired buffer into external desktop applications, such as graphical file managers or web browsers.

(setq dired-mouse-drag-files t)

Cross-platform file associations

The following snippet configures Dired to open specific file extensions using the default application handler of the host operating system. It identifies the environment (macOS, Linux, or Windows) and assigns the corresponding system command (open, xdg-open, or start) to the dired-guess-shell-alist-user variable for documents, images, and media files. The main benefit is that it delegates file association management to the operating system, removing the need to configure individual applications within Emacs for every file type.

(defvar my-dired-xdg-open-cmd nil)
(with-eval-after-load 'dired
  (when-let* ((cmd (cond
                    ((eq system-type 'darwin)
                     "open")
                    ((memq system-type '(gnu gnu/linux gnu/kfreebsd
                                             berkeley-unix))
                     "xdg-open")
                    ((memq system-type '(cygwin windows-nt ms-dos))
                     "start"))))
    (setq dired-guess-shell-alist-user
          `(("\\.\\(?:docx\\|pdf\\|odt\\|odg\\|ods\\|djvu\\|eps\\)\\'" ,cmd)
            ("\\.\\(?:jpe?g\\|webp\\|png\\|gif\\|xpm\\)\\'" ,cmd)
            ("\\.\\(?:xcf\\)\\'" ,cmd)
            ("\\.tex\\'" ,cmd)
            ("\\.\\(?:mp4\\|mkv\\|m4a\\|avi\\|flv\\|rm\\|rmvb\\|ogv\\)\\(?:\\.part\\)?\\'" ,cmd)
            ("\\.\\(?:mp3\\|flac\\)\\'" ,cmd)))
    (when cmd
      (setq my-dired-xdg-open-cmd cmd))))

How to use it: To use this configuration in practice, navigate to a directory using Dired and place your cursor over a file. For example, if your cursor is on a video file, press ! (which invokes dired-do-shell-command) or & (for asynchronous execution). Dired will prompt you in the minibuffer with the appropriate system command already populated based on your operating system, such as xdg-open. Press RET to confirm, and the video will open in your operating system's default media player.

If you prefer forcing all file types to open asynchronously via the operating system handler (e.g., xdg-open), the following snippet routes every file through the system default application.

(defvar my-dired-xdg-open-cmd nil)
(with-eval-after-load 'dired
  (when-let* ((cmd (cond
                    ((eq system-type 'darwin)
                     "open")
                    ((memq system-type '(gnu gnu/linux gnu/kfreebsd
                                             berkeley-unix))
                     "xdg-open")
                    ((memq system-type '(cygwin windows-nt ms-dos))
                     "start"))))
    (setq dired-guess-shell-alist-user
          `((".*" ,cmd)))
    (when cmd
      (setq my-dired-xdg-open-cmd cmd))))

Emacs configurations are like well shuffled card decks: no two are alike. But, as Arlo Guthrie famously sang, that’s “not what I came to tell you about”. Rather, this post is about differing organizations for those Emacs configurations.

The idea was suggested to me by a post from Andros Fenollosa on his own Emacs configuration. Fenollosa says that he doesn’t use any of the all-in-one configurations like Spacemacs or Doom because they include too much and are hard to understand and make changes to. He also doesn’t use the popular literate configuration method using Org mode because it’s just another layer of complexity that can go wrong.

His idea is to to have a separate file for each “area of responsibility” and to use init.el as a sort of index that loads them in order. I like that idea but don’t use separate files. I keep everything in init.el and just organize it in sections.

Still, Fenollosa has a good argument for the separate files but I think I get the same benefits with a single file broken into sections. Actually, it’s not quite true that everything is in a single file. I run Emacs on several type of systems and keep the system/OS specific information in separate files that I load conditionally based on the system and OS type¹. That way I don’t have a lot of conditionals dealing with system/OS type in init.el itself.

There aren’t as many ways of organizing your Emacs configuration as there are configurations but there are a lot of them. What principle do you use?

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Pull in system and platform specific configurations                    ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;; Just keep on going if the requisite file isn't there.
;; Manipulations in second load is for "gnu/linux" → "linux"

(load (car (split-string (system-name) "\\.")) t)
(load (car (reverse (split-string (symbol-name system-type) "/"))) t)

Cet article est inspiré par le Carnaval d'Emacs sur la recherche de connaissances. Merci à Charlie Holland pour son accueil ! C'est une bonne occasion de réfléchir à la gestion de mes notes, qui est un de mes intérêts forts.

Saisir : Je souhaite saisir et publier ce que j'apprends aussitôt que possible parce que ma mémoire n'est pas fiable. Je préfère le format texte brut car il est le plus consultable et le plus archivable à long terme. Je suis loin de mon ordinateur la plupart du temps, donc j'utilise Orgzly Revived sur mon téléphone pour saisir des notes courtes dans ma boîte de réception inbox.org ou mon fichier de brouillons posts.org. Une fois que je suis sur mon ordinateur, je développe mes notes en utilisant Org Mode sur Emacs. J'utilise org-refile pour déplacer des notes vers d'autres fichiers comme organizer.org. J'utilise quelques grands fichiers Org. Pour les tâches répétitives comme mes flux de travail, j'y ajoute des détails autant que possible.

Chercher : Pour chercher mes notes publiques, j'utilise souvent Google. Les notes publiques me permettent de les récupérer facilement. Si je publie mes notes, d'autres personnes peuvent en profiter et les enrichir. Forcément, j'ai aussi des notes personnelles. J'utilise org-refile pour chercher par titres ou consult-ripgrep pour naviguer dans mes notes privées. J'utilise aussi consult-line et isearch si je veux chercher par mots dans le corps. Ils reposent sur des comparaisons exactes, mais si j'essaie des mots similaires, je ne peux pas trouver ce que je cherche. C'est la raison pour laquelle je m'intéresse au paquet p-search et aux plongements de phrases (embeddings) pour la recherche approximative, mais je n'ai pas encore mis en place un bon flux de travail. Je rêve d'un système pour suggérer automatiquement des liens vers mes autres articles, ma configuration et mes notes privées, ce qui peut me rafraîchir la mémoire sur des choses oubliées. Une vraie évaluation doit attendre d'avoir plus de temps libre.

Naviguer : J'utilise C-u org-refile pour naviguer dans mes sous-titres n'importe où dans mes fichiers org-refile-targets. Je relis aussi ma boîte de réception et mes brouillons de temps en temps. J'ai une fonction sacha-blog-edit-org qui ouvre le code source Org à partir d'un lien, même s'il est dans mon posts.org ou seulement dans la copie publiée.

Lier : Beaucoup de mes idées sont inspirées par des articles d'autres personnes, donc quand je trouve un article intéressant sur mon téléphone, je l'envoie à Orgzly Revived pour l'ajouter à ma boîte de réception. Ça me permet d'inclure le lien ou les liens dans l'article une fois que je réussis finalement à l'écrire et à le publier.

J'ai une petite fonction sacha-org-contacts-suggest-mentions qui m'aide à notifier l'auteur de l'article précédent et peut-être d'autres personnes qui sont potentiellement intéressées en utilisant mon fichier people.org, où j'ai spécifié des expressions régulières à comparer au texte.

Pour m'aider à lier l'article aux autres ressources, j'ai des fonctions pour lier :

• aux articles sur mon blog avec le genre de lien "blog"
• aux autres sites automatiquement à partir du texte du lien

(Hmm, je peux automatiser les liens vers les autres parties de ma configuration qui définissent les autres fonctions…)

Mes pensées sont souvent déconnectées à cause d'un cerveau qui aime sauter d'un sujet à l'autre.​ (Bien évidemment, même avec cet article…) En écrivant un article, j'ajoute de nombreuses idées dans ma boîte de réception. À bien y penser, je pourrais ajouter à Org Mode un genre de lien qui résoudra un vrai lien une fois que l'article lié sera publié, comme les WikiWords, ce qui peut m'aider à les connecter. Je sais qu'il y a des paquets qui offrent cette fonctionnalité.

Publier : J'utilise le générateur de site statique 11ty avec ox-11ty.el. Une fois que je publie une note, le code source org est aussi copié dans le même répertoire.

Visualisation et exploration

J'ai toujours envie de graphes de connaissances comme celui dans le cerveau de Jerry. Je pense que l'affichage du voisinage autour de l'article actuel est plus utile qu'un aperçu global (comme ceux de ) qui est impressionnant mais un peu trop difficile à utiliser.​

J'adore également les grands jardins publics de connaissances comme celui d'Andy Matuschak même si on n'a pas une véritable carte ou un graphe. La richesse des liens m'encourage à les explorer. Je préfère les liens intégrés plutôt que les listes ou les connexions ​sans explications. Je suis curieuse aussi du projet Anagora, qui essaye de créer un grand réseau de graphes de connaissances personnels et de faciliter le saut de l'un à l'autre par sujet.

Mais je ne veux pas investir trop d'efforts pour le faire moi-même. La majorité de mes articles (sauf le bulletin d'information Emacs News et les revues) contiennent peu de liens. Si je reste au niveau des catégories, il y a trop de points près d'Emacs. Je pourrais convertir les sous-catégories dans mon catalogue en données pour la visualisation… Quand même, le catalogue aurait bien besoin d'une mise à jour.

Il y a d'autres genres de graphes que j'utilise fréquemment. Je dessine souvent pendant que j'écris. Je fais des cartes mentales et des notes dessinées. En fait, c'est plutôt que je jette plusieurs mots sur une page et puis que je les déplace, les connecte, et les range graduellement. Je le fais pour découvrir ce que je veux dire et comment je peux les organiser. De temps en temps, j'inclus des dessins dans les articles ou les publie dans mon carnet de croquis public, et c'est une agréable surprise quand un de ces dessins intéresse d'autres personnes.

J'accumule beaucoup de brouillons dans mon fichier posts.org, que je synchronise avec mon téléphone via Syncthing pour éditer sur Orgzly Revived. De temps en temps, j'utilise une carte arborescente (ou treemap) pour visualiser les tailles des brouillons oubliés (et qui sont peut-être presque finalisés, il leur manque seulement une petite révision ou un ajout). (Hmm, je me demande comment je peux ajouter la taille du sous-arbre aux titres d'Org…)

En plus, j'apprécie l'analyse des tendances saisonnières ou annuelles dans ma fréquence de publication (qui me rassure sur le fait que les journées chargées de l'été sont normales et je retrouverai bientôt un peu plus de temps libre):

Tendances mensuelles

import json
import seaborn as sns
import re
from collections import defaultdict
import requests
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
with open('/home/sacha/proj/static-blog/_site/blog/all/index.json') as jsonfile:
    posts = json.load(jsonfile)
    jsonfile.close()
monthly_counts = defaultdict(lambda: defaultdict(int))
for post in posts:
    title = post.get("title", "")
    date_str = post.get("date", "")
    if re.search(r'emacs news', title, re.IGNORECASE):
        continue
    if date_str and len(date_str) >= 7:
        year = date_str[:4]
        month = int(date_str[5:7])
        monthly_counts[year][month] += 1
months_labels = ['Jan', 'Fév', 'Mar', 'Avr', 'Mai', 'Juin', 'Juil', 'Août', 'Sept', 'Oct', 'Nov', 'Déc']
years = ['2022', '2023', '2024', '2025', '2026']
df = pd.DataFrame(index=range(1, 13), data={'Mois': months_labels})
for year in years:
    df[year] = [monthly_counts[year][m] for m in range(1, 13)]
df.iloc[8:, -1] = None
df_long = df.melt(id_vars=['Mois'], value_vars=years, var_name='Année', value_name='Compte')
num_old_years = len(years) - 1
gray_shades = np.linspace(0.8, 0.3, num_old_years)  # 0.8 is lighter, 0.3 is darker
custom_colors = {year: str(shade) for year, shade in zip(years[:-1], gray_shades)}
custom_colors['2026'] = "#000000"  # Force the current year to pure black
widths = {year: 1 for year in years}
widths['2026'] = 3
plt.figure(figsize=(10, 5))
ax = sns.lineplot(data=df_long, hue='Année', x='Mois', y='Compte', size='Année', palette=custom_colors, sizes=widths, sort=False)
ax.set_xticks(range(12))
ax.set_xticklabels(months_labels)
plt.title("Fréquence mensuelle des articles sur sachachua.com\n(hors Emacs News)", fontsize=12, fontweight='bold')
plt.xlabel("Mois", fontsize=10)
plt.ylabel("Nombre d'articles publiés", fontsize=10)
plt.grid(True, linestyle='--', alpha=0.5)
plt.legend(loc='upper right')
plt.tight_layout()
plt.savefig('frequence.svg')
return df

	Mois	2022	2023	2024	2025	2026
1	Jan	6	19	20	23	16.0
2	Fév	0	3	0	10	8.0
3	Mar	0	5	1	24	15.0
4	Avr	0	2	1	14	22.0
5	Mai	0	1	1	9	15.0
6	Juin	0	3	1	9	13.0
7	Juil	1	0	0	6	9.0
8	Août	7	2	1	5	11.0
9	Sept	1	8	12	17	nan
10	Oct	2	12	29	11	nan
11	Nov	5	1	19	8	nan
12	Déc	4	15	6	6	nan

2026-08-30T08:43:07.159204 image/svg+xml Matplotlib v3.11.0, https://matplotlib.org/

et la croissance graduelle de mon vocabulaire français selon mon journal:

Bien qu'ils ne soient pas des graphes de connaissances classiques, ils m'aident à voir des tendances qui ne sont pas évidentes au jour le jour.

You can comment on Mastodon or e-mail me at sacha@sachachua.com.

Being a text editor (among other things), Emacs has quite a few tricks up its sleeve for making writing not just easier but also fun and seemingly magical. I call this section in my config “Wordcraft.”

Emacs Dictionary

When we need a dictionary, Emacs got us covered and then some. After version 28, Emacs connects to a dictionary as a two-step process by default:

1. It tries to connect to a local host.
2. If it fails, it next connects to an online dictionary at www.dict.org,

This workflow remains in place as long as dictionary-server is nil, which is the default. It’s a bit confusing (to me anyway), since “nil” might indicate that no dictionary is set up, but here it means we simply didn’t introduce any configuration to it.

The online version at dict.org contains the Webster dictionary from 1913¹, which (if you follow the footnote) will start sounding like an excellent resource. What I didn’t know up until now however is that dict.org contains more than just this wonderful dictionary.

When you search for something like “US” with Emacs’ built-in dictionary, it checks this database and gives you results from:

1. The Collaborative International Dictionary of English
2. WordNet
3. V.E.R.A. – Virtual Entity of Relevant Acronyms
4. The Free Online Dictionary of Computing (it has an entry as an ASCII character)

There are others, like the CIA Factbook and the Bible, among others. All of those are at your fingertips, inside Emacs, from a simple quick search².

The problem is that it’s an online dictionary. No internet, no dictionary. On my MacBook this can happen as I take it with me when I travel. Meanwhile, on Linux, I’m always online (desktop, wired connection).

Follow the footnote, and you will learn how to get that Webster dictionary (but just that, not the database at dict.org) working offline. As for me, I don’t want to set up an offline dictionary because macOS’s dictionary app³ (which works fine offline) is good enough — a quick copy-paste and I’m done. So I configured my dictionary-server to point directly to dict.org, so Emacs doesn’t even search for a local one first.

Here is the setting itself, including the localhost option as a reference and a reminder:

;; (set dictionary-server nil) default, search localhost and then dict.org
;; (setq dictionary-server "localhost") local only, no online search
  (setq dictionary-server "dict.org")

Hippie Expand

I learned about hippie-expand through Mastering Emacs. It’s one of those things that make Emacs magic. It uses different expansion functions (not to be confused with completion functions, which we will learn more about in a minute) to guess which word should come next in our text as we write, depending on which buffer we are in.

Following Mickey’s advice (linked above), I rebound this to M-/, which is bound to dabbrev-expand by default. It’s similar, but not as powerful (essentially it’s more basic; hippie-expand takes the functions that dabbrev-expand uses and builds on top of those with additional ones). Keep pressing M-/ to flip through suggestions.

The catch is that you need to open the buffers you want it to look through. For example, if I want it to pull words from my personal journal while writing this post, I need to have my journal buffer open somewhere. If you’re one of the people who don’t turn off Emacs often, this is not a problem — just keep that in mind when you use it.

Turning it on (by replacing the command, using the same binding):

(global-set-key [remap dabbrev-expand] 'hippie-expand)

We also want to change the order in which it searches for things so it works better for us. For me, as a person who does less coding and more writing, I prefer it to look at Lisp-related functions toward the end. The same logic applies to global (all-buffers) lists vs those that operate on the visible buffer only. So our first M-/ will give us suggestions from our current buffer, and as we keep pressing M-/ and exhaust those, it will search all the other buffers we have open. for other suggestions⁴.

(setq hippie-expand-try-functions-list
      '(try-expand-dabbrev
        try-expand-dabbrev-all-buffers
        try-expand-dabbrev-from-kill
        try-expand-line
        try-expand-line-all-buffers
        try-expand-list
        try-expand-list-all-buffers
        try-complete-file-name-partially
        try-complete-file-name
        try-expand-all-abbrevs
        try-complete-lisp-symbol-partially
        try-complete-lisp-symbol))

ispell

ispell is one of those things I set around the time I started using Emacs and never looked at again. I’ve made a mistake: I bound ispell-region to M-$. Those of you who use ispell often are probably perking an eyebrow: “huh? Why would you do that for? ispell does it by default!”

But somehow I didn’t know this. For years I highlighted whatever I needed to spell check, even single words. The default keybinding attributes M-$ to ispell-word, which checks the word at the marker, but if you have a region selected, it spellchecks the region. I should have given Emacs more credit; today I know better.

Another really handy thing I did not know about ispell is its ability to complete words I’m unsure of. But before we go on, please note that word completion (and completion functions) in Emacs is a big topic that I just spent a whole week on, and what I’m going to discuss here is just the tip of the iceberg.

First, the useful built-in completion built into ispell itself: l for lookup. Say you forgot how to write “psychiatry”. You type what you know — “psy” — and then call ispell, and as the suggestions show up, press l. ispell will ask you what to complete, along with a wildcard, so add * and then y so you have “psy*y”. ispell will show you what words start with psy and have whatever letters after but end with y. Useful!

Another thing I didn’t know: use R for query replace. This is good when you make the same mistake across several words. For example, when I wrote this post, I originally capitalized every ispell as Ispell. No problem. Stand on one of those, call ispell, press R to replace, and change it to ispell. Now you are prompted if you want to change all of them one by one, or, just hit ! and get it over with in one swoop.

With those quick tips, now back to completion functions.

Years ago, when I started using Emacs, I installed company with its minimal default settings and called it a day. It’s been working OK, and up until I started writing this post, I didn’t realize how much about Emacs completion-at-point functions (capf). Prot has a good video about this, which I’m still chewing through, but basically for ispell the magic happens when you stand on a word you don’t know how to finish and ask Emacs to suggest completions.

To understand how this works, Let’s say we don’t know if water is written as watter or watar, as a simple example.

1. We write “wate” and we ask Emacs to complete the word by calling completion with ispell with M-C i. Because the only word that exists (in English anyway) that starts with “wate” is water, Emacs will complete it for us to “water” automatically.
2. Now, while standing on the word “water,” we call completion again. Emacs informs us: complete, but not unique. In other words: the word water is real and complete (we have it spelled right) but there are other words that start with water.
3. While still standing on “water”, we call complete yet again. Emacs goes “OK. So you know it’s a word that exists, and you also know there are other words that start with water, so if you’re calling complete again, you probably want to see the other words that start with water.”

Bam, we have a buffer full of words that start with water, like waterboard or watermelon. We can select a word from this menu, even though it’s a bit weird — by going down or up with M-⇡ and M-⇣, then insert the word we want with M-Ret⁵.

This is nice, but usually you want to complete words that you already know, or kind of know. If I type “psych,” I don’t need a whole buffer of words if I’m looking for “psychology”; I just slowly add letters until I find what I need — and this is exactly what packages like company or corfu⁶ do.

Harper, languagetool and abbrevs

Let me just remind you of those for now and finish up this post. We will dig into those more next time.

This post is my participation in this month’s Emacs Carnival, on the theme of The Search for Knowledge.

About my current workflow

My way of handling notes and knowledge has evolved a lot over time. I’ve written about my note-taking journey in this blog post.
As of today, my knowledge management sauce is composed of Emacs and Vakana.mg. I’ve been using Logseq less and less over the past few months.

Indoor

In my day-to-day computer usage, I have the Emacs client open all day long with a scratch buffer ready for anything. I dump everything into the scratch buffer, remove or add paragraphs as needed and use vundo for time traveling. I use no structure except some dashes as separation between topics.
Whether it’s to capture fleeting insights or mold prompts for LLMs, the scratch buffer acts as a buffer between my mind and the computer (notes, prompts, etc.).
If something interesting is worth saving, then I save it. I use Denote for that.
If I’m not using my computer, I use pen and paper to capture thoughts and ideas, which I extract later on using a VLM if it’s worth saving. I talk about the process in this post.

Outdoor

For external capture I use Vakana.mg, my own offline mobile app. It solves the problem of taking photos, writing notes and commenting on them at the same time.
Very practical when I’m in the wild documenting plants. When I’m back home, I can export to an Org file from my phone and send it to my computer using LocalSend.

The Search for Knowledge

Retrieving

I don’t bother too much about retrieving. In Emacs, I either just open Denote or use project-find-regexp to reach whatever I want. Vakana.mg’s search also does fuzzy finding inside note contents.

On knowledge graphs

From what I’ve learned and in my own experience, retention of knowledge works better when the owner defines the visual representation of the information to retain, so it matches the way their mind works, and not the other way around (by letting the patterns emerge).
Putting direct intent into the graph’s shape makes the retention of the knowledge stronger. It’s the same mechanism as “charging an image” for better retention in the Memory Palace technique.
Vakana.mg’s visual design works better for me because it’s easier to traverse nodes in a linear way. And custom threads representing specific topics make for clean reading and understanding.

Emacs Packages for Knowledge Management

I like Hyperbole and org-roam but I don’t use them at all. I use Denote and plain org files. The simpler, the better for me. Even the information structure is very simple: one file = one topic. The length may vary.

Where do all my notes come from?

I don’t copy-paste much from other sources. Most of what I write comes from my brain. Either by digesting some books or through insights and observations.
The exceptions are pictures I take with my phone.

What’s next? What I wish to have

• Resurfacing random notes.
  I write more notes than I can review. A lot of notes are buried forever. In my spare time, I want to be able to go through my old collected notes. I added the feature in Vakana.mg. I don’t have the system in place yet in Emacs.

• Whiteboard inside Emacs.
  Artist mode is really good but it’s not that great for sharing because not everyone is a fan of ASCII art. Especially in a professional context. For that, I rely heavily on Excalidraw for diagrams. Now that we have the Emacs canvas, I really hope someone will soon build something similar to Excalidraw within Emacs.

A couple of days ago I wrote that smarter form targeting was coming to CIDER, and I ended that post by asking whether I’d got the resolution rules right and whether anything still surprised people. I got an answer. CIDER 2.1 will ship with the classic behaviour intact.

This is not a sad story, though. The detour turned up a bug that was quietly mangling people’s comments, and CIDER came out of it better than it went in.

What I was actually after

The targeting change wasn’t really about cursor positions. What I wanted was for every CIDER command that operates on a form to behave the same way, without adding yet another command to get there. CIDER has an enormous surface of evaluation commands, and every “at point” variant I could have added would have made that worse. If the existing commands simply resolved the form you meant, newcomers would have had fewer commands to learn, not more.

That was the bet: consistency by redefinition rather than by addition. In hindsight it was the wrong bet for a project this old. Fifteen years in, the existing behaviour isn’t an implementation detail I get to tidy up - it’s the contract. And as it turned out, the redefinition wasn’t nearly as transparent as I’d convinced myself it was.

The feedback

Several users, including CIDER’s co-maintainer Sashko Yakushev, voiced concerns and flagged issues I’d overlooked while playing with this initially. The most important one: inspection is just another flavour of evaluation, and people inspect bare symbols constantly. If it got the same treatment, the disruption would be real enough to run a fork over.

My instinct was that this was an edge case, so I measured it instead of arguing. Across every cursor position in a buffer, only three rules actually differ, and the flagship flow - type a form, hit C-x C-e - is identical under both. Two of those three were fine. The third was this one:

The cursor doesn’t move between those two evaluations. That’s the same position, twice, and the answers differ - "b" under the classic rules, "ab" under the new ones.

I’d filed “cursor on a closing paren” as an oddity nobody hits deliberately. But think about when you land there: you finish typing the last thing inside a form, and the cursor is now sitting on the ). For someone inspecting symbols all day, that fires constantly. And the classic answer isn’t arbitrary either - as Sashko put it, the rule of thumb is “whatever paredit-backward jumps back to”, which is a better description of the tradition than anything I’d written down.

Why the tradition exists in the first place

Here’s the part I under-weighted, and it’s worth spelling out for anyone who finds “the form before the cursor” arbitrary.

Emacs form navigation overwhelmingly leaves the cursor after a form. C-M-f (forward-sexp) moves over the next form and stops just past its closing delimiter. C-M-e (end-of-defun) leaves you after the whole top-level form. C-M-n (forward-list) does the same for the enclosing list. Paredit’s paredit-forward behaves the same way, and so does typing: finish a form and the cursor is, by definition, right after it.

So “evaluate the preceding form” isn’t a quirk - it composes with how you already move around. Navigate forward over a form, evaluate it. Type a form, evaluate it. The cursor is already in the right place, every time.

Getting onto a form instead takes deliberate effort: C-M-b (backward-sexp), C-M-a (beginning-of-defun), paredit-backward, or a jump package like avy. All perfectly good tools, but you have to reach for them - unless you’re clicking around with a mouse, in which case the cursor lands wherever you pointed and “the form before the cursor” genuinely is useless. Which, I suspect, is exactly the workflow difference behind this whole argument.

What CIDER got instead

The half of the idea that was never controversial is still there, as commands you opt into rather than a new meaning for keys you already use. Every operation now has an “at point” variant, not just eval and tap: cider-inspect-sexp-at-point, cider-pprint-eval-sexp-at-point, cider-macroexpand-1-at-point, cider-macroexpand-all-at-point, cider-format-edn-sexp-at-point, cider-insert-sexp-at-point-in-repl.

Three ways to say which form you mean, and now every command supports all of them:

The at-point commands fall back to the preceding form when there’s nothing to point at, so they’re drop-in replacements rather than a separate mode of working. Which means anyone who wanted smart targeting can simply have it:

(with-eval-after-load 'cider-mode
  (define-key cider-mode-map (kbd "C-x C-e") #'cider-eval-sexp-at-point)
  (define-key cider-mode-map (kbd "C-c C-e") #'cider-eval-sexp-at-point))

Two lines, no hidden mode, and everyone else’s fingers keep working. This is what I should have shipped in the first place, and it’s what the manual now recommends. Yes, it’s more commands than I wanted. It’s also the version that doesn’t break anyone.

Macroexpansion is the one place a bit of cleverness survived on its own merits, because an expansion needs a call form. Stand on a bare symbol and cider-macroexpand-1-at-point widens to the call around it, since expanding a lone symbol is never what anyone meant.

The bug at the bottom of the hole

While unifying the plumbing I found this, which is much worse than anything form targeting was ever guilty of. Put the cursor at the end of a comment:

(defn foo [])
;; a comment|

CIDER answered comment. Not the (comment ...) form - the word, lifted out of your prose, because sexp motion has no notion of comments once the cursor is inside one and happily reads the words as symbols.

For evaluation that produced a puzzling error. For the in-place macroexpansion commands, which replace the region they resolved, it did this:

;; a comment          ->   ;; a EXPANDED<comment>
(+ 1 2) ; hey         ->   (+ 1 2)          ; EXPANDED<hey>

It rewrote the comment. That bug has been in CIDER for years, and I only found it because I went looking at the primitives while cleaning up after myself.

Then I checked the neighbours, and this is my favourite part of the whole episode: SLIME, SLY and Emacs Lisp itself all still do this. Both Lisp environments use a bare backward-sexp, and if you put the cursor after (+ 1 2) ; hey in any Emacs Lisp buffer and ask for the preceding sexp, you get hey. CIDER now steps out of the comment first, which as far as I can tell makes it the only one of the family that gets this right.¹

One idea worth stealing

The same survey turned up something CIDER was missing. SLY briefly flashes the region it compiled, so you see what it acted on. That’s a direct answer to the confusion this whole saga was about - “which form did it just take?” - and it changes nothing about what gets taken.

(setq cider-flash-evaluated-region t)

Off by default, because I’ve learned my lesson about switching things on for everyone. But if the targeting rules ever puzzle you, turn it on for a day.

The moral

In the original post I described cider-form-targeting, the escape hatch back to the classic rules, as “living on borrowed time” - clutter left over from a plan I’d since reversed, which I was itching to delete.

That option is the only reason the conversation stayed a conversation. Its existence made the objection “please don’t remove the fallback” rather than “I’m forking CIDER”, and I very nearly removed it before anyone had tried the change.

Every mistake is a learning experience for me, and this one was cheap: nothing had shipped, so the whole thing cost a few days and some rewriting. The testing and feedback cycle worked exactly as it should have - people tried something on master, told me plainly what was wrong with it, and the result is better than either what I proposed or what we had before. Everyone gets the behaviour they want, and CIDER lost a text-eating bug on the way.

Thanks to everyone who took the time to tell me I was wrong.

That’s all I have for you today. Keep hacking!

Raw link: https://www.youtube.com/watch?v=8V4ZyEL_i-s

The built-in completion-preview-mode lets us expand what we type in a minimalist, distraction-free way. It can also be combined with the default Completions buffer to show all the available options. The Completions buffer has several nice features, starting with Emacs 31, which make this an excellent combination that does not require any third party packages (though packages can still augment the overall experience). I also mention the Emacs 31 ‘newcomers-presets’ theme, which configures some of these options as well: it is a great way to start your Emacs configuration.

Sample configuration

(use-package completion-preview
  :ensure nil
  :demand t
  :bind
  ( :map completion-preview-active-mode-map
    ("M-i" . completion-preview-insert-word)
    ("M-n" . completion-preview-next-candidate)
    ("M-p" . completion-preview-prev-candidate)
    ("M-<return>" . completion-preview-insert)
    ;; With TAB we effectively defer to the *Completions* buffer to
    ;; show more completion candidates at once.
    ("<tab>" . completion-preview-complete))
  :config
  (setq completion-preview-minimum-symbol-length 2)
  (with-eval-after-load 'org
    (add-to-list 'completion-preview-commands #'org-self-insert-command))
  (global-completion-preview-mode 1))

;; I have a more detailed configuration (and explanation) that works
;; with Emacs 31 built-in completion capabilities:
;; https://protesilaos.com/codelog/2026-07-29-emacs-default-minibuffer-completion-overview/.
(use-package minibuffer
  :ensure nil
  :demand t
  :bind
  ( :map completion-in-region-mode-map
    ("M-i" . minibuffer-choose-completion)
    ("M-n" . minibuffer-next-completion)
    ("M-p" . minibuffer-previous-completion))
  :config
  (setq completions-format 'one-column)
  (setq completions-max-height 12)
  (setq completion-auto-help t)
  (setq completion-auto-select nil)
  (setq minibuffer-visible-completions t)
  (setq completion-eager-update t))

Finally, the newcomers-presets theme is an excellent way to start your configuration. It is available as part of Emacs 31. Put this at the top of your init.el:

(load-theme 'newcomers-presets)

As an Emacs configuration grows, startup time can gradually increase. Measuring that increase accurately makes it easier to identify regressions. The majority of Emacs users use emacs-init-time. However, this built-in function does not measure all the work performed during startup.

Emacs startup proceeds through several stages: it loads the early init and regular init files, processes command-line options, sets after-init-time, runs emacs-startup-hook, performs additional initial-frame setup such as applying frame parameters from the configuration, and then runs window-setup-hook after the initial frame parameters have been configured. This makes window-setup-hook a useful place to record a broader startup-time measurement.

For a more accurate startup-time measurement, add the following Emacs Lisp code to early-init.el or init.el:

;; Emacs startup proceeds through several stages: it loads the early init and
;; regular init files, processes command-line options, sets after-init-time,
;; runs emacs-startup-hook, performs additional initial-frame setup such as
;; applying frame parameters from the configuration, and then runs
;; window-setup-hook after the initial frame parameters have been configured.
;; This makes window-setup-hook a useful place to record a broader startup-time
;; measurement.
;;
;; URL: https://www.jamescherti.com/measuring-emacs-startup-time/
(defvar my-recorded-startup-time-message nil
  "Stores the formatted string of the Emacs startup metrics.")

(defun my-record-startup-time ()
  "Calculate and record the elapsed startup time.
This function records the time when `window-setup-hook' runs."
  (setq my-recorded-startup-time-message
        (format "Emacs loaded in %.2f seconds (Init time: %.2fs) with %d garbage collections."
                (float-time (time-since before-init-time))
                (float-time (time-subtract after-init-time before-init-time))
                gcs-done))
  ;; Output to the *Messages* buffer during the initial launch
  (message "%s" my-recorded-startup-time-message))

(defun my-display-startup-time ()
  "Display the previously recorded Emacs startup time in the echo area."
  (interactive)
  (if my-recorded-startup-time-message
      (message "%s" my-recorded-startup-time-message)
    (message "Startup time was not recorded.")))

;; Read startup summary:
;; https://www.gnu.org/software/emacs/manual/html_node/elisp/Startup-Summary.html
(add-hook 'window-setup-hook #'my-record-startup-time 99)

This provides a broader measurement than M-x emacs-init-time because it continues measuring after after-init-time has been set, including subsequent startup processing through window-setup-hook.

A depth of 99 places the function near the end of window-setup-hook. This makes the measurement less likely to omit work performed by other functions on the same hook.

The variable gcs-done tracks the total number of garbage collections during the session. Because this function formats and saves the message string during window-setup-hook, it locks in the exact number of garbage collections triggered during the startup phase, giving you a metric of memory allocation bottlenecks during initialization. Ideally, it should be 0 or 1.

Capturing the time the UI finishes rendering provides a reliable metric to track down performance regressions. Once Emacs has finished loading, you can retrieve the recorded startup time at any point during your session. Execute M-x my-display-startup-time to print the exact initialization metrics in the echo area. This interactive command ensures the startup data remains accessible even if the initial message is cleared from the screen by subsequent buffer activity.

I am not going to share my Emacs configuration, but the way I keep it organized. I do not think I am discovering anything new, but it might be useful for someone who is starting to organize their configuration and does not know where to begin.

I do not use any framework (neither Doom nor Spacemacs) nor the literate approach of Org mode. Everything is vanilla Emacs and each file is an area of responsibility, while init.el acts as the index.

Why vanilla and not a framework? Frameworks decide for you. They lend you a huge configuration that you do not understand and that is hard to tweak. For me, the literate approach of Org is one more layer where something can break. I prefer the simplicity of the file I edit being the file that runs. The less magic, the fewer things that break.

So, inside my configuration folder (~/.emacs.d/), I have the following files:

• "init.el": the index of my configuration. It loads the rest of the files in order.
• "core.el": base Emacs behavior, such as handling backups, paths, clipboard, etc.
• "functions.el": my personal scripts and macros.
• "packages.el": repository configuration, such as MELPA (among others).
• "ui.el": everything related to visual aspects: theme, modeline, typography, visual behavior, etc.
• "ide.el": LSP, debugger, linters and programming configurations.
• "plugins/init.el": third-party packages, each with its own configuration.

An example of a block you might find inside plugins/init.el:

;; ===
;; vterm-editor
;; Compose text in a full Emacs buffer and send it to vterm with a single keystroke.
;; Docs: https://git.andros.dev/andros/vterm-editor.el
;; ===
(use-package vterm-editor
  :ensure t
  :vc (:url "https://git.andros.dev/andros/vterm-editor.el")
  :after vterm
  :bind (:map vterm-mode-map
         ("C-c e" . vterm-editor-open)))

Each element is isolated in its own context. Using use-package lets me have an isolated and organized configuration block for each package.

I also have other satellite files for third-party packages, such as "plugins/feeds.el" for my RSS subscriptions, "plugins/erc.el" for IRC, "plugins/mu4e-config.el" for email, "plugins/gnus.el", etc. When they grow large and specific, I split them into individual files.

And why break it into areas instead of a single giant init.el? Because I want to know where to look without stopping to think. The brain appreciates each thing having its place, especially when you come back to it after months. Besides, each file is a piece I understand fully, because I wrote it myself. Over time your configuration stops being an editor and becomes a workstation tailored to you. It is my interface with the machine, and it should be as finely tuned as possible.

I am not saying this is the best way, but it makes it easy for me to know where to look and where to put things. Simplicity is also a feature.

Help me keep writing Every coffee gives me a push toward the next article. Sure, it's on me!

Send an email to comment+article-dc7db35a@andros.dev to leave a comment. The subject will be ignored.

I saw an amusing Reddit post recently with an Emacs user thinking about declaring “Emacs bankruptcy” with a config file falling in the 800-900 line range.

Many users in the replies were happy to point out that even 10-12K lines is nothing if you understand what’s going on, and it’s well-documented.

This reminded me of something I’ve been experimenting with lately. Instead of updating my config, I’m trying out directory-local variables per project.

Having local configurations in a project avoids the extra cogitation of worrying about conflicts with other file types or projects down the line. I like this. Also makes settings easier to transfer to a similar project in the future.

The post Don’t go bankrupt, go local appeared first on Chris Maiorana.

Eglot provides built-in LSP support in modern Emacs, giving developers a native interface for autocompletion, linting, and formatting. When paired with python-lsp-server (pylsp), creating a Python development environment comes down to managing the LSP server configuration properly.

Historically, setting up this toolchain required wiring together a stack of individual utilities such as flake8 and isort. Now, ruff stands entirely apart from that legacy ecosystem by consolidating all of those separate checks into a single, high-performance Rust binary. This article demonstrates how to configure Eglot to detect and use Ruff dynamically when it is present on your system, while retaining a clean fallback to the older stack of tools like Flake8, pycodestyle, and pydocstyle when Ruff is missing.

The configuration strategy

The configuration provided in this article begins by checking for the presence of ruff and flake8 in your system path. Based on these checks:

1. If Ruff is installed, the configuration relies on the python-lsp-ruff plugin. Ruff consolidates linting, formatting, and import sorting.
2. If Ruff is missing but Flake8 is present, Flake8 takes over linting duties alongside Pylint.
3. If neither is installed, the system falls back to the individual pylsp plugins (pyflakes, pycodestyle, mccabe, etc.).

Dependencies

• Core: python-lsp-server.
• Primary: ruff, python-lsp-ruff, and pylint.
• Fallback: flake8, flake8-docstrings (Integration of pydocstyle and flake8), isort, and python-lsp-isort.

The dependencies can be installed locally pip or directly via your system's package manager.

The complete configuration

Below is the complete Emacs Lisp code to achieve this dynamic configuration. You can place this snippet in one of your init files:

;; Use ruff when it is available because it is fast (written in Rust). When ruff
;; is not available, fall back to flake8 and its individual underlying tools.
;;
;; URL: https://www.jamescherti.com/emacs-python-dev-using-eglot-pylsp-ruff-pylint-flake8/
;;
;; To sup up:
;; - When ruff is available: Ruff, and Pylint.
;; - When Ruff is not available: Flake8, isort, and Pylint.
;;
;; Documentation:
;; https://github.com/python-lsp/python-lsp-server/blob/develop/CONFIGURATION.md
;; https://github.com/python-lsp/python-lsp-ruff
;; https://github.com/chantera/python-lsp-isort
(with-eval-after-load 'eglot
  (let* ((has-ruff (executable-find "ruff"))
         (has-flake8 (executable-find "flake8")))
    ;; Target ONLY the 'pylsp key in the global configuration alist safely
    (setf (alist-get 'pylsp (default-value 'eglot-workspace-configuration))
          `(:pylsp
            (:plugins
             (;; Plugin: https://github.com/python-lsp/python-lsp-ruff
              :ruff (;; Ruff configuration
                     :enabled ,(if has-ruff t :json-false)

                     :formatEnabled ,(if has-ruff t :json-false)

                     ;; Add 'W' (pycodestyle warnings), 'UP' (pyupgrade),
                     ;; and 'D' (pydocstyle).
                     :extendSelect ["W" "UP" "D"]

                     ;; Ignore specific rules
                     ;;   D213: Multi-line docstring summary should start on
                     ;;         the second line.
                     ;;   D202: No blank lines allowed after function
                     ;;         docstring.
                     ;; :ignore ["D213" "D202"]
                     )

              ;; Pylint remains enabled regardless of whether Ruff
              ;; or Flake8 is active because it serves
              ;; complementary role.
              :pylint (:enabled t)

              ;; Flake8 is a wrapper tool that bundles pyflakes,
              ;; pycodestyle, and mccabe.
              :flake8 (:enabled ,(if (and (not has-ruff) has-flake8)
                                     t
                                   :json-false))

              ;; When Flake8 or Ruff runs, they execute these under
              ;; the hood. If we enable either, we must explicitly
              ;; disable the individual pylsp plugins for them,
              ;; otherwise the language server will run the exact
              ;; same checks twice and duplicate all editor
              ;; diagnostics.
              :mccabe (:enabled ,(if (or has-ruff has-flake8)
                                     :json-false
                                   t))
              :pyflakes (;; pyflakes catches logical errors
                         ;; (unused imports, undefined names...)
                         :enabled ,(if (or has-ruff has-flake8)
                                       :json-false
                                     t))

              :pycodestyle (;; pycodestyle catches style/formatting
                            ;; violations (PEP 8)
                            :enabled ,(if (or has-ruff has-flake8)
                                          :json-false
                                        t)

                            ;; Ignore specific rules
                            ;; :ignore ["W293"]
                            )

              :pydocstyle (;; pydocstyle enforces PEP 257 docstring
                           ;; conventions
                           :enabled ,(if (or has-ruff has-flake8)
                                         ;; Use flake8-docstrings
                                         ;; https://github.com/pycqa/flake8-docstrings
                                         :json-false
                                       t)

                           ;; Ignore specific rules
                           ;;   D213 Multi-line docstring summary should start on
                           ;;        the second line.
                           ;;   D202 No blank lines allowed after function
                           ;;        docstring.
                           ;; :ignore ["D213" "D202"]
                           )

              ;; Formatting: isort
              ;; https://github.com/chantera/python-lsp-isort
              :isort (:enabled ,(if has-ruff :json-false t))

              ;; Formatting: autopep8
              :autopep8 (:enabled ,(if has-ruff :json-false t))
              :yapf (:enabled :json-false)

              ;; Code completion
              :jedi_completion (;; jedi configuration
                                :enabled t

                                ;; Disable resolving documentation details eagerly
                                ;; :eager t

                                ;; Add class objects as a separate completion item
                                ;; :include_class_objects t

                                ;; Add function objects as a separate completion item
                                ;; :include_function_objects t

                                ;; Auto-complete methods and classes for each parameter
                                ;; :include_params t

                                ;; Fuzzy matching for typos/abbreviations
                                ;; :fuzzy t

                                ;; Modules for which labels and snippets should be cached.
                                ;; :cache_for ["pandas", "numpy", "tensorflow", "matplotlib"]

                                ;; How many labels and snippets should be resolved?
                                ;; :resolve_at_most 25
                                )))))))

This Eglot configuration prioritizes Ruff to handle linting and formatting when it is available in the environment. If Ruff is missing, it falls back to Flake8 and the default pylsp plugins. This keeps Emacs Eglot adaptable across different machines, guaranteeing consistent diagnostics and autocompletion without demanding a strict set of dependencies on every system you use.

For me, one of the most difficult Emacs behaviors—or at least “normal” Emacs behaviors—to understand is scrolling. The default behavior is so unintuitive and jarring that it kept me from embracing Emacs for a long time. It was only after I took the plunge that I discovered that that behavior, like everything else in Emacs, is configurable.

That was almost 20 years ago when I was just starting and knew next to nothing about Emacs configuration but I was able find the solution on the Internet. Here’s what I’ve had in my init.el almost from the beginning:

(setq    ;set reasonable scrolling
 scroll-margin 0
 scroll-conservatively 100000
 scroll-preserve-screen-position 1)

Back then, I had no idea what any of it meant, only that it made Emacs scrolling rational by my standards. It’s been sitting there undisturbed ever since.

Now James Cherti has a really excellent post that expains all the fine points of configuring scrolling. He explains the above lines, which most people probably have in their configuration. If you want Emacs scrolling to behave as it does in every other application, you can leave them as is but you can tweak the behavior a bit if you like. Cherti has all the details.

But wait. There’s more. There are similar settings for horizontal scrolling that you might like. I’ve never had any problem with horizontal scrolling—probably because I’ve always wrapped lines in one way or another—but they’re there if you need them.

There are some other tweaks that you can apply to delay fontification during scrolling to speed things up a bit. Again, this is not something that I use but if you deal with large files, you may find it useful.

In Emacs 29 and later you can set pixel-precise scrolling to make scrolling over images more pleasant. There are a few other tweaks in Cherti’s post so you should definitely take a look at it. There’s a lot of good content and even if you use only a bit of it, you will find his post worthwhile.

This is now fixed: GCC drive error on macOS: This seems to show up with almost every new Emacs package I’ve been trying recently on my Mac. I remember trying to dig into it, and I went in circles trying to install something from Homebrew. Has anyone fixed this? I’m on GNU Emacs plus 30.2.

Intro

So, Emacs 31 has been released, and a lot of shiny new stuff is there, ready for us to play with.

You probably heard of this new markdown-ts-mode and decided to check it out. And guess what? On Emacs version 31, this is marked as an experimental mode. What does this mean? Should you use it or not? Is this ready? Is this just a sketch of a mode?

Treat this post as a quick guide to getting this mode up and running and helping yourself find answers to these questions.

Where is it in terms of features?

This is an experimental mode, right? You need to opt in, so probably not everything will work flawlessly yet, and it needs more testing and feedback.

That said, don't let this title mislead you. This does not mean the mode is premature in terms of features. As you will see, this is a very feature-rich mode. This mode already covers all of the https://commonmark.org/ spec, as well as most of https://github.github.com/gfm/, with some extras like code blocks even for non-ts-modes, like elisp, table of contents utilities, and interfaces with external converters, such as pandoc and gfm.

Before deep diving into it yourself, you may need some help simply turning this mode on. Tree-sitter is tricky. It might even be your first time with tree-sitter, so a quick "install guide" is on our agenda.

Where is it? Do I need to install the mode?

Experimental means Emacs does not enable the mode by default so it is not there waiting for you to simply open a .md file or call it with M-x markdown-ts-mode RET. You need to load this library.

As always on Emacs, there's more than one way of doing everything, I am a big fan of use-package so I tend to use it to organize my init file. Here is my suggested initial setup:

(use-package markdown-ts-mode
  :ensure nil
  :mode ("\\.md\\'" "\\.mdx\\'" "\\.markdown\\'")
  :config
  (require 'markdown-ts-mode-x))

Or if you keep use-package out of your tool belt:

(autoload 'markdown-ts-mode "markdown-ts-mode" nil t)

(dolist (re '("\\.md\\'" "\\.mdx\\'" "\\.markdown\\'"))
  (add-to-list 'auto-mode-alist (cons re 'markdown-ts-mode)))

(with-eval-after-load 'markdown-ts-mode
  (require 'markdown-ts-mode-x))

Now both the mode and the x (nice extra goodies) libraries are loaded, and you can simply visit your Markdown files using it.

If you want to experiment with it without touching your own configuration, do the following:

1. Save the above content in a file like testing.el.
2. Call emacs with emacs -Q --load 'testing.el'.

And there you have it, a bare Emacs session with your testing ground set up. This is what I will use for the rest of this guide.

IMPORTANT: there's NO NEED to download or add this package to your package manager. The (now very old and archived) MELPA Repository will refuse to install on Emacs version 31 onward and is very, very poor in terms of features. If you are using this, you're not using the new built-in markdown-ts-mode. Right? Let's continue.

Opening our first markdown file

In order for you to "see what I see", we need some pictures. If it is the first time you're using a tree-sitter-based mode, let me warn you: although tree-sitter is wonderful, fast, and feature-rich, it comes with its own set of tasks to complete and perhaps debugging skills if it needs help. I will try to cover some here; I will forget others for sure.

For this guide, I will be using this test file.

The repository where it is hosted is our laboratory. No code lives there, remember, all code is in Emacs itself.

Now go ahead and open the test.md file.

IMPORTANT: At this point, many things can happen. If you have the grammar for markdown installed in your system, the file is already opened. You could, though, be prompted, as I am here, with this:

It means Emacs hasn't found a grammar for markdown in my system, in this case in ~/.emacs.d/tree-sitter/ (which is the default when I start Emacs with emacs -Q ...). Emacs will offer to install it, which means downloading and compiling it from a repository already defined in markdown-ts-mode's source code. Let's install it with y. Emacs will clone the grammar repository, compile it, and continue to the second grammar. Yes, markdown uses two grammars: the main one and one for inline parsing. I will allow Emacs to install the second one with y.

Success!

What you should be seeing:

If not, here is what you should check if something went wrong:

1. Is Emacs compiled with the tree-sitter flag? Use M-: (featurep 'treesit) RET and check if it returns t.

2. Do you have the tooling used for "compiling" grammars, like make, gcc, and others?

3. Tree-sitter needs a package in your distro, usually named tree-sitter-cli which provides a tree-sitter binary, you can check you have it with tree-sitter --version.

This is a common headache for all tree-sitter modes. Many people like NOT to compile their own grammars, but instead use some compiled file from a place they trust, like their own distro repository, or packages with hundreds of pre-compiled grammars. I will not dive into it; there are many ways of acquiring grammars, and I will stick with "build it yourself" for this guide.

See, I kind of tricked you there. I told you that you should be seeing that, but actually, the "do you see what I see" should look like this:

We provide the full file in here, with several default themes so you can compare whether your setup is complete.

So, what happened?

This is part of the reason markdown-ts-mode is very special.

This mode can work not only with markdown, but with all other -ts-modes available! Keep this in mind; we will talk about code blocks in a while. For now, we need to understand a few things.

In your test.md file, we have a special header. It is very common to have toml or yaml as headers of markdown files.

This little guy here:

---
title: The Official 'markdown-ts-mode.el' Feature Test File
author: Rahul Martim Juliato
date: 2026-03-18
version: 0.1.0
parsers needed: markdown, markdown-inline, yaml, toml, html, c, javascript, python, ruby, rust
---

Needs something else to fontify (aka be painted with colors by Emacs). Can you figure out what is missing? If your answer is "we need a grammar for YAML!", kudos!

Whenever something does not fontify correctly in -ts-modes, you're probably missing a grammar. And as markdown-ts-mode is made to work with all available ts-modes, this is no exception.

Let's install our yaml grammar with our trusty M-x treesit-install-language-grammar RET yaml.

You might see now what I am seeing:

Let's agree to it with y. Hmm, it looks like this time, something went wrong with yaml-ts-mode trying to register its preferred grammar with treesit-install, as there are no suggestions. We could provide it manually. But let's check something first. Taking a look at yaml-ts-mode.el, we can check which grammar it expects in its source code:

;; from yaml-ts-mode.el
(add-to-list
 'treesit-language-source-alist
 '(yaml "https://github.com/tree-sitter-grammars/tree-sitter-yaml"
		:commit "b733d3f5f5005890f324333dd57e1f0badec5c87")
 t)

Awesome! Let's simply evaluate that block and try to install the grammar again. Or manually provide the source https://github.com/tree-sitter-grammars/tree-sitter-yaml to our already-started interactive session, as I did this time:

We then keep going with the defaults with RET RET RET... until the library is installed.

After that, reload markdown-ts-mode, or use C-x x g, or re-open the file you're visiting.

What we did here by visiting the source code is pretty rare, and most -ts-modes will automatically suggest the repository from which they are going to compile. It was nice that this happened, so I can show you what to do.

Now what? We need to do the same M-x treesit-install-language-grammar for every block without fontification that we encounter. If you'd like, for our test file we could use C-x x f to force fontification and be prompted for every missing grammar used by this file.

By now, you should see the entire document fontified as in here. Same as previous image:

A note on grammars

A -ts-mode is only as good as the tree-sitter grammar behind it. This means every -ts-mode needs to constantly keep up with improvements to the grammar, which is shared by any editor or program wanting to use tree-sitter to parse the language.

This also means we are, at some point, dependent on the grammar for certain constraints and features. Almost all -ts-mode code in Emacs is filled with notes on limitations and the reasoning behind why and how something obscure is treated the way it is.

Emacs mode authors and maintainers always try to suggest the grammar and the SHA commit the ts-mode is prepared to use, either in comments or in the code inside the mode, which is the same as you saw for the yaml suggestion. Part of maintaining ts-modes is keeping up with newer grammar version changes. We try our best to keep it updated with the latest versions, but the one we tested against and that should work as expected is the one in the source file of the mode.

This is why I think compiling it yourself interactively with Emacs is the best possible way to guarantee a nice experience.

Specifically for markdown-ts-mode, we're using the grammars provided by https://github.com/tree-sitter-grammars/tree-sitter-markdown, as this is the most complete, maintained, and broadly adopted one, both by code editors and programs in general. This doesn't mean it is free of bugs or limitations. Again, we do our best to work around these limitations and even contribute issues to the grammar and to the core tree-sitter library.

I can finally open a markdown file!

Congrats! Now what? How often do I need to do all of this? Only once, the first time you use a -ts-mode, or never if you already have grammars installed by some other method.

Now let's see what markdown-ts-mode already provides.

A quick look at markdown-ts-mode features

We (BTW, this mode is authored by me and Stéphane Marks) provided an easy-menu feature for quick discoverability of functionalities.

You can access it by clicking on Markdown in the mode-line, or, if you have menu-bar-mode enabled, on the menu bar, or even Ctrl + Right click (whatever Emacs maps your OS input to) on a buffer using markdown-ts-mode.

This is actually this guide's TL;DR, if you want to stop now and explore it yourself (spoilers ahead).

Editing

The fastest way to learn the mode is to type a little of everything. Below is a speed run: what you write, what key does it for you.

Marks (emphasis)

Markdown is plain text, so you can always type the markers yourself:

Or let the mode do it: C-c C-x C-f (markdown-ts-emphasize) then a single key:

• b bold, B bold with underscores
• i italic, I italic with underscores
• a bold + italic
• s strikethrough
• c inline code
• SPC remove emphasis at point

If a region is active, the formatting wraps the region. With no region, it wraps the word at point, or inserts the pair and drops point in the middle.

Tip: C-c C-x RET (markdown-ts-toggle-hide-markup) hides the markers themselves, so **bold** shows as bold. Very nice for reading while editing, like default org-mode.

Another tip: M-q fills correctly even inside lists and quotes.

Headings

Type them: #, ##, ... up to ######. Setext headings (=== and --- underlines) are recognized, too.

Promote and demote without retyping the hashes:

• M-<left> promote (markdown-ts-promote)
• M-<right> demote (markdown-ts-demote)

And move a whole section, body and children included:

• M-<up> (markdown-ts-move-subtree-up)
• M-<down> (markdown-ts-move-subtree-down)

TAB on a heading cycles its visibility (outline folding). The mode is an outline-minor-mode citizen, so folding just works. S-TAB on a heading will cycle the visibility of all headings.

IMPORTANT: By now, you can see this mode tries, when possible, to draw parallels with org-mode, so Emacs users used to it can have fewer problems adapting to markdown. If these bindings don't suit you, everything can be customized.

Listings (lists and checkboxes)

Type - item, + item, * item or 1. item.

• M-RET new list item (markdown-ts-insert-list-item)
• RET is smart: markdown-ts-newline continues the list for you
• M-<left> / M-<right> promote/demote the item
• C-c C-r renumber an ordered list (markdown-ts-renumber-list)
• C-c C-c toggle a task checkbox (markdown-ts-toggle-checkbox)
• M-q fills correctly inside an item

Task lists are the GFM ones:

- [ ] not done
- [x] done

Raw mode:

With markup hidden:

Note the bullets and boxes you see if you toggled C-c C-x RET are display only. The buffer still holds - and [x]. See markdown-ts-unordered-list-marker, markdown-ts-checked-checkbox and markdown-ts-unchecked-checkbox.

Blocks

C-c C-, (markdown-ts-insert-structure) then one key:

• ` fenced code block, prompts for the language
• ~ tilde fenced code block
• q block quote
• d divider (thematic break)
• t table

If a region is active, it wraps the region instead of inserting an empty block.

With markup hidden:

Code blocks

This is the party trick. A fenced block tagged with a language is fontified by that language's own mode:

```python
def hello():
	return "world"
```

Missing colors typically means a missing grammar, same story as the yaml header earlier.

Better than colors: put point inside the block and you are in markdown-ts-code-block-in-context-mode (lighter [code] in the mode-line). Inside it:

• TAB indents like the language does
• RET newline and indent like the language does
• M-q fills like the language does
• M-. jumps to definition via xref

Move to the next/previous blocks with C-c C-v n and C-c C-v p.

Non tree-sitter modes work too, elisp included. Knobs: markdown-ts-code-block-modes, markdown-ts-default-code-block-mode, markdown-ts-fontify-code-blocks-natively.

An example raw:

With markup hidden:

Tables

Insert one with C-c C-, t or M-x markdown-ts-table-insert-table, which asks you to specify the number of rows and columns to insert.

| Column 1 | Column 2 |
|----------|:---------|
| a        |        1 |

Inside a table you are in markdown-ts-in-table-mode (lighter [table]) and the keys change:

• TAB / S-TAB next / previous cell (also formats your table)
• RET / S-RET next / previous row
• M-RET insert row below
• M-<up> / M-<down> move row
• M-<left> / M-<right> move column
• M-S-<up> insert row above, M-S-<down> delete row
• M-S-<right> insert column left, M-S-<left> delete column
• C-c C-c align the whole table
• C-c C-t a set column alignment (left, center, right)
• C-c C-t t transpose the table

Plus, from the menu: clone rows and columns, CSV/TSV import of a region and CSV/TSV export of the table.

NOTE: There are some limitations when working with tables at the moment, mostly due to how the grammar parses them, so you may bump into unfontified stuff while typing. All valid tables according to the GFM spec should be good to use, though.

Links and images

Links are the usual [text](url) and [text][ref]. Fragment links like [intro](#intro) are clickable and jump to the heading in the buffer, using GitHub style slugs by default.

Images render inline. C-c C-x C-v toggles them (markdown-ts-toggle-inline-images). See markdown-ts-image-max-width and markdown-ts-display-remote-inline-images for how big and whether remote URLs are fetched.

Markdown:

After C-c C-x C-v:

After C-c C-x RET:

Moving around

• TAB cycle folding at point
• C-c C-n / C-c C-p next / previous heading
• C-c C-u up to parent heading
• C-c C-f / C-c C-b next / previous heading, same level
• M-x imenu jump to any heading or named code block by completion
• C-c C-v n / C-c C-v p next / previous code block

markdown-ts-default-folding decides how a file opens: everything shown, or folded.

markdown-ts-view-mode

M-x markdown-ts-view-mode read-only mode with a single key navigation: n, p, u, f, b, TAB. Good for reading a README without fear of typing into it.

Extras

Everything below lives in markdown-ts-mode-x.el, which is why we loaded it back in the setup.

TOC

A table of contents is delimited by HTML comments, so it survives rendering anywhere:

<!-- markdown-ts-toc: -->
<!-- markdown-ts-toc-end: -->

• M-x markdown-ts-toc-insert-template inserts those markers, basic or complete (the complete one lists every parameter with its default)
• M-x markdown-ts-toc-generate fills them in, and refills on every call
• M-x markdown-ts-toc-clear empties, markdown-ts-toc-clear-and-remove also removes the markers
• M-x markdown-ts-toc-update-before-save-mode regenerates on save

Parameters go inline in the opening comment: min-depth, max-depth, candidates, from, style, indent, no-link, relative-depth, ignore. A buffer can hold more than one table with different parameters. Candidates are not only headings, list items, setext headers and named code blocks can feed a table too.

Raw:

With markup hidden:

Exporting

M-x markdown-ts-convert converts the buffer, markdown-ts-convert-file a file. You get asked for the format and the converter, unless you set markdown-ts-default-converter. Supported out of the box:

• PDF via pandoc
• HTML via pandoc, cmark, cmark-gfm, markdown, markdown.pl

With a prefix argument the result is displayed, by default with eww. See markdown-ts-convert-display-function to open in a browser instead. That is your somewhat 'live' preview. Converting is not (yet) automatically when you make changes, maybe in the future.

Example using eww, split manually made for this demo:

Spec at hand

M-x markdown-ts-browse-commonmark-spec and M-x markdown-ts-browse-gfm-spec open the specs, for when you need to settle an argument.

Experiment with eglot and eldoc

This is still experimental within the experimental, so don't blame eglot's author if something goes wrong. Send a bug report to markdown-ts-mode instead.

If you set this:

(setopt eglot-documentation-renderer #'markdown-ts-view-mode)

Eglot will try to render documentation (usually Markdown provided by the LSP server) using markdown-ts-mode.

Again, we are still shaving off some rough edges here, and results may vary. Please do help us test this, though.

Play with options

M-x customize-group RET markdown-ts RET and go through it. Some of the customs worth a look at first:

• markdown-ts for display: markup hiding, ellipsis, bullets, checkboxes, thematic break and hard line break characters, inline images, folding on open
• code blocks: markdown-ts-code-block-modes, markdown-ts-default-code-block-mode, markdown-ts-enable-code-block-context-mode
• tables: markdown-ts-enable-table-mode, markdown-ts-table-auto-align, markdown-ts-table-default-column-width
• markdown-ts-convert for exporting
• markdown-ts-toc for tables of contents

Faces are customizable too, one per Markdown element.

How you can help

The best way you can help is simply by using it. Try it with your Markdown files, play with the different features, and see what needs improvement or what breaks.

If you find something that doesn't work as expected, please report it as a bug from Emacs itself with M-x report-emacs-bug RET. Include a small example that reproduces the problem whenever possible. This is especially useful for issues involving fontification, tree-sitter grammars, tables, code blocks, or interactions with other modes.

We're still polishing the rough edges, so bug reports, feedback, and real-world testing are very welcome.

I found a bug, is it because markdown-ts-mode is buggy?

Some of the surprises you may hit while using markdown-ts-mode might be the mode, some might be the grammar, some might come from how tree-sitter is integrated into Emacs, or from the tree-sitter ecosystem as a whole. Knowing about this upfront helps understanding that debugging is challenging.

Grammars are a shared, external asset

A grammar is not written for Emacs. The very same tree-sitter-markdown is consumed by other editors and tools, so any change to it is negotiated among all of its users. That is great for the ecosystem, and it also means a fix we would like to see may take a while to land, or may never land in the shape we would prefer. When that happens, we work around it inside the mode as best we can, and report the issue upstream.

So, if you find something that looks like a mode bug and the answer turns out to be "the grammar parses it this way", now you know where that answer comes from. Please do report it anyway, we would rather hear about it twice than not at all.

Building grammars has its own quirks too. Not every grammar builds with make and a C compiler alone: several are generated from a JavaScript definition, so their build path expects the tree-sitter CLI, and sometimes a Node.js installation, to be available. This is a good part of why pre-compiled grammar bundles and distro packages are so popular. As said before, I still prefer compiling them interactively from Emacs, but now you know why your distro may be pulling in more than you expected.

Indirect buffers

This one deserves an explicit warning, because it surprises people: tree-sitter and indirect buffers do not get along.

1. Parsers are not shared with indirect buffers. They belong to the base buffer, and an indirect buffer starts with none. You either copy them over manually, or re-instantiate them by enabling a major mode in the indirect buffer.

2. Font-lock in indirect buffers is not supported at all. This is a limitation in Emacs itself.

The practical consequence is that (at least at the moment of this writing) if you use a package that clones a region into an indirect buffer, expect no fontification there. This is not specific to markdown-ts-mode, it applies to every -ts-mode, and it is not something we can fix from the mode's side.

Further reading

If this guide got you interested, there is a lot of good material out there about writing and using tree-sitter modes. Stéphane Marks, my partner in crime on this mode, put together the list below, and it is too good to keep to ourselves. Some of it may be a little stale by now, tree-sitter moves fast, but the reasoning in these articles holds up:

• Pulsar Edit's tree-sitter series, another editor going through the same journey
• Building Emacs major modes with tree-sitter: lessons learned
• Tree-sitter modes still need a syntax table
• Let's write a tree-sitter major mode
• Making an Emacs major mode for Cabal using tree-sitter

And, of course, the notes from the people who built all of this into Emacs, Yuan Fu and Juri Linkov, which are the closest thing we have to a canonical reference:

• Emacs 30 tree-sitter notes
• admin/notes/tree-sitter in the Emacs repository

Is this going to be out of the experimental tag on next Emacs release?

In this post beginning I wrote:

What this means? Should you use it or not? Is this ready? Is this just a sketch of a mode?

Now you probably have a better answer.

experimental does not mean markdown-ts-mode is just a sketch or that it is missing the basic features you would expect from a Markdown mode. It means the mode is still evolving, and we are not yet ready to promise that its API, behavior, or some of its features won't change.

So, should you use it? Yes! If you are comfortable with the experimental label, please give it a try. The more people using it with different Markdown files, configurations, and workflows, the easier it is for us to find issues and fix it.

Will it be out of experimental in the next Emacs release? Maybe, we sure are working towards it! We will see. There are still things to polish, limitations to work around, and feedback to process before we can make that call.

For now, consider this your invitation to play with it. And if you find something weird, don't just work around it, let us know. That's how we get it ready.

By default, scrolling in Emacs recenters the window when point moves off-screen, and rapid scrolling through large, heavily fontified files can introduce noticeable input lag. This article outlines configurations that make scrolling more predictable and responsive.

Customizing scroll recentering

Adjusting the automatic scrolling behavior can prevent Emacs from making large jumps when point moves beyond the visible portion of the window:

;; Scroll by up to 20 lines to bring point back into view before falling back to
;; the normal automatic scrolling behavior.
(setq scroll-conservatively 20)

When point moves off-screen or into the scroll margin, setting scroll-conservatively to a moderate value like 20 allows Emacs to scroll the text by up to 20 lines in either direction to bring point back into view.

Note: Setting scroll-conservatively to a value above 100 prevents automatic scrolling from centering point, regardless of how far point moves. Emacs instead scrolls only far enough to bring point into view, placing it at the top or bottom of the window depending on the direction of scrolling.

Maintaining vertical context

While scroll-conservatively controls how Emacs reacts when point leaves the window, you can also define a boundary to force scrolling before point reaches the absolute edge:

;; Keep 3 lines of context visible above and below point.
(setq scroll-margin 3)

Setting scroll-margin to 3 establishes a boundary of three lines at both the top and bottom of the Emacs window, forcing the buffer to scroll automatically as soon as your cursor enters this area instead of waiting for it to reach the absolute edge of the screen.

This keeps point away from the top and bottom edges of the window whenever automatic scrolling can move it out of the margin.

Note: Leaving scroll-margin at the default of 0 ensures the cursor can sit directly on the top or bottom line before triggering a scroll. Many users prefer this default setting because it maximizes usable vertical screen space and mirrors the edge-scrolling behavior found in most other modern text editors.

Horizontal scrolling

When line truncation is enabled (truncate-lines is non-nil), Emacs automatically scrolls horizontally when point approaches the left or right edge of the window. hscroll-margin controls how close point can get to an edge, while hscroll-step controls how far the window moves when automatic horizontal scrolling occurs.

;; Horizontal scrolling
(setq hscroll-margin 2
      hscroll-step 1)

Setting hscroll-margin to 2 causes horizontal scrolling to trigger when point comes within two columns of the left or right edge, while setting hscroll-step to 1 forces the window to pan exactly one column at a time.

This transforms horizontal movement into a column-by-column scroll, replacing the default behavior where Emacs jumps the view by half a screen horizontally and forces you to visually search for your cursor.

Deferring fontification during input

Fontification (syntax highlighting) requires CPU time to parse and colorize text. In large or complex buffers, this process can block the main thread, leading to input latency. Setting redisplay-skip-fontification-on-input to t causes Emacs to prioritize user input over immediate syntax highlighting:

;; Skip some fontification when input is pending.
(setq redisplay-skip-fontification-on-input t)

The tradeoff is that syntax highlighting may temporarily lag behind the underlying text while your input is actively being processed. When scrolling rapidly into an unseen section of a file or pasting a large block of code, the text might appear uncolored or incorrectly colored for a fraction of a second. However, the delay is virtually unnoticeable, and the correct colors will render as soon as the input queue clears.

Preserving screen position

Setting scroll-preserve-screen-position to t fixes a common visual annoyance when paging up or down through a file (using C-v or M-v). If your cursor is in the middle of the screen and you hit Page Down, the cursor stays exactly in the middle of your monitor:

;; Preserve point's vertical screen position when scrolling.
(setq scroll-preserve-screen-position t)

Note: There is one exception involving next-screen-context-lines (default 2), which controls how many lines of text are repeated from your previous screen when you scroll by a full window. If your cursor is resting on one of these repeated lines at the edge of the window when you jump, Emacs does not preserve its vertical screen position. Instead, it moves the cursor into the newly revealed text. This prevents the cursor from getting stranded at the extreme edge of the window and ensures you have enough surrounding text to read comfortably.

Disabling automatic vertical scrolling

Setting auto-window-vscroll to nil prevents movement and scrolling functions from automatically modifying the window's vertical scroll position when they encounter display rows taller than the window:

;; Do not automatically adjust vertical scrolling through tall display rows.
(setq auto-window-vscroll nil)

This makes vertical movement through buffers containing large elements, such as inline images, much more predictable by avoiding sudden partial-screen shifts. The tradeoff is that tall display rows become more cumbersome to navigate because Emacs no longer automatically scrolls through their partially visible portions to reveal the rest of the element.

Top and bottom scroll errors

By default, Emacs immediately signals an error if you attempt to scroll past the top or bottom of a buffer. Setting scroll-error-top-bottom to t changes this behavior so that your first attempt to scroll past the boundary safely moves the cursor to the exact beginning or end of the document:

;; Move point to the buffer boundary before signaling a scrolling error.
(setq scroll-error-top-bottom t)

Instead of throwing an error immediately, it moves your cursor directly to the first or last character of the buffer. If you attempt to scroll again while your cursor is already resting on that final position, Emacs will then signal the standard scrolling error.

Enabling faster scrolling

Rapid scrolling can become sluggish when Emacs encounters previously unfontified text. Setting fast-but-imprecise-scrolling to t prevents Emacs from becoming unresponsive when you move rapidly through large buffers:

;; Avoid fontifying unfontified text while scrolling rapidly.
(setq fast-but-imprecise-scrolling t)

The primary tradeoff is that scrolling can become visually imprecise. However, this behavior is generally nothing to worry about. For typical programming tasks using a standard monospaced font, line heights remain consistent, meaning you will likely never experience this imprecision at all. Even in modes that do use variable font sizes, the visual jump is minor and temporary. Once you stop scrolling and the input queue clears, Emacs finishes fontifying the visible text and corrects the layout, ensuring your final view is accurate.

Scroll aggressiveness

By default, when point moves beyond the top or bottom of the window, Emacs scrolls the buffer and places point around the middle of the screen. Setting scroll-up-aggressively and scroll-down-aggressively to 0.01 keeps point near the edge of the screen instead:

;; Provide a "stick-to-edge" scrolling experience.
(setq-default scroll-up-aggressively 0.01
              scroll-down-aggressively 0.01)

This results in minimal, predictable scrolling increments.

Permitting scrolling during search

By default, attempting to scroll the window while in an active isearch session (using C-s or C-r) cancels the search. You can allow scrolling without losing your search context.

;; Allow scrolling actions while remaining inside a search block.
(setq isearch-allow-scroll 'unlimited)

This allows you to scroll away from your current match to check another part of the file for reference, and then resume your search by pressing C-s to jump to the next match.

Shell and compilation buffers

When executing long-running processes in interactive shells or REPLs (comint-mode), new output arriving at the bottom of the buffer will frequently scroll your view downward. Setting comint-scroll-to-bottom-on-input to t and comint-scroll-to-bottom-on-output to nil causes Emacs to snap point to the bottom of the buffer only when you supply keyboard input:

;; Auto-scroll to bottom only when you type, not when background output arrives.
(setq-default comint-scroll-to-bottom-on-input t
              comint-scroll-to-bottom-on-output nil)

This allows you to scroll up through compilation logs or terminal history to read errors without the screen aggressively jumping to the bottom every time a new line is printed.

The mouse wheel scrolling

The default mouse wheel behavior in Emacs can feel jumpy, as it scrolls multiple lines per click and accelerates based on scroll speed. You can easily modify this and assign modifier keys to perform horizontal scrolling or text scaling:

;; Scroll one line at a time and map modifier keys to specific actions.
(setq mouse-wheel-scroll-amount
      '(1
        ((shift) . hscroll) ((meta))
        ((control meta) . global-text-scale)
        ((control) . text-scale)))

;; Disable acceleration of scrolling.
(setq mouse-wheel-progressive-speed nil)

Setting mouse-wheel-scroll-amount to 1 configures the mouse wheel to scroll exactly one line vertically, while mapping modifier keys like Shift for horizontal scrolling and Control for text scaling turns your mouse into a navigation multi-tool. Paired with setting mouse-wheel-progressive-speed to nil, this prevents rapid wheel movements from dynamically accelerating the scroll distance.

The result is a predictable, line-by-line scrolling experience that stops you from losing your place, with the tradeoff being that navigating very long files with a physical scroll wheel requires more physical effort since the view will not jump in large increments.

Note: If you prefer a keyboard-driven workflow and want to disable mouse input entirely, check out the inhibit-mouse package.

Modern pixel-precise scrolling

Emacs 29 introduced pixel-precise scrolling for pointing devices that support suitable high-resolution scrolling events.

;; Enable pixel-precise scrolling for supported pointing devices.
(pixel-scroll-precision-mode 1)

;; (setq pixel-scroll-precision-use-momentum nil) ; Optional: disable momentum

Enabling pixel-scroll-precision-mode activates pixel-resolution scrolling for supported mouse and touchpad input, removing the traditional limitation of scrolling by whole text lines.

My go to Emacs in-line dictionary is abo-abo’s define-word. It pops up a definition of the word at point in the minibuffer. I use it several times a day. Lately, though, it has been returning “zero definitions found” on every invocation. This problem predated my update to Emacs 31.1 so it’s not related to the version of Emacs.

Today (Tuesday) I finally got fed up and decided to track down the problem. It wasn’t too hard. It turns out that the problem is that define-word calls the on-line dictionaries with HTTP rather than HTTPS and the sites are rejecting the connections. There’s already a pull request (2026-08-22) for the fix but as of today (2026-08-25) it hasn’t been merged or uploaded to MELPA.

I messed around for a while but couldn’t get any of the obvious solutions to work so I gave up and added

  :init
  ;; Until define-word is updated in MELPA
  (defcustom define-word-services
    '((wordnik "https://wordnik.com/words/%s" define-word--parse-wordnik)
      (openthesaurus "https://www.openthesaurus.de/synonyme/%s" define-word--parse-openthesaurus)
      (webster "https://webstersdictionary1828.com/Dictionary/%s" define-word--parse-webster)
      (offline-wikitionary define-word--get-offline-wikitionary nil))
    "Services for define-word, A list of lists of the
  format (symbol url function-for-parsing).
Instead of an url string, url can be a custom function for retrieving results."
    :type '(alist
            :key-type (symbol :tag "Name of service")
            :value-type (group
                         (string :tag "Url (%s denotes search word)")
                         (function :tag "Parsing function"))))

to the use-package for define-word. That’s just a copy of the definition of define-word-services from the define-word source. Note that it’s important that it goes in the :init section so that the definition gets established before define-word is loaded.

It’s a messy solution but it will do until the fix is merged and percolates up to MELPA.

Back in 2019 I wrote about dealing with Jekyll post URLs, where I shared a tiny command that spared me from having to remember the exact file name of every article I wanted to link to. That command has been in my config ever since, and over the years it quietly grew a few siblings. Recently I finally gathered them all in one place and turned them into a small package - utterson.

The common Jekyll tasks

I guess anyone who blogs with Jekyll knows the drill. Jekyll is great and I have no intention of switching, but a few of its conventions generate a steady trickle of manual work:

• posts live in _posts and their file names have to start with the publication date, as in 2026-08-26-some-post.md
• every article needs a bit of YAML front matter at the top - a layout, a title, a date, some tags
• linking to another post means using a Liquid tag that wants that date-prefixed file name, which nobody remembers
• images and other assets need URLs relative to the site root, not to the article you happen to be editing

None of this is hard. All of it is annoying, and all of it is exactly the sort of mechanical work an editor should be doing on your behalf. So over the years I wrote a command for each chore, dropped it in my init.el and moved on with my life.

Why I finally cleaned this up

The tipping point was the last command I added - promoting a draft to a post.

I write most articles in _drafts, where jekyll serve --drafts shows them but a deploy doesn’t. Publishing one used to mean renaming the file by hand to add today’s date, then editing the date in the front matter to match, then convincing git that this was a rename rather than a delete plus a brand new file. Three chances to get something wrong, and I certainly got it wrong more than once.

Once that was automated I took a look at what had accumulated in my config and realized it wasn’t a bag of snippets anymore - it was a workflow. And since every person blogging with Jekyll from Emacs deals with exactly the same chores, there was no good reason to keep it to myself. So I spent an evening extracting the lot, wrote some tests, and gave it a name.¹

There are other Jekyll packages for Emacs, of course. Both hyde and easy-jekyll aim to be something like an IDE for your site, with dashboards, deployment and preview buffers. That’s a perfectly reasonable thing to want, it’s just never been what I wanted. My site lives in git, I deploy it with a push, and I’ve already got Magit and a browser. All I ever wanted was for the bookkeeping to stop being my problem.

So utterson is deliberately small. It knows that a Jekyll site is a folder of Markdown files with YAML front matter, and that’s about the extent of its ambitions. Renames go through vc, so git records them as renames and the history of an article follows it around. Nothing in there ever deploys anything.

Taking it for a spin

The package is not on MELPA (yet?), so for the time being it’s package-vc territory:

(use-package utterson
  :vc (:url "https://github.com/bbatsov/utterson" :rev :newest)
  :custom
  ;; where to look for sites, when you invoke a command outside one
  (utterson-search-path '("~/projects/"))
  :config
  ;; the commands live in a keymap that you bind wherever you please
  (keymap-set utterson-mode-map "C-c j" 'utterson-command-map)
  (global-utterson-mode +1))

global-utterson-mode enables the minor mode in the buffers of any folder that has a _config.yml in it, so the commands are around while you’re working on a site and nowhere else.

C-c j p starts a post. It asks for a title, offers a file name slug derived from it (which you’re free to shorten right there, and I usually do), then asks for tags, completing against every tag the site already uses. That last bit is how you avoid ending up with both Emacs and emacs in your tag cloud. Finally it writes the front matter, saves the file and leaves the cursor exactly where you’re about to start writing:

---
layout: post
title: Meet Utterson, my Jekyll blogging helper
date: 2026-08-26 15:01 +0300
tags:
- Jekyll
- Blogs
- Packages
---

That block, as it happens, is the one this very article started with. Here’s the whole thing in action:

C-c j d does the same in _drafts and C-c j t moves an article between the two, dating it on the way in and staging the rename with git. C-c j r is for the article you wrote a couple of weeks ago and never got around to publishing - it sets the date to now and renames the file to match. Both of them take a prefix argument if you’d rather type a date than accept the current time, which is how you schedule something for next Monday morning.

Publishing a draft looks like this - notice that the file name, the date in the front matter and git’s idea of what happened all stay in sync:

The linking commands are the descendants of that 2019 snippet, all grown up. C-c j u inserts a post_url tag, completing over your posts newest first and showing you each post’s title next to its file name, and C-c j l inserts the entire Markdown link, already titled after the post it points to:

C-c j i inserts an image, C-c j I copies a file into your images folder first (perfect for a screenshot that’s still sitting on your desktop under a name like Screenshot 2026-08-26 at 15.01.12.png), and C-c j a links to anything else under assets. And C-c j s runs jekyll serve in a buffer, because sooner or later you do want to look at the thing.

Note: There’s a menu as well, in case you’d rather click your way around while the keybindings are still settling in.

Epilogue

It’s early days for the package, even though most of the code behind it has been in daily use for years. If you blog with Jekyll from Emacs, I’d love to hear which of your own little chores it doesn’t cover yet - that’s the fastest way for it to get better.

And if you don’t blog with Jekyll - what does your setup look like? I’ve got the feeling that quite a few of you are writing your posts in org-mode and I’m always curious about the workflows people come up with.

That’s all I have for you today! Keep hacking!

If I had a dollar for every time someone asked on the Clojurians Slack in #cider why C-x C-e evaluated “the wrong thing”, I’d probably be writing this post from a yacht. The answer was always the same: the cursor wasn’t where CIDER expected it to be. The upcoming CIDER 2.1 release changes that - the evaluation commands now figure out which form you mean from where your cursor actually is.

NOTE: Update: this didn’t survive contact with its users, and CIDER 2.1 ships with the classic behaviour after all. See /posts/2026/08/29/smarter-form-targeting-is-not-coming-to-cider.html for what the feedback was, what replaced it, and the rather nasty bug the detour turned up.

A bit of history

Emacs has a very particular tradition when it comes to evaluating code: eval-last-sexp (the venerable C-x C-e) acts on the expression before the cursor. Not the one you’re looking at, not the one you’re inside of - the one that ends exactly where your cursor stands. SLIME follows this tradition, Emacs Lisp itself follows it, and for the past 15+ years CIDER has followed it too.¹ If you grew up in Emacs, this rule is in your fingers and you’ve never once thought about it.

Here’s the thing, though - most people using CIDER didn’t grow up in Emacs. And many of them never programmed in Emacs Lisp and Common Lisp with SLIME. They came to Emacs because of CIDER (or Clojure in general), and for them the rule is invisible, arbitrary and mildly hostile. You put your cursor on a form, you press the eval key, and CIDER cheerfully evaluates… something else. Meanwhile every other modern Clojure environment - Calva, Conjure, the various vim plugins - resolves the form from the cursor position and just does what you meant.²

For a long time I resisted changing this, mostly out of respect for the Emacs tradition (and my own muscle memory). But at some point I had to admit that I was optimizing for the wrong audience. CIDER’s users are mostly casual Clojure hackers who happen to use Emacs, not Emacs experts who happen to write Clojure. The tradition was serving me, and confusing them.

What’s actually changing

The evaluation commands (and their macroexpansion, inspection and tapping siblings) now resolve “the form the cursor indicates”. Concretely, with | marking the cursor:

(map inc |(range 10))

Pressing C-c C-e here used to evaluate inc - the form before the cursor, which is almost never what you wanted. Now it evaluates (range 10) - the form your cursor is pointing at.

(str "hello" " " "world"|)

This one used to evaluate "world" (really!), because the last complete expression before a cursor sitting on the closing paren is the final string. Now it evaluates the whole (str ...) call.

Macroexpansion benefits too:

(when tru|e (launch-missiles))

C-c C-m here used to complain that true is not a macro. Now it expands the enclosing (when ...) call, because expanding a bare symbol is never what anyone means.

And my favorite one - the rich comment workflow is now consistent everywhere:

(comment
  (calculate-all-the-things|))

Every defun-level command - eval, pretty-print, inspect, debug - now treats the form inside the (comment ...) as the top-level one. Evaluating a whole comment form returns nil by definition, which has exactly zero uses, so CIDER no longer does that no matter which command you reach for.

Why you probably won’t notice

Here’s the part I’m most pleased with: the new behavior agrees with the old one at every position where “the form before the cursor” made sense. Cursor right after a form? Same result as always. Cursor in the whitespace after a form? Same. Cursor in the middle of a symbol? Same. The two behaviors only diverge where the classic answer was something nobody ever wanted - a previous sibling, a lone trailing atom.

So if your muscle memory follows the Emacs tradition, nothing changes for you. If it doesn’t - CIDER stops punishing you for it. That’s the whole change.

Reverting to the classic behavior (for now)

If you do want the traditional rules - maybe you genuinely use “evaluate the previous sibling while standing on an opening paren” - one setting restores them exactly:

(setq cider-form-targeting 'preceding)

There’s also a per-session toggle in the eval menu (C-c C-v T) that shows the active mode in the mode line while you experiment.

This option is probably living on borrowed time, though. I added it back when I planned to keep the classic behavior as the default and offer smart targeting as an opt-in. Now that the roles are reversed, an option whose only job is restoring rules almost nobody deliberately relied on doesn’t really make much sense, and lately I’ve been trying to trim that kind of clutter from CIDER, not add to it. Don’t be surprised if the option quietly disappears - possibly even before the release ships. Which is one more reason to speak up now if the classic behavior genuinely matters to you.

Farewell, “last sexp”

This change forced my hand on something I’d been putting off for years - the command names. cider-eval-last-sexp is a fine name for a command that evaluates the last sexp. It’s a lie for a command that evaluates the form your cursor indicates. So the commands got honest names:

• cider-eval-last-sexp is now cider-eval-form
• cider-eval-defun-at-point is now cider-eval-defun (the -at-point never carried information)
• likewise for the pprint/tap/inspect/insert variants

Every old name keeps working as an alias, so your config and your M-x habits are safe. But why “form” and not “sexp”? Beyond the targeting change, there’s a Clojure-specific reason: in Clojure a form isn’t always a single sexp. ^:private x is two sexps but one form; so is #inst "2024-01-01". The commands operate on forms - the reader’s unit of evaluation - and now they say so.³ The manual’s evaluation docs got a proper glossary explaining all of this.

Closing thoughts

All of this is on master and in the MELPA snapshots today, ahead of the next stable release. I’d really love for people to play with it before the release ships - especially if you’re an Emacs veteran whose fingers disagree with my reasoning, or a newcomer for whom this was supposed to just work. Did we get the resolution rules right? Does anything still surprise you?

Share your feedback on the CIDER discussions board, in #cider on the Clojurians Slack, or just file an issue. This is exactly the kind of change that’s easy to adjust before a release and painful after - and the fate of the compatibility option depends on what I hear.

That’s all I have for you today. Keep hacking!

Eglot ships with Emacs as a built-in, lightweight LSP client, and its default configuration is sufficient for most projects. However, working with large codebases can cause latency. When Eglot becomes sluggish, the problem may involve work performed by Eglot and Emacs as well as the language server itself. Event logging, filesystem watching, diagnostics, completion, and other editor activity can all contribute to latency.

This article covers practical changes for keeping Eglot responsive when working with large projects.

Auto-shutting down idle Eglot servers

This reduces resource usage when switching between multiple projects. The eglot-autoshutdown variable shuts down the LSP server after the last managed buffer has been killed.

(setq eglot-autoshutdown t)

This is useful when many separate language servers would otherwise remain running after their buffers have been closed.

(If you find yourself routinely leaving unused buffers open, the buffer-terminator package can automate this cleanup. It quietly monitors your buffer activity and terminates idle file buffers, ensuring eglot-autoshutdown can trigger reliably without requiring you to manually execute kill-buffer.)

Preventing Eglot from blocking the Emacs UI on connection

Opening a project can cause Emacs to block while waiting for the LSP server to initialize. Setting eglot-sync-connect to nil prevents Eglot from blocking on the initial connection, allowing the connection to continue in the background:

(setq eglot-sync-connect nil)

This prevents the connection attempt from unnecessarily delaying interactive editing.

Disabling LSP event logging

Eglot maintains an events buffer containing JSON-RPC activity. Large event logs consume memory and add string allocation costs, especially when retaining complete JSON payloads is not needed during normal editing.

Configuring eglot-events-buffer-config (or eglot-events-buffer-size on Emacs 29 and earlier) reduces the volume of retained data:

;; Disable event logging completely (Emacs >= 30)
(setq eglot-events-buffer-config '(:size 0 :format short))

;; For Emacs <= 29
;; (setq eglot-events-buffer-size 0)

Setting :size 0 disables the events buffer.

Reducing file watchers

Allowing a language server to monitor large portions of a repository can consume OS file descriptors, increase memory usage, and add startup delay. To reduce these resource costs, limit the number of file that Eglot watches using:

(setq eglot-max-file-watches 5000)

In addition, where supported by the language server, configure it to ignore large generated directories such as node_modules, .git, or build output folders. Because these exclusion rules are specific to the language server, they must be passed through the eglot-workspace-configuration variable. (The standard method is to define these rules per-project using a .dir-locals.el file at the root of your repository.)

Disabling progress reporting

Whenever a server reports progress (e.g., during indexing or builds), this can trigger mode-line redisplays. The following suppress mode-line progress reports:

;; Suppress mode-line progress animations
(setq eglot-report-progress nil)

Disabling automatic code action probing

By default, Eglot can asynchronously query the language server for available code actions at point when the cursor is idle. Disabling these automatic indications reduces continuous process communication and background activity during editing:

;; Disable automatic code action indicators to reduce background polling
(setq eglot-code-action-indications nil)

Note: Disabling this feature only removes the automatic UI indicators. You retain the ability to manually request and execute code actions at any time by invoking M-x eglot-code-actions.

Disabling unneeded LSP server capabilities

Note: You do not need to disable all of these capabilities, as some of them are very useful. Only disable the ones you do not use.

LSP servers can provide optional capabilities. Disabling features that are not needed can reduce processing and visual clutter, although the actual performance benefit depends on the language server and project.

Eglot handles on-type formatting by evaluating every single keystroke to check if the connected language server supports the feature and if the typed character is a registered trigger character. If a match occurs, Eglot issues an RPC request and applies the asynchronous edits, which can conflict with external formatters and introduce typing latency. To prevent these background requests and bypass the per-keystroke evaluation entirely, use:

(with-eval-after-load 'eglot
  (add-to-list 'eglot-ignored-server-capabilities :documentOnTypeFormattingProvider))

Inlay hints (eglot-inlay-hints-mode) display automatically determined types and parameter names as annotations in the buffer. Disabling them removes the associated visual annotations and any work required to maintain them:

(with-eval-after-load 'eglot
  (add-to-list 'eglot-ignored-server-capabilities :inlayHintProvider))

When the cursor rests on a symbol, the LSP server can highlight other occurrences of that symbol (eglot-highlight-eldoc-function). Disabling it will stop Eglot from highlighting other occurrences of the symbol under the cursor:

(with-eval-after-load 'eglot
  (add-to-list 'eglot-ignored-server-capabilities :documentHighlightProvider))

For major modes with Tree-sitter support, Tree-sitter already provides syntax-aware fontification locally and can be sufficient for many users. When the language server supports semantic tokens, Eglot can request semantic-token information over LSP and use it for additional syntax highlighting. Processing these responses requires JSON-RPC communication, decoding the token data, and applying the corresponding fontification. On large or frequently changing buffers, this can add CPU overhead. Ignoring the server's semantic-token capability prevents Eglot from using this feature:

(with-eval-after-load 'eglot
  (add-to-list 'eglot-ignored-server-capabilities :semanticTokensProvider))

Note: The tradeoff is that some semantic highlighting supplied by the language server may be lost. Tree-sitter fontification and LSP semantic tokens are not identical, so disabling semantic tokens can result in less precise or less detailed highlighting for some languages.

Garbage collection, native compilation, and read process output max

• The Emacs garbage collector can cause pauses during heavy workloads. LSP activity can increase allocation through diagnostics, completion, JSON processing, and other editor integrations. GC tuning can therefore help in some workloads, but the effect is workload-dependent. Increasing gc-cons-threshold permanently can reduce garbage collection frequency:
  (setq gc-cons-threshold (* 100 1024 1024))
  (Alternatively, several users rely on the gcmh package, which raises the GC threshold during active editing and forces a collection when Emacs becomes idle.)
• Enable Native Compilation: Ensure that Emacs is built with native compilation support enabled. Native compilation can improve the execution speed of Emacs Lisp code, including code used by Eglot and other packages. (Recommendation: Use the compile-angel package to ensure that all packages are natively compiled.)
• read-process-output-max: read-process-output-max controls the maximum amount of data Emacs reads from a subprocess in a single operation. Since Eglot communicates with language servers through subprocesses, increasing this value can improve performance when a server sends large bursts of JSON-RPC data, such as during initialization, workspace indexing, or large file updates, by reducing the number of read operations required to consume the output. Raising it can help workloads that regularly receive large bursts of process output:
  (setq read-process-output-max (* 1024 1024))
  (This raises the limit to 1 MiB. It does not reserve 1 MiB of memory for each process or increase the amount of data a server can send; it only allows Emacs to consume more output per read operation. On GNU/Linux systems, the value should not exceed /proc/sys/fs/pipe-max-size)

Freeing up the main Emacs thread with tree-sitter

Emacs executes Lisp, handles asynchronous process output, and updates the UI on a single main thread. In traditional major modes, typing triggers complex regular expression evaluations for syntax highlighting (font-locking). This CPU-bound work competes directly with Eglot, which relies on the exact same thread to deserialize incoming JSON-RPC payloads and render diagnostics. If the main thread is busy computing regexes, Eglot is forced to wait in the queue, resulting in input lag even if the external language server responds instantly.

Major modes built on Tree-sitter (the *-ts-mode variants, such as c-ts-mode, python-ts-mode, and rust-ts-mode) use the Tree-Sitter C library for incremental syntax parsing. If a stable *-ts-mode exists for your programming language, enabling it can improve Eglot's responsiveness.

A quick update for my Emacs config Gems series:

I am working on part 5, and I’m trying to finalize a few things first. Currently it’s Ispell (I’ve not been using it to its full capacity) and completion… more details soon.

Emacs produces a backup of each file by default. It does this by appending a tilde to the file's name. For example, Myfile.txt is backed up to Myfile.txt~. It's a reasonable strategy, assuming that a Version Control system is in place.

But in the absence of version control, you're limited to restoring just the previous version; older versions need to be restored from backup.

I use git for coding projects that I share to the public. But I didn't create a repository for my home directory. So when C-c a m TAG¹ generated an error instead of a list of TAGged items, I hoped fervently that the latest init file change was to blame.

After finding and fixing the problem quickly, (and realizing I was lucky this time), I resolved to be more diligent about disaster recovery. I looked into what backup schemes Emacs already provides.

Emacs can create unique backups for a file rather than overwriting the previous backup. When Emacs sees a numbered backup for a given file, it will make a new, sequentially-named file for each backup of that file, while continuing to use the "append tilde" method for other files.

Once I renamed (or copied) .emacs~ to .emacs.~1~, Emacs created backups named .emacs.~2~, .emacs.~3~ (and so on). I didn't even need to change a variable -- when Emacs detected .emacs.~1~, it knew that backups of .emacs needed to be numeric, so it acted accordingly. Emacs continues to use bills.org~ as the backup for bills.org. Until I tell it otherwise.

Read the Emacs Manual to learn more about numbered backups.

¹ C-c a m invokes org-tags-view

The default values for the pertinent backup variables are:

• make-backup-files is t
• backup-by-copying is nil
• version-control is nil

The topic of this month's Emacs Carnival interests me, even though I "dump ... notes into a directory and simply grep for information ...."⁰ Org does not work the way my brain works,¹ or rather, my brain doesn't work the way Org works.

I do use Org. At first I created a few Org files (work.org and home.org, and maybe todo.org) thinking I could rigidly dedicate all my topics to them.

Over time I had about dozen files, one for nearly every major facet of my life until I gave up. Why? Because it really doesn't matter where I put Org TODOs and their notes. When I need to locate something, Org provides a way to search entries for a regular expression, which is what grep does, sans all that Unixy CLI stuff.

So faced with the task of paying one of my wife's medical bills, I could agonize over whether to put the task into wife.org or bills.org or medical.org.² Or I could just:

• establish the task somewhere,
• act on it
• link to a receipt
• mark it done³

I created a special template for org-capture, which places these one-off tasks into todo.org. And it clocks into the task, too.

A topic with even greater complexity is "education." I'm a lifelong learner; my edu.org file has (only) 29 headings, all of which have at least a few subheadings. If I learn about an Emacs feature, I might want to write about it, so I'll put a task into blog.org that links to it.

Occasionally a post will span multiple topics in edu.org, topics such as Emacs, Vivaldi, LibreOffice, HTML or LaTeX. In a year from now, which file should I look for it in? The keystroke C-c a s comes to the rescue.⁴ I might search for "Sacha" because all I remember is that I discovered an Emacs feature on Sacha's website.⁵ Incidentally, I get 13 hits when I search for "Sacha," one of which was the one I had in mind.

The question I think all Emacs users face is, "At what point does tweaking Emacs (and self-quantifying tools in general) tip the scales from aiding our progress to impeding it?" I dread going down a Knowledge Management rabbit hole,⁶ but I'm sure I'll enjoy the leap.

⁰ Charlie Holland's Search for Knowledge

¹ A tree works like your brain.

² Don't even get me started on insurance.

³ All of this occurs while clocked in to the task.

⁴ In this case, C-c a is bound to org-agenda.

⁵ Sacha Chua's blog

⁶ Can one gain knowledge of Knowledge Management Systems without having a Knowledge Management System in which to record that knowledge? That may be a Zen koan for someone.

I installed Donovan Ratefison's brand-new Vakana app¹ on my Android device this morning. After following the tutorial, I exported the thread as an Org-mode-compatible package in a ZIP and emailed it to myself in order to transfer it to my desktop.

After opening the Org file that Vakana generated, I exported the entire buffer to HTML. The result is shown below. The only change I wanted to make was to scale the bead of each heading 25%.²

It's fortuitous that Donovan Ratefison released Vakana in a month whose Emacs Carnival theme is "The Search for Knowledge," because Vakana provides a unique way to manage one's knowledge. I'll need to become proficient in it before adding it to my workflow. So my eventual Emacs Carnival submission will be more pedestrian.

¹ Learn about Vakana here or download here.

² The images used for beads are SVG files. However this blogging platform does not support that file type, so I converted them to GIF for this post. This should explain why they don't look awesome.

Your first thread

Your first thread
A 90-second tour. Walk it bead by bead, then make it yours — delete it, or reload it anytime from Settings → Pro Tips.

Table of Contents

• 1. The thread
• 2. Start here · a 90-second tour
• 3. 1/5 · Tap the bead
• 4. 2/5 · Open the thread
• 5. 3/5 · Comment — swipe me right
  • 5.1. Comments
    • 5.1.1. Comment — [2026-08-09 Sun 18:50]
• 6. 4/5 · Long-press a bead in the list
  • 6.1. Comments
    • 6.1.1. Comment — [2026-08-09 Sun 18:22]
    • 6.1.2. Comment — [2026-08-09 Sun 19:14]
• 7. 5/5 · Close it, then make it yours

1. The thread

2. Start here · a 90-second tour

[2026-08-09 Sun]

Welcome — and if this is all new, that’s perfectly fine. We’ll go gently.

Vakana is the Malagasy word for beads — there’s no other word for them in the language, and it’s where this app takes its name. The idea is old and simple: you turn a moment into a small bead — a little coloured token — and beads you keep together form a thread you can walk back along, like beads on a string. (These six notes are already a thread — “Your first thread.”)

That’s the whole shape of it. What a bead means is always yours — the app never decides that for you.

This is a short, hands-on tour: five steps, each one a thing you try yourself.

Next → 1/5 · Tap the bead.

3. 1/5 · Tap the bead

[2026-08-08 Sat]

,*Tap the bead* at the top of this note — the composer opens. That’s where you pick a bead’s shape, pattern, mood-colour and a tiny glyph (this one’s is the number 1️⃣).

Eight shapes, eight patterns, eight moods — small enough to learn, wide enough for anything. There’s no legend: a circle isn’t “an encounter” unless you decide it is.

How does the user navigate the beads? Now I see "< Prev" and "Next >" so it's obvious.

Next → 2/5 · Open the thread.

4. 2/5 · Open the thread

[2026-08-07 Fri]

You’re on a thread right now — a chain of beads strung together on purpose. Open “Your first thread” (tap its chip here, or find it in the Threads view) and you’ll see all six beads in a row you can walk, bead by bead.

The app also keeps a quiet thread for every day you write, under Days in the Threads view — built for you, no effort.

Next → 3/5 · Comment.

5. 3/5 · Comment — swipe me right

[2026-08-06 Thu]

Some thoughts arrive after the moment. Instead of rewriting a note, leave a comment in its margin.

Try it: tap the 💬 at the top of this note — or, back in your list, swipe this row to the right. Either opens the margin, where you can jot a thought or even set it to remind you later.

(The next bead, 4️⃣, already has a comment — spot the 💬 on its row.)

Next → 4/5 · Long-press the bead.

5.1. Comments

5.1.1. Comment — [2026-08-09 Sun 18:50]

The tutorial shows an icon for comment as a white-filled rectangular balloon with three dots. However the actual icon is a balloon that's an empty circle

6. 4/5 · Long-press a bead in the list

[2026-08-05 Wed]

Beads repeat, and you’ll want to find a bead’s kin. This is a thing you do from your list, not from inside a note — so head back to the list first.

There, press and hold any bead: the list instantly filters to every bead like it. (Long-press is the move most people miss.)

Want finer control? Tap the funnel at the top of the list to filter by shape, mood, pattern or glyph, then gather the results into a brand-new thread.

Next → 5/5 · Make it yours.

6.1. Comments

6.1.1. Comment — [2026-08-09 Sun 18:22]

I keep coming back to this one — long-pressing a bead is the move most people miss.

6.1.2. Comment — [2026-08-09 Sun 19:14]

The alarm clock icon next to the note field is for a reminder, not a timestamp. It puts it on the next business day at 9:00 a.m., perhaps. I pressed it at 3:00 p.m. on Sunday August 9th, and then entered the reminder for the next day at 9:00 a.m..

7. 5/5 · Close it, then make it yours

[2026-08-04 Tue]

This thread is closed — notice the clasp. Closing marks a loop that finished; you can reopen it anytime.

A finished thread can leave the app: open it and Export to turn it into a web page or a slide deck.

That’s the whole grammar — bead, thread, comment, close, export. Now make it yours:

• Delete this tour — swipe any note left, or remove it in one tap from Settings → Pro Tips → Interactive tutorial. • Want it back later? Reload from the same place.

Now write your first real moment, and bead it however you like.

Created: 2026-08-09 Sun 16:42

Validate