emacs.d

GNU Emacs configuration built around reproducibility, speed and portability across multiple installations.

Requirements

GNU Emacs 29.1 or greater. Tested by CI on 29.1 and development snapshots, used every day on development snapshot.

This configuration is only tested on GNU/Linux systems.

Guiding principles and features

• Fast startup (less than 1 second with native compilation)
• Portable on multiple machines (or multiple users) allowing specific local changes
• Provide core basic features and pluggable modules
• Prioritize builtin features (eglot, project, flymake, …) when it’s possible
• Keep things standard
• Reproducible builds with functional package management (straight.el) and version lockfile
• Avoid too much key customization
• Keep the Emacs home directory clean
• It has to work in the terminal
• Test package installation and startup in CI
• Weekly automated package upgrades via GitHub action

Installation

Clone the repo in .emacs.d (or the directory you want if you use the --init-directory option of Emacs 29):

git clone https://github.com/tomrss/emacs.d .emacs.d

Install packages: start Emacs or launch installer script in `.emacs.d` directory with:

make install

Update

Updates to package dependencies are made automatically by GitHub Action weekly. Packages and their “versions” (git commit) are freezed in dependency lockfile. If you want to upgrade package dependencies as per lockfile provided, you can pull latest updates on the main branch and then sync:

make sync-from-lockfile rebuild

If you want to upgrade further (you will be out of sync with this repo), you can do:

make upgrade rebuild

Local configuration

Every user installation can provide its own configuration in the local-config.el in the init directory (by default .emacs.d). This file is loaded after core features but before pluggable modules.

This file is gitignored, in fact it should be local only on one installation.

A typical usage of this local configuration is to decide which modules to plug in.

The module system

This configuration provides features in two ways:

Core features

Core feature are basic and fundational features that are always pulled in. This type of features prioritize builtin features and tries to keep the number of external packages low. Also key customization is minimized.

In other words, core features try to enhance Emacs without diverging too much from the standards.

They include:

• Cleanup Emacs init directory
• Better defaults: enable or tweak features that are builtin
• Some UI tweaks (fonts, scrolling, …)
• Completion framework: classic based on vertico, corfu, marginalia and orderless
• Try to make sense of window display and management (most notably with shackle rules)
• Boost dired
• Beautify org-mode (but not too much)
• Enhancement of compilation buffers and terminals (especially eshell)
• Development features mainly based on eglot

Pluggable modules

This modules are just Emacs Lisp files that can be pulled in or not in each installation. A pluggable module can be loaded or not without breaking anything.

This approach helps to increase configuration portability over multiple machines and multiple users, and also allow to maintain pieces of code no more used without loading them every time, ready for possible future usage.

Modules that will be loaded are defined in the variable u/enabled-modules. This variable can be changed in the local config file.

A default selection of modules is included in init.el.

The full list of modules is simply the list of files in modules directory.