May I recommend…

to only add items to your init files you understand and document them? This may be evident for you but took me a long time to realize and follow.

This post for Emacs Carnival May 2026 describes my workflow for changing my init files.

Emacs is the most configurable and malleable software I’m aware of. As such, there is an huge amount of settings one can choose already built in and a lot more depending on the amount of additional packages.

Like probably many others I follow blogs that describe Emacs configurations and settings. Also I like looking at other people’s Emacs configurations to discover settings that could improve my workflow or ease of use of Emacs.

For a long time I’d just copy settings and code into my init.el file. This created a number of issues:

• things would break but I didn’t know why, like one example I described here.
• I encountered unexpected behaviour I couldn’t explain or settings wouldn’t work as described.
• I lost track what settings were for and why they existed leading to cruft in my config.

Hence now beside being more cautious in adding new stuff I rather try to understand each piece of code I add and to document it.

My approach is now

• I look up the documentation for each setting. Thanks to the Emacs introspection capabilities this just requires running the describe-variable function usually bound to C-h v. Only if it makes sense to me I add it to my init files.

• For code snippets, hooks etc. I try to understand the code and what it does. I have to admit that even after 35 years of using Emacs my knowledge of Emacs lisp leaves a lot to be desired. If I don’t get the feeling I know what’s going on I rather omit it even it comes from experts.

  Also I document a lot more on multiple levels:

  • I use a literal orgmode configuration so I can take notes on what parts of my config intend and why I added them and where I found them.
  • When changing existing settings at least I add a note with C-c C-z with a comment to help me reminding later.
  • I prefer setting variables directly rather than through the customize facility since it’s easier to add notes.
  • I use the use-package macro extensively and like the option to add comments inline for custom settings so for example:

(use-package emacs
:ensure nil
:custom
(create-lockfiles nil "Prevent the creation of lock files when editing")
(cursor-in-non-selected-windows nil "Don't show a cursor if the window is not selected to reduce visual clutter")
(custom-safe-themes t "I treat all themes as safe")
(delete-by-moving-to-trash t "Move deleted files to the trash instead of permanently deleting them")
(delete-selection-mode t "Enable replacing selected text with typed text"))

Since following this workflow my configuration has become a lot more stable and more maintainable.