This repository contains the configuration for my personal Emacs setup. Feel free to try it out for yourself or take any bits that you find useful.
This repository contains the following key files and folders:
- custom.el
- A file containing variables set through the Emacs customize interface
M-x customize. - early-init.el
- A file that loads before init.el. This file mostly contains code that reduces Emacs load time.
- early-init.org
- A literate programming file which generates early-init.el and contains commentary on the code contained in early-init.el.
- ./elisp/
- A folder containing my personal elisp files. These files are code which I am working with that with either become an Emacs package in the future or are used for small hacks and fixes.
- init.el
- This is the Emacs configuration file that is loaded during Emacs startup. Note: It is recommended that you DO NOT edit this file but rather edit the Org Mode file (init.org) below. Editing and saving the init.org will overwrite init.el as the files are tangled.
- init.org
- A literate programming file which generates init.el and contains commentary on the code contained in init.el
- ./modules/
- A folder containing the Emacs configuration modules. Each module is configured using a literate Org Mode file that is tangled to the corresponding Elisp file.
- README.org
- The file which you are currently viewing.
- runemacs.bat
- A batch file for windows that will execute the Windows runemacs.exe binary after setting the home directory to the drive label of the device that the batch file was called from. This file is useful for running emacs from a flash drive to create a fully portable Emacs setup.
- ./straight/versions/default.el
- A file generated from
straight-freeze-versionscontaining the current versions of all the packages defined in ./init.el.
In order to manage the large init.el configuration file, the configuration is written using Org Mode. There are some reasons for using Org Mode to manage the Emacs configuration:
- When a change to the configuration is made, it is easy to document why the change was made.
- Org Mode makes it much easier to navigate a large Emacs configuration as different code blocks can be nested under headings which can be folded or unfolded.
I have made this repository public as I have found inspiration from looking at the configuration of other Emacs users and thought that I would post this publicly in the small possibility that even one person might find this useful. Everything in this repository has been gathered from the GNU Emacs manual or sites that have been scoured from the internet in my quest to get Emacs to behave in the manner that fits my workflow.
If you like what you see here and you want to use this configuration yourself, that is fantastic. Feel free to clone this repository for yourself or make a fork of it as you see fit.
While this is my personal Emacs configuration, I have left the issues section open if anyone finds any errors that I may have missed and I will be ❤️ grateful ❤️ for your reporting of any issues that you find, however, keep the following in mind when you report any issues:
- The issues page is mainly for bugs or typos that you have discovered and want to report.
- This repository is my personal configuration and therefore reflects my personal taste in how I use Emacs. If you like this configuration but would prefer different themes, keybindings, or different packages then I would recommend forking this repository for your own use.
- If you have suggestions for improving this configuration, feel free to post an issue to this repository and I will consider it as I am open to new ideas, however, do not count on it being incorporated into this repository. Once again, I would recommend forking the
Even though this is a personal Emacs configuration, I have left the pull requests page open for a couple reasons:
- Occasionally, I use the Github web interface to merge my branches
- If someone finds an error in my code and wants to suggest a fix a pull request would be welcome.
I have not enabled the wiki for this repository or created a site for this page as nearly everything is documented in early-init.org and init.org. If you want to learn about the code, check out these files. I am constantly updating the files to reference where I have found these Emacs Lisp snippets and why I use them. I may consider enabling a wiki or a site in the future if I believe that may be useful to others and provide something that the .org files cannot provide.
This Emacs configuration is implemented with the following key features:
- Default Keybindings
- When possible, the default keybindings are used. Emacs was my first text editor and I have learned and memorized many of the keybindings from reading through the Emacs manual. This version of Emacs is not designed for Evil.
- Fast
- I am always trying to make Emacs run as fast as possible as I am often on slow machines and running Emacs from a flash drive really slows things down. Nearly every package has loading deferred.
- Modular
- This configuration has been split into modules which can be found in the ./modules/ folder. This makes the files smaller, easier to read and interpret, easier for bug-fixing, and simpler to interpret with benchmark.el.
- Portable
- This configuration is designed to work under both Linux and Windows. It has been tested in GUIX, on Raspberry Pi OS, Windows 10, and Windows 11. It is also designed to run quickly from a flash drive with runemacs.bat.
Many of you might be asking:
“Why create another custom Emacs configuration when there are modular versions of Emacs out there such as Doom Emacs and Spacemacs?”
The reasons for creating my own custom version are below:
- Vanilla Emacs was my first experience with serious text editing. Unlike many users who have switched from Vim to Emacs, I started as an Emacs user from the beginning. This led to:
- I learned the default Emacs keybindings from the GNU Emacs manual and I am not interested in switching to vi keybindings. I have become so accustomed to Emacs keys that I find I try to use them everywhere as they have become muscle memory.
- Having spent a lot of time reading the GNU Emacs manual, I feel more comfortable editing my own init.el file rather than having to learn how to wrangle with Spacemacs or Doom Emacs init files.
- I have found use-package to be modular enough that I don’t need a modular system such as Spacemacs or Doom Emacs.
- Using straight.el has allowed me to pick and choose which exactly which packages I want to use allowing for both cutting edge features when desired or freezing a version for stability without having to rely on waiting for package updates. It also provides the ability to easy fix or add features to code by allowing for editing the Emacs Lisp directly or by downloading your own forks of packages.
- I have been able to incorporate code into my Emacs configuration that makes it flexible enough to run on multiple operating systems and even as a portable Windows app without too many features being broken.
- Creating my own Emacs customization has allowed me to learn a lot about Emacs Lisp.
To summarize: This configuration was created by an Emacs user who started out as an Emacs user and who does not want to relearn new keys and enjoys customizing.
Fantastic! Here are some things you can do:
If you wish to give this configuration of Emacs a spin, use the following procedure:
- If you already have Emacs installed, make sure you make a backup of your current configuration so you can restore it if needed.
cd ~ mv .emacs.d .emacs.d.bak
- Clone this git repository into your home directory.
git clone https://github.com/tfree87/.emacs.d.git - Run Emacs and wait for it to load.
emacs
Feel free to fork this configuration and make any changes you see fit. If you add something cool 😎 please let me know!
If you like this configuration, please star it by clicking the star ⭐ button at the top of the page. If I get enough stars, I will consider making a public, community-driven repository of this configuration for general use.
In an open source world, sharing is caring. This configuration would not be the way it is without the work of others who were also willing to share their configurations: