A starter project for your Emacs configuration in a single command.
Install Emacs 29+:
- Download the latest version of Emacs (version 29+ required).
Install external dependencies:
gitgcc(a C compiler is required for compiling tree-sitter grammars)
Install Start Emacs:
Note
Your installation directory is the user-emacs-directory variable
in Emacs. If you open up Emacs and don't see any changes after
cloning, try invoking M-: user-emacs-directory in Emacs to
discover the correct location.
Mac/Linux:
git clone https://github.com/mgmarlow/start-emacs.git "${XDG_CONFIG_HOME:-$HOME/.config}"/emacsWindows (Powershell):
Warning
Windows users may prefer running Emacs via WSL, as outlined in WINDOWS.md.
git clone https://github.com/mgmarlow/start-emacs.git $env:USERPROFILE\AppData\Roaming\.emacs.d\
Post installation:
You're all set! Open up Emacs and you should see a bunch of stuff initializing, which might take a few seconds. First-time startup always takes a little longer since Emacs must refresh it's package archive, download packages used in Start Emacs, and get everything initialized.
With Emacs running, the next step is to work your way through the
tutorial. You can open it via the keybinding: C-h t (ctrl + h,
followed by t). The tutorial will teach you all of the basic
navigation tools that will help you when reading the Start Emacs
configuration source in init.el.
Note
While you're reading Emacs Lisp, don't forget that you can highlight
any symbol and use C-h o to pull up the built-in help docs.
When you're comfortable with the basic Start Emacs configuration, check out EXTENDING.md for a bunch of recipes that implement other useful Emacs features.
If you want to version control your Emacs configuration (like I
do), you will want to replace
the git artifacts from Start Emacs with your own. The simple way to do
this is to blow away the .git folder and re-initialize:
cd my-emacs-directory/
rm -rf .git/
git init
git commit -m "My new Emacs configuration"You may also be interested in using a tool like GNU Stow if your dotfile needs are more complicated.
There's a lot of joy to be had from throwing together your own Emacs configuration, but it can be hard to get started. A lot of that initial difficulty comes from the obtuseness of Emacs when viewed as a modern text editor; it just doesn't pack the same default experience that you may be used to.
The goal of Start Emacs is to set up some of those modern defaults with comments that explain what is being changed. It intentionally doesn't configure everything for you out-of-the-box, just the baseline features that might be expected from other editors like VS Code or Helix. Ultimately, your configuration should be your own and the comments are there to help you learn to be self-sufficient.
With Emacs 29 there's actually not that much configuration that you need (in my opinion) to have a great text editor, thanks in large part to the Emacs maintainers and ecosystem changes around LSP and tree-sitter. However, knowing what to change and how to do it comes with experience. Start Emacs can help bridge that gap.
Tree-sitter is a fancy tool that parses source code into syntax trees that are used for syntax highlighting (as opposed to using regular expressions, like classic Emacs modes). Start Emacs prefers tree-sitter major modes to their non-tree-sitter counterparts.
Although Emacs 29 ships with the tools necessary for enabling tree-sitter, it does not bundle the programming language grammars actually used for parsing. Those grammars must be installed separately. To work around this, Start Emacs uses a great little library, treesit-auto, that prompts for grammar installation if one is available for the current buffer. This will kick in automatically for any programming language that treesit-auto recognizes.
Eglot is a LSP client that ships with Emacs 29 and maintains a high-level of compatibility with other built-in Emacs packages. The configuration from Start Emacs plays nicely with the completion framework Corfu, which provides LSP suggestions directly in your Emacs buffer.
Start Emacs replaces the default Emacs navigation with a few tools that do the job (arguably) better. Vertico and Consult do most of the heavy-lifting here, providing interactive completing-read suggestions when working in the minibuffer or searching buffers. Orderless makes both of these tools better with space-delimited matching, meaning your query does not need to exactly match the buffer text to find results.