Go to file
Henrik Lissner 0e851ace9b
Backport bits of CLI rewrite
The rewrite for Doom's CLI is taking a while, so I've backported a few
important changes in order to ease the transition and fix a couple bugs
sooner.

Fixes #2802, #2737, #2386

The big highlights are:

- Fix #2802: We now update recipe repos *before* updating/installing any
  new packages. No more "Could not find package X in recipe repositories".

- Fix #2737: An edge case where straight couldn't reach a pinned
  commit (particularly with agda).

- Doom is now smarter about what option it recommends when straight
  prompts you to make a choice.

- Introduces a new init path for Doom. The old way:
  - Launch in "minimal" CLI mode in non-interactive sessions
  - Launch a "full" interactive mode otherwise.
  The new way
  - Launch in "minimal" CLI mode *only* for bin/doom
  - Launch is a simple mode for non-interactive sessions that still need
    access to your interactive config (like async org export/babel).
  - Launch a "full" interactive mode otherwise.

  This should fix compatibility issues with plugins that use the
  async.el library or spawn child Emacs processes to fake
  parallelization (like org's async export and babel functionality).

- Your private init.el is now loaded more reliably when running any
  bin/doom command. This gives you an opportunity to configure its
  settings.

- Added doom-first-{input,buffer,file}-hook hooks, which we use to queue
  deferred activation of a number of packages. Users can remove these
  modes from these hooks; altogether preventing them from loading,
  rather than waiting for them to load to then disable them,
  e.g. (after! smartparens (smartparens-global-mode -1)) -> (remove-hook
  'doom-first-buffer #'smartparens-global-mode)

  Hooks added to doom-first-*-hook variables will be removed once they
  run.

  This should also indirectly fix #2386, by preventing interactive modes
  from running in non-interactive session.

- Added `doom/bump-*` commands to make bumping modules and packages
  easier, and `doom/bumpify-*` commands for converting package!
  statements into user/repo@sha1hash format for bump commits.

- straight.el is now commit-pinned, like all other packages. We also
  more reliably install straight.el by cloning it ourselves, rather than
  relying on its bootstrap.el.

  This should prevent infinite "straight has diverged from master"
  prompts whenever we change branches (though, you might have to put up
  with it one more after this update -- see #2937 for workaround).

All the other minor changes:

- Moved core/autoload/cli.el to core/autoload/process.el
- The package manager will log attempts to check out pinned commits
- If package state is incomplete while rebuilding packages, emit a
  simpler error message instead of an obscure one!
- Added -u switch to 'doom sync' to make it run 'doom update' afterwards
- Added -p switch to 'doom sync' to make it run 'doom purge' afterwards
- Replace doom-modules function with doom-modules-list
- The `with-plist!` macro was removed, since `cl-destructuring-bind`
  already serves that purpose well enough.
- core/autoload/packages.el was moved into core-packages.el
- bin/doom will no longer die if DOOMDIR or DOOMLOCALDIR don't have a
  trailing slash
- Introduces doom-debug-variables; a list of variables to toggle on
  doom/toggle-debug-mode.
- The sandbox has been updated to reflect the above changes, also:
  1. Child instances will no longer inherit the process environment of
     the host instance,
  2. It will no longer produce an auto-save-list directory in ~/.emacs.d
2020-05-15 01:33:52 -04:00
.github Fix github pull request templates 2020-04-30 18:32:06 -04:00
bin Backport bits of CLI rewrite 2020-05-15 01:33:52 -04:00
core Backport bits of CLI rewrite 2020-05-15 01:33:52 -04:00
docs Merge pull request #3109 from jsmestad/patch-4 2020-05-14 04:21:12 -04:00
modules Backport bits of CLI rewrite 2020-05-15 01:33:52 -04:00
test Add test/shell.nix files for Emacs 26 & HEAD 2020-01-09 22:56:26 -05:00
.gitignore Add test/.local*/ to gitignore 2020-01-09 22:56:26 -05:00
early-init.el Ensure menu/tool/scroll bars are disabled 2020-02-21 12:49:57 -05:00
init.el Backport bits of CLI rewrite 2020-05-15 01:33:52 -04:00
init.example.el General refactors, reformatting & comment revision 2020-04-23 23:56:17 -04:00
LICENSE
README.md UPDATE: "Contribute" link in toc of README.md 2020-05-11 02:19:26 +01:00

Doom Emacs

InstallDocumentationFAQScreenshotsContribute

Made with Doom Emacs Supports Emacs 26-27 Latest commit Build status: develop Discord Server

Doom Emacs Screenshot


Table of Contents

Introduction

It is a story as old as time. A stubborn, shell-dwelling, and melodramatic vimmer—envious of the features of modern text editors—spirals into despair before he succumbs to the dark side. This is his config.

Doom is a configuration framework for GNU Emacs tailored for Emacs bankruptcy veterans who want less framework in their frameworks, a modicum of stability (and reproducibility) from their package manager, and the performance of a hand rolled config (or better). It can be a foundation for your own config or a resource for Emacs enthusiasts to learn more about our favorite operating system.

Its design is guided by these mantras:

  • Gotta go fast. Startup and run-time performance are priorities. Doom goes beyond by modifying packages to be snappier and load lazier.
  • Close to metal. There's less between you and vanilla Emacs by design. That's less to grok and less to work around when you tinker. Internals ought to be written as if reading them were part of Doom's UX, and it is!
  • Opinionated, but not stubborn. Doom is about reasonable defaults and curated opinions, but use as little or as much of it as you like.
  • Your system, your rules. You know better. At least, Doom hopes so! It won't automatically install system dependencies (and will force plugins not to either). Rely on doom doctor to tell you what's missing.
  • Nix/Guix was a great idea! The Emacs ecosystem is temperamental. Things break and they break often. Disaster recovery should be a priority! Doom's package management should be declarative and your private config reproducible, and comes with a means to roll back releases and updates (still a WIP).

Check out the FAQ for answers to common questions about the project.

Features

  • Minimalistic good looks inspired by modern editors.
  • Curated and sane defaults for many packages, (major) OSes, and Emacs itself.
  • A modular organizational structure for separating concerns in your config.
  • A standard library designed to simplify your elisp bike shedding.
  • A declarative package management system (powered by straight.el) with a command line interface. Install packages from anywhere, not just (M)ELPA, and pin them to any commit.
  • Optional vim emulation powered by evil-mode, including ports of popular vim plugins like vim-sneak, vim-easymotion, vim-unimpaired and more!
  • Opt-in LSP integration for many languages, using lsp-mode.
  • Support for many programming languages. Includes syntax highlighting, linters/checker integration, inline code evaluation, code completion (where possible), REPLs, documentation lookups, snippets, and more!
  • Support for many tools, like docker, pass, ansible, terraform, and more.
  • A Spacemacs-esque keybinding scheme, centered around leader and localleader prefix keys (SPC and SPCm for evil users, C-c and C-c l for vanilla users).
  • A rule-based popup manager to control how temporary buffers are displayed (and disposed of).
  • Per-file indentation style detection and editorconfig integration. Let someone else can argue about tabs vs spaces.
  • Project-management tools and framework-specific minor modes with their own snippets libraries.
  • Project search (and replace) utilities, powered by ripgrep and ivy or helm.
  • Isolated and persistent workspaces (also substitutes for vim tabs).
  • Support for Chinese and Japanese input systems.
  • Save a snapshot of your shell environment to a file for Emacs to load at startup. No more struggling to get Emacs to inherit your PATH, among other things.

Prerequisites

  • Git 2.23+
  • Emacs 26.1+ (27 is recommended) with GNUTLS support
  • ripgrep 11.0+
  • GNU find
  • OPTIONAL: fd 7.3.0+ (improves file indexing performance for some commands)

Doom is comprised of ~150 optional modules, some of which may have additional dependencies. Visit their documentation or run bin/doom doctor to check for any that you may have missed.

Install

git clone --depth 1 https://github.com/hlissner/doom-emacs ~/.emacs.d
~/.emacs.d/bin/doom install

Then read our Getting Started guide to be walked through installing, configuring and maintaining Doom Emacs.

It's a good idea to add ~/.emacs.d/bin to your PATH! Other bin/doom commands you should know about:

  • doom sync to synchronize your private config with Doom. Installs new packages, removes orphaned packages and regenerates caches. Run this whenever you modify your private init.el or packages.el, or install/remove an Emacs package through your OS package manager (e.g. mu4e or agda).
  • doom upgrade to update Doom to the latest release & all installed packages.
  • doom doctor to diagnose common issues with your system and config.
  • doom env to dump a snapshot of your shell environment to a file that Doom will load at startup. This allows Emacs to inherit your PATH, among other things.
  • doom build to recompile all installed packages (use this if you up/downgrade Emacs).

Roadmap

Doom is an active and ongoing project. To make that development more transparent, its roadmap (and other concerns) are published across three github project boards and a newsletter:

  • Development Roadmap: roughly outlines our goals between release milestones and their progress.
  • Plugins under review: lists plugins we are watching and considering for inclusion, and what their status for inclusion is. Please consult this list before requesting new packages/features.
  • Upstream bugs: lists issues that originate from elsewhere, and whether or not we have local workarounds or temporary fixes for them.
  • Doom's newsletter (not finished) will contain changelogs in between releases.

Getting help

Emacs is no journey of a mere thousand miles. You will run into problems and mysterious errors. When you do, here are some places you can look for help:

  • Our documentation covers many use cases.
  • With Emacs built-in help system documentation is a keystroke away:
    • For functions: SPC h f or C-h f
    • For variables: SPC h v or C-h v
    • For a keybind: SPC h k or C-h k
    • To search available keybinds: SPC h b b or C-h b b
  • Run bin/doom doctor to detect common issues with your development environment and private config.
  • Check out the FAQ, in case your question has already been answered.
  • Search Doom's issue tracker in case your issue was already reported.
  • Hop on our Discord server; it's active and friendly! Keep an eye on the #announcements channel, where I announce breaking updates and releases.

Contribute

PRs Welcome Elisp styleguide Donate on liberapay Donate on paypal

Doom is a labor of love and incurable madness, but I'm only one guy. Doom wouldn't be where it is today without your help. I welcome contributions of any kind!

  • I ❤️ pull requests and bug reports (see the Contributing Guidelines)!
  • Don't hesitate to tell me my Elisp-fu sucks, but please tell me why.
  • Hop on our Discord server and say hi! Help others, hang out or talk to me about Emacs, gamedev, programming, physics, pixel art, anime, gaming -- anything you like. Nourish this lonely soul.
  • If you'd like to support my work financially, buy me a drink through liberapay or paypal. My work contends with studies, adventures in indie gamedev and freelance work. Donations help me allocate more time to my Emacs and OSS capers.