emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
doomemacs/docs/faq.org
Henrik Lissner dd402b7db3
Remove references to enh-ruby-mode
2020-03-12 11:29:54 -04:00

1068 lines
50 KiB
Org Mode
Raw Blame History

#+TITLE: Frequently Asked Questions
#+STARTUP: nofold
* Table of Contents :TOC:
- [[#general][General]]
- [[#why-is-it-called-doom][Why is it called Doom?]]
- [[#does-doom-work-on-windows][Does Doom work on Windows?]]
- [[#is-doom-only-for-vimmers][Is Doom only for vimmers?]]
- [[#i-am-a-beginner-can-i-use-doom][I am a beginner. Can I use Doom?]]
- [[#how-does-doom-compare-to-spacemacs][How does Doom compare to Spacemacs?]]
- [[#why-such-a-complicated-package-management-system][Why such a complicated package management system?]]
- [[#how-does-doom-start-up-so-quickly][How does Doom start up so quickly?]]
- [[#why-is-startup-time-important-why-not-use-the-daemon][Why is startup time important? Why not use the daemon?]]
- [[#how-do-i-use-doom-alongside-other-emacs-configs][How do I use Doom alongside other Emacs configs?]]
- [[#why-should-i-use-doom-instead-of-rolling-my-own-config][Why should I use Doom instead of rolling my own config?]]
- [[#what-is-the-meaning-behind-dooms-naming-conventions][What is the meaning behind Doom's naming conventions?]]
- [[#how-can-i-contribute-tosupport-doom][How can I contribute to/support Doom?]]
- [[#what-version-of-doom-am-i-running][What version of Doom am I running?]]
- [[#configuration][Configuration]]
- [[#should-i-fork-doom-to-customize-it][Should I fork Doom to customize it?]]
- [[#how-do-i-configure-doom-emacs][How do I configure Doom Emacs?]]
- [[#how-do-i-enable-or-disable-a-doom-module][How do I enable or disable a Doom module?]]
- [[#how-do-i-change-the-theme][How do I change the theme?]]
- [[#how-do-i-change-the-fonts][How do I change the fonts?]]
- [[#how-do-i-bind-my-own-keys-or-change-existing-ones][How do I bind my own keys (or change existing ones)?]]
- [[#how-do-i-get-motions-to-treat-underscores-as-word-delimiters][How do I get motions to treat underscores as word delimiters?]]
- [[#how-do-i-change-the-leaderlocalleader-keys][How do I change the leader/localleader keys?]]
- [[#how-do-i-change-the-style-of-line-numbers-or-disable-them-altogether][How do I change the style of line-numbers (or disable them altogether)?]]
- [[#how-do-i-change-the-behavior-and-appearance-of-popup-windows][How do I change the behavior and appearance of popup windows?]]
- [[#how-do-i-change-the-appearance-a-face-or-faces][How do I change the appearance a face (or faces)?]]
- [[#can-doom-be-customized-without-restarting-emacs][Can Doom be customized without restarting Emacs?]]
- [[#can-vimevil-be-removed-for-a-more-vanilla-emacs-experience][Can Vim/Evil be removed for a more vanilla Emacs experience?]]
- [[#should-i-use-make-or-bindoom][Should I use ~make~ or ~bin/doom~?]]
- [[#when-should-and-shouldnt-i-use-bindoom][When should and shouldn't I use ~bin/doom~?]]
- [[#when-to-run-doom-sync][When to run ~doom sync~]]
- [[#how-to-suppress-confirmation-prompts-while-bindoom-is-running][How to suppress confirmation prompts while ~bin/doom~ is running]]
- [[#package-management][Package Management]]
- [[#how-do-i-install-a-package-from-elpa][How do I install a package from ELPA?]]
- [[#how-do-i-install-a-package-from-githubanother-source][How do I install a package from github/another source?]]
- [[#how-do-i-change-where-an-existing-package-is-installed-from][How do I change where an existing package is installed from?]]
- [[#how-do-i-disable-a-package-completely][How do I disable a package completely?]]
- [[#how-do-i-reconfigure-a-package-included-in-doom][How do I reconfigure a package included in Doom?]]
- [[#where-does-straight-clonebuild-packages-to][Where does straight clone/build packages to?]]
- [[#defaults][Defaults]]
- [[#why-ivy-over-helm][Why Ivy over Helm?]]
- [[#why-are-there-no-default-keybinds-for-smartparens-for-evil-users][Why are there no default keybinds for Smartparens (for evil users)?]]
- [[#why-do-non-evil-users-get-expand-region-but-not-evil-users][Why do non-evil users get expand-region, but not evil users?]]
- [[#why-not-use-exec-path-from-shell-instead-of-doom-env][Why not use exec-path-from-shell instead of ~doom env~?]]
- [[#why-wsbutler-over-delete-trailing-whitespace-or-whitespace-cleanup][Why wsbutler over delete-trailing-whitespace or whitespace-cleanup?]]
- [[#common-issues][Common Issues]]
- [[#i-get-the-vanilla-emacs-splash-screen-at-startup][I get the vanilla Emacs splash screen at startup]]
- [[#i-see-a-blank-scratch-buffer-at-startup][I see a blank scratch buffer at startup]]
- [[#strange-or-incorrect-icons-are-displayed-everywhere][Strange (or incorrect) icons are displayed everywhere]]
- [[#void-variable-and-void-function-errors-on-startup][~void-variable~ and ~void-function~ errors on startup]]
- [[#doom-cant-find-my-executablesdoesnt-inherit-the-correct-path][Doom can't find my executables/doesn't inherit the correct ~PATH~]]
- [[#theres-artefacting-on-my-icon-fonts-in-gui-emacs-956][There's artefacting on my icon fonts in GUI Emacs (#956)]]
- [[#the-s-and-s-keys-dont-behave-like-they-do-in-vimevil-1307][The =s= and =S= keys don't behave like they do in vim/evil (#1307)]]
- [[#changes-to-my-config-arent-taking-effect][Changes to my config aren't taking effect]]
- [[#the-frame-goes-black-on-macos-while-in-full-screen-mode][The frame goes black on MacOS, while in full-screen mode]]
- [[#doom-crashes-when][Doom crashes when...]]
- [[#cant-load-my-theme-unable-to-find-theme-file-for-x-errors][Can't load my theme; ~unable to find theme file for X~ errors]]
- [[#tramp-connections-hang-forever-when-connecting][TRAMP connections hang forever when connecting]]
- [[#an-upstream-package-was-broken-and-i-cant-update-it][An upstream package was broken and I can't update it]]
- [[#why-do-i-see-ugly-indentation-highlights-for-tabs][Why do I see ugly indentation highlights for tabs?]]
- [[#contributing][Contributing]]
* General
** Why is it called Doom?
It's an homage to idsoftware's classic game, whose open sourced code was
Henrik's (Doom's maintainer) first exposure to programming.
And if you're obsessed enough with a text editor that you write a community
config for it, you're doomed from the start.
** Does Doom work on Windows?
Windows support is weak and generally lags behind Linux/MacOS support, so your
mileage will vary. However, some have reported success using Doom Emacs on
Windows (using WSL, WSL2 or scoop/chocolatey). You'll find install instructions
in the [[file:getting_started.org::On Windows][Getting Starting guide]].
If you're a Windows user, help us improve our documentation!
** Is Doom only for vimmers?
No, but it is Doom's primary audience. Its maintainer is a dyed-in-the-wool
vimmer with almost two decades of vim muscle memory, and he came to Emacs to
find a better vim.
Although Doom is less polished without evil, its growing non-evil user base is
slowly improving the situation. We welcome suggestions and PRs to help
accommodate a non-evil workflow.
If you'd still like a go at it, see the [[file:../modules/editor/evil/README.org::Removing evil-mode][removing evil-mode]] section in the
[[file:../modules/editor/evil/README.org][:editor evil]] module's documentation.
** I am a beginner. Can I use Doom?
If you're new to the terminal, to programming, or Emacs and/or vim, Doom (or
Emacs, for that matter) is a rough place to start. Neither Doom nor Emacs are
particularly beginner friendly. That's not to say it's impossible, or that we
won't help you if you ask, but expect a hefty commitment and a bumpy journey.
Remember to check out the [[file:index.org][Documentation]] for a guide to getting started.
** How does Doom compare to Spacemacs?
To paraphrase (and expand upon) a [[https://www.reddit.com/r/emacs/comments/6pa0oq/quickstart_tutorial_for_emacs_newbies_with_doom/dkp1bhd/][reddit answer]] to this question by [[https://github.com/gilbertw1][@gilbertw1]]:
+ *Doom is lighter than Spacemacs.* Doom starts up faster and is better
optimized, but Spacemacs has more features.
+ *Doom is thinner than Spacemacs.* There are fewer abstractions between you and
vanilla Emacs, and what abstractions do exist are thin by design. This means
there's less to understand and it's easier to hack.
+ *Doom is much more opinionated than Spacemacs.* Doom does not strive to be a
one-size-fits-all, beginner-friendly solution, nor is it configured by
consensus. It is [mostly] the work of one developer and caters to his
vim-slanted tastes. Doom's defaults enforce very particular (albeit optional)
workflows.
+ *Doom lacks manpower.* Bugs stick around longer, documentation is light and
development is at the mercy of it's single maintainer's schedule, health and
whims.
+ *Doom is not beginner friendly.* Spacemacs works out of the box. Your mileage
may vary with Doom; assembly is required! Familiarity with Emacs Lisp (or
programming in general), git and the command line will go a long way to ease
you into Doom.
+ *Doom manages its packages outside of Emacs.* Spacemacs installs (and checks
for packages) on startup or on demand. Doom leaves package management to be
done externally, through the ~bin/doom~ script. This allows for package
management to be scripted on the command line and enables a number of startup
optimizations we wouldn't have otherwise.
** Why such a complicated package management system?
Doom had +four+ *five* goals for its package management system:
1. *Scriptability:* package management should be shell-scriptable, so updating
can be automated.
2. *Reach:* allow users to install packages from sources other than ELPA (like
github or gitlab), and from specific commits, branches or tags. Some plugins
are out-of-date through official channels, have changed hands, have a
superior fork, or aren't available in ELPA repos.
3. *Performance:* lazy-loading the package management system is a tremendous
boon to start up speed. Initializing package.el and straight (and/or checking
that your packages are installed) each time you start up is expensive.
4. *Organization:* an Emacs configuration grows so quickly, in complexity and
size. A clear separation of concerns (configuration of packages from their
installation) is more organized.
5. *Reproducibility:* /This goal hasn't been implemented yet/, but all our work
up until now is aimed at this goal. Emacs is a tumultuous ecosystem; packages
break left and right, and we rely on hundreds of them. Eventually, we want
package versions to be locked to Doom's releases so that Doom installs are
reproducible.
** How does Doom start up so quickly?
Doom employs a number of techniques to cut down startup time. Here are its most
effective techniques:
*** Avoid garbage collection at startup
The GC can easily double startup time, so we suppress it at startup by turning
up ~gc-cons-threshold~ (and perhaps ~gc-cons-percentage~) temporarily:
#+BEGIN_SRC emacs-lisp
(setq gc-cons-threshold most-positive-fixnum ; 2^61 bytes
gc-cons-percentage 0.6)
;; ... your emacs config here ...
#+END_SRC
However, it is important to reset it eventually. Not doing so will cause garbage
collection freezes during long-term interactive use. Conversely, a
~gc-cons-threshold~ that is too small will cause stuttering. We use 16mb as our
default.
#+BEGIN_SRC emacs-lisp
(add-hook 'emacs-startup-hook
(lambda ()
(setq gc-cons-threshold 16777216 ; 16mb
gc-cons-percentage 0.1)))
#+END_SRC
It may also be wise to raise ~gc-cons-threshold~ while the minibuffer is active,
so the GC doesn't slow down expensive commands (or completion frameworks, like
helm and ivy). Here is how Doom does it:
#+BEGIN_SRC emacs-lisp
(defun doom-defer-garbage-collection-h ()
(setq gc-cons-threshold most-positive-fixnum))
(defun doom-restore-garbage-collection-h ()
;; Defer it so that commands launched immediately after will enjoy the
;; benefits.
(run-at-time
1 nil (lambda () (setq gc-cons-threshold doom-gc-cons-threshold))))
(add-hook 'minibuffer-setup-hook #'doom-defer-garbage-collection-h)
(add-hook 'minibuffer-exit-hook #'doom-restore-garbage-collection-h)
#+END_SRC
Another alternative (which is [[https://github.com/hlissner/doom-emacs/blob/develop/core/core.el#L269-L274][what Doom uses]]) is to use the [[https://gitlab.com/koral/gcmh/][gcmh]] package to
stave off the GC until you are idle or unfocus the Emacs frame.
*** Unset ~file-name-handler-alist~ temporarily
Emacs consults this variable every time a file is read or library loaded, or
when certain functions in the file API are used (like ~expand-file-name~ or
~file-truename~).
Emacs does to check if a special handler is needed to read that file, but none
of them are (typically) necessary at startup, so we disable them (temporarily!):
#+BEGIN_SRC emacs-lisp
(defvar doom--file-name-handler-alist file-name-handler-alist)
(setq file-name-handler-alist nil)
;; ... your whole emacs config here ...
;; Then restore it later:
(setq file-name-handler-alist doom--file-name-handler-alist)
;; Alternatively, restore it even later:
(add-hook 'emacs-startup-hook
(lambda ()
(setq file-name-handler-alist doom--file-name-handler-alist)))
#+END_SRC
Don't forget to restore ~file-name-handler-alist~, otherwise TRAMP won't work
and compressed/encrypted files won't open.
*** Concatenate package autoloads
When you install a package, a PACKAGE-autoloads.el file is generated. This file
contains a map of autoloaded functions and snippets declared by the package.
They tell Emacs where to find them when they are eventually called. In your
conventional Emacs config, every one of these autoloads files are loaded
immediately at startup (when ~package-initialize~ is called).
Since you'll commonly have hundreds of packages, loading hundreds of autoloads
file can hurt startup times, especially without an SSD. We get around this by
concatenating these files into one giant one when you run ~doom sync~.
Emacs 27+ introduces a ~package-quickstart~ command does this for you, and
=straight=, our package manager, does this for you too, but [[https://github.com/hlissner/doom-emacs/tree/develop/core/cli/autoloads.el][Doom Emacs has its
own specialized mechanism]] for this, topped off with a few Doom-specific
optimizations.
*** Lazy load package management system(s)
Initializing package.el or straight.el at startup is expensive. We can save some
time by delaying that initialization until we actually need these libraries (and
load them only when we're doing package management, e.g. when we run ~doom
sync~).
Among other things, ~doom sync~ does a lot for us. It generates concatenated
autoloads files; caches expensive variables like caches ~load-path~,
~Info-directory-list~ and ~auto-mode-alist~; and preforms all your package
management activities there -- far away from your interactive sessions.
How exactly Doom accomplishes all this is a long story, so here is a boiled-down
version you can use in your own configs (for package.el, not straight.el):
#+BEGIN_SRC emacs-lisp
(defvar cache-file "~/.emacs.d/cache/autoloads")
(defun initialize ()
(unless (load cache-file t t)
(setq package-activated-list nil)
(package-initialize)
(with-temp-buffer
(cl-pushnew doom-core-dir load-path :test #'string=)
(dolist (desc (delq nil (mapcar #'cdr package-alist)))
(let ((load-file-name (concat (package--autoloads-file-name desc) ".el")))
(when (file-readable-p load-file-name)
(condition-case _
(while t (insert (read (current-buffer))))
(end-of-file)))))
(prin1 `(setq load-path ',load-path
auto-mode-alist ',auto-mode-alist
Info-directory-list ',Info-directory-list)
(current-buffer))
(write-file (concat cache-file ".el"))
(byte-compile-file cache-file))))
(initialize)
#+END_SRC
You'll need to delete ~cache-files~ any time you install, remove, or update a
new package. You could advise ~package-install~ and ~package-delete~ to call
~initialize~ when they succeed, or make ~initialize~ interactive and call it
manually when necessary. Up to you!
Note: package.el is sneaky, and will initialize itself if you're not careful.
*Not on my watch, criminal scum!*
#+BEGIN_SRC emacs-lisp
;; in ~/.emacs.d/init.el (or ~/.emacs.d/early-init.el in Emacs 27)
(setq package-enable-at-startup nil ; don't auto-initialize!
;; don't add that `custom-set-variables' block to my init.el!
package--init-file-ensured t)
#+END_SRC
*** Lazy load more than everything
~use-package~ can defer your packages. Using it is a no-brainer, but Doom goes a
little further with lazy loading. There are some massive plugins out there. For
some of them, ordinary lazy loading techniques don't work. To name a few:
+ The =lang/org= module defers loading babel packages until their src blocks are
executed or read. You no longer need ~org-babel-do-load-languages~ in your
config -- in fact, you shouldn't use it at all!
+ Company and yasnippet are loaded as late as possible (waiting until the user
opens a non-read-only, file-visiting buffer (that isn't in fundamental-mode)).
+ The =evil-easymotion= package binds many keys, none of which are available
until you load the package. Instead of loading it at startup, =gs= is bound to
a command that loads the package, populates =gs=, then simulates the =gs= key
press as though those new keys had always been there.
+ Doom loads some packages "incrementally". i.e. after a few seconds of idle
time post-startup, Doom loads packages piecemeal (one dependency at a time)
while Emacs. It aborts if it detects input, as to make the process as subtle
as possible.
For example, instead of loading =org= (a giant package), it will load these
dependencies, one at a time, before finally loading =org=:
#+BEGIN_SRC elisp
(calendar find-func format-spec org-macs org-compat org-faces org-entities
org-list org-pcomplete org-src org-footnote org-macro ob org org-agenda
org-capture)
#+END_SRC
This ensures packages load as quickly as possible when you first load an org
file.
*** Use [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Lexical-Binding.html][lexical-binding]] everywhere
Add ~;; -*- lexical-binding: t; -*-~ to the top of your elisp files. This can
break code if you've written it to depend on undeclared dynamic variables, but
I've designed Doom not to.
This buys a small improvement in performance, but every little bit helps. You'll
find more about it in:
+ [[http://nullprogram.com/blog/2017/01/30/]["How to Write Fast(er) Emacs Lisp."]]
+ [[http://nullprogram.com/blog/2016/12/22/]["Some Performance Advantages of Lexical Scope."]]
** Why is startup time important? Why not use the daemon?
The central motivation for a config that starts up fast (aside from the learning
experience) was to have a viable alternative to vim for quick, one-shot editing
in the terminal (without ~-Q~).
Besides that, it happens to facilitate:
- Running multiple, independent instances of Emacs (e.g. on a per-project basis,
or for nix-shell users, or to isolate one instance for IRC from an instance
for writing code, etc).
- Quicker restarting of Emacs, to reload package settings or recover from
disastrous errors which can leave Emacs in a broken state.
- Faster integration with "edit in Emacs" solutions (like [[https://github.com/alpha22jp/atomic-chrome][atomic-chrome]]), and
without a daemon.
What's more, I believe a daemon shouldn't be necessary to get a sane startup
time out of Emacs.
** How do I use Doom alongside other Emacs configs?
I recommend [[https://github.com/plexus/chemacs][Chemacs]]. You can think of it as a bootloader for Emacs. You'll [[file:getting_started.org::*Alongside other Emacs configs (with Chemacs)][find
instructions on how to use it with Doom in the user manual]].
You'll still need a separate folder for personal configuration (=~/.doom.d= or
=~/.config/doom= by default), but the =--doomdir PATH= switch (or ~DOOMDIR~
environment variable) will allow you to use a different location:
#+BEGIN_SRC bash
# First install Doom somewhere
git clone https://github.com/hlissner/doom-emacs ~/fakehome/doom-emacs
# Then create a place to store our private doom configs. The bin/doom script
# recognizes the DOOMDIR environment variable.
export DOOMDIR=~/fakehome/doom-emacs-config
mkdir -p "$DOOMDIR"
# Set up Doom for the first time; this may take a while
cd ~/fakehome/doom-emacs
bin/doom install
# then launch Doom Emacs from this folder with:
bin/doom run
#+END_SRC
#+begin_quote
Warning: the way ~bin/doom run~ starts Doom bypasses many of its startup
optimizations. Treat it as a convenience for testing Doom, rather than a
permanent entry point.
#+end_quote
** Why should I use Doom instead of rolling my own config?
If you care about personalizing the software you use on a daily basis, even half
as much as I do, then you probably need professional help, but you also know it
is time consuming. Emacs out-of-the-box is a barren wasteland with archaic
defaults. Building anything out here and getting a feel for it will take /a lot/
of time. Time that I've already wasted and can never get back.
Time you could otherwise spend attending your daughter's dance recitals, that
baseball game your son's team almost won last Thursday, or answering the court
summons to fight for custody of your kids.
Also, Doom's fast yo.
** What is the meaning behind Doom's naming conventions?
You'll find [[file:contributing.org::*Conventions][an overview of Doom's code conventions]] in the [[file:contributing.org][contributing guide]].
** How can I contribute to/support Doom?
Take a look at the [[file:contributing.org][Contributing guide]].
** What version of Doom am I running?
You'll find the current version displayed in the modeline on the dashboard. It
can also be retrieved using ~M-x doom/version~ (bound to =SPC h d v= by default)
or ~doom info~ on the command line.
* Configuration
** Should I fork Doom to customize it?
No. Not unless you have a good reason for doing so (and you're comfortable with
the git-rebase workflow). Your customization can be relegated to =~/.doom.d/=
(or =~/.config/doom/=) entirely.
If you /must/ modify Doom proper to get something done, it's a code smell.
Visit the [[file:getting_started.org::*Customize][Customize section]] of [[file:getting_started.org][the Getting Started guide]] for details on how to
do this.
** How do I configure Doom Emacs?
Canonically, your private config is kept in =~/.doom.d/= or =~/.config/doom/=.
Doom will prioritize =~/.config/doom=, if it exists. This directory is referred
to as your ~$DOOMDIR~.
Your private config is typically comprised of an =init.el=, =config.el= and
=packages.el= file. Put all your config in =config.el=, install packages by
adding ~package!~ declarations to =packages.el=, and enable/disable modules in
you ~doom!~ block, which should have been created in your =init.el= when you
first ran ~doom install~.
Check out the [[file:getting_started.org::Customize][Customize section]] in the [[file:getting_started.org][Getting Started]] guide for details.
** How do I enable or disable a Doom module?
Comment or uncomment the module in your ~doom!~ block, found in
=$DOOMDIR/init.el=.
Remember to run ~bin/doom sync~ afterwards, on the command line, to sync your
module list with Doom.
See the "[[file:getting_started.org::*Configuration modules][Configuration modules]]" section of the [[file:getting_started.org][Getting Started]] guide for more
information.
** How do I change the theme?
There are two ways to load a theme. Both assume the theme is installed and
available. You can either set ~doom-theme~ or manually load a theme with the
~load-theme~ function.
#+BEGIN_SRC emacs-lisp
;;; add to ~/.doom.d/config.el
(setq doom-theme 'doom-tomorrow-night)
;; or
(load-theme 'doom-tomorrow-night t)
#+END_SRC
#+begin_quote
At the moment, the only difference between the two is that ~doom-theme~ is
loaded when Emacs has finished initializing at startup and ~load-theme~ loads
the theme immediately. Which you choose depends on your needs, but I recommend
setting ~doom-theme~ because, if I later discover a better way to load themes, I
can easily change how Doom uses ~doom-theme~, but I can't (easily) control how
you use the ~load-theme~ function.
#+end_quote
*** Installing a third party theme
To install a theme from a third party plugin, say, [[https://github.com/bbatsov/solarized-emacs][solarized]], you need only
install it, then load it:
#+BEGIN_SRC emacs-lisp
;;; add to ~/.doom.d/packages.el
(package! solarized-theme)
;;; add to ~/.doom.d/config.el
(setq doom-theme 'solarized-dark)
#+END_SRC
Don't forget to run ~doom sync~ after adding that ~package!~ statement to ensure
the package is installed.
** How do I change the fonts?
Doom exposes five (optional) variables for controlling fonts in Doom, they are:
+ ~doom-font~
+ ~doom-variable-pitch-font~
+ ~doom-serif-font~
+ ~doom-unicode-font~
+ ~doom-big-font~ (used for ~doom-big-font-mode~)
They all accept either a =font-spec=, font string (="Input Mono-12"=), or [[https://wiki.archlinux.org/index.php/X_Logical_Font_Description][xlfd
font string]].
e.g.
#+BEGIN_SRC emacs-lisp
;;; Add to ~/.doom.d/config.el
(setq doom-font (font-spec :family "Input Mono Narrow" :size 12 :weight 'semi-light)
doom-variable-pitch-font (font-spec :family "Fira Sans") ; inherits `doom-font''s :size
doom-unicode-font (font-spec :family "Input Mono Narrow" :size 12)
doom-big-font (font-spec :family "Fira Mono" :size 19))
#+END_SRC
** How do I bind my own keys (or change existing ones)?
The ~map!~ macro is recommended; it is a convenience macro that wraps around
Emacs' (and evil's) keybinding API, i.e. ~define-key~, ~global-set-key~,
~local-set-key~ and ~evil-define-key~.
You'll find comprehensive examples of ~map!~'s usage in its documentation (via
=SPC h f map!= or =C-h f map!= -- also found [[file:api.org][in docs/api]]).
You'll find a more comprehensive example of ~map!~'s usage in
[[file:../modules/config/default/+evil-bindings.el][config/default/+evil-bindings.el]].
** How do I get motions to treat underscores as word delimiters?
(This explanation comes from [[https://github.com/emacs-evil/evil#underscore-_-is-not-a-word-character][emacs-evil/evil]]'s readme)
An underscore "_" is a word character in Vim. This means that word-motions like
=w= skip over underlines in a sequence of letters as if it was a letter itself.
In contrast, in Evil the underscore is often a non-word character like
operators, e.g. =+=.
The reason is that Evil uses Emacs' definition of a word and this definition
does not often include the underscore. Word characters in Emacs are determined
by the syntax-class of the buffer. The syntax-class usually depends on the
major-mode of this buffer. This has the advantage that the definition of a
"word" may be adapted to the particular type of document being edited. Evil uses
Emacs' definition and does not simply use Vim's definition in order to be
consistent with other Emacs functions. For example, word characters are exactly
those characters that are matched by the regular expression character class
~[:word:]~.
If you want the underscore to be recognized as word character, you can modify
its entry in the syntax-table:
#+BEGIN_SRC emacs-lisp
(modify-syntax-entry ?_ "w")
#+END_SRC
This gives the underscore the word syntax-class. You can use a mode-hook to
modify the syntax-table in all buffers of some mode, e.g.:
#+BEGIN_SRC emacs-lisp
;; For python
(add-hook! 'python-mode-hook (modify-syntax-entry ?_ "w"))
;; For ruby
(add-hook! 'ruby-mode-hook (modify-syntax-entry ?_ "w"))
;; For Javascript
(add-hook! 'js2-mode-hook (modify-syntax-entry ?_ "w"))
#+END_SRC
** How do I change the leader/localleader keys?
These variables control what key to use for leader and localleader keys:
+ For Evil users:
+ ~doom-leader-key~ (default: =SPC=)
+ ~doom-localleader-key~ (default: =SPC m=)
+ For Emacs and Insert state (evil users), and non-evil users:
+ ~doom-leader-alt-key~ (default: =M-SPC= for evil users, =C-c= otherwise)
+ ~doom-localleader-alt-key~ (default: =M-SPC m= for evil users, =C-c l=
otherwise)
e.g.
#+BEGIN_SRC emacs-lisp
;;; add to ~/.doom.d/config.el
(setq doom-leader-key ","
doom-localleader-key "\\")
#+END_SRC
** How do I change the style of line-numbers (or disable them altogether)?
Doom uses the ~display-line-numbers~ package, which is built into Emacs 26+.
*** Disabling line numbers entirely
#+BEGIN_SRC elisp
;;; add to ~/.doom.d/config.el
(setq display-line-numbers-type nil)
;; or
(remove-hook! '(prog-mode-hook text-mode-hook conf-mode-hook)
#'display-line-numbers-mode)
#+END_SRC
*** Switching to relative line numbers (permanently)
To change the style of line numbers, change the value of the
~display-line-numbers-type~ variable. It accepts the following values:
#+begin_example
t normal line numbers
'relative relative line numbers
'visual relative line numbers in screen space
nil no line numbers
#+end_example
For example:
#+BEGIN_SRC elisp
;;; add to ~/.doom.d/config.el
(setq display-line-numbers-type 'relative)
#+END_SRC
You'll find more precise documentation on the variable through =<help> v
display-line-numbers-type= (=<help>= is =SPC h= for evil users, =C-h=
otherwise).
*** Switching the style of line numbers (temporarily)
Use ~M-x doom/toggle-line-numbers~ (bound to =SPC t l= by default) to cycle
through the available line number styles in the current buffer.
e.g. =normal -> relative -> visual -> disabled -> normal=.
** How do I change the behavior and appearance of popup windows?
The =:ui popup= module tries to standardize how Emacs handles "temporary"
windows. It includes a set of default rules that tell Emacs where to open them
(and how big they should be).
Check out the [[file:../modules/ui/popup/README.org::Configuration][:ui popup module's documentation]] for more on defining your own
rules.
You'll find more comprehensive documentation on ~set-popup-rule!~ in its
docstring (available through =SPC h f= -- or =C-h f= for non-evil users).
** How do I change the appearance a face (or faces)?
Doom provides the ~custom-set-faces!~ and ~custom-theme-set-faces!~ macros as a
convenience.
#+begin_quote
*Do not use ~M-x customize~ or any of the built-in Emacs customize-* API.* Doom
does not support it and never will; those settings could break at any time.
#+end_quote
See =<help> f custom-set-faces\!= (or =M-x helpful-function custom-set-faces\!=)
for documentation and examples on how to use it. =<help>= is =SPC h= for evil
users and =C-h= for non-evil users.
** Can Doom be customized without restarting Emacs?
Short answer: You can, but you shouldn't.
Long answer: Restarting Emacs is always your safest bet, but Doom provides a few
tools for experienced Emacs users to skirt around it (most of the time):
- Evaluate your changes on-the-fly with ~+eval/region~ (bound to the =gr=
operator for evil users) or ~eval-last-sexp~ (bound to =C-x C-e=). Changes
take effect immediately.
- On-the-fly evaluation won't work for all changes. e.g. Changing your ~doom!~
block (i.e. the list of modules for Doom to enable).
But rather than running ~doom sync~ and restarting Emacs, Doom provides ~M-x
doom/reload~ for your convenience (bound to =SPC h r r= and =C-h r r=). This
runs ~doom sync~, restarts the Doom initialization process and re-evaluates
your personal config. However, this won't clear pre-existing state; Doom won't
unload modules/packages that have already been loaded and it can't anticipate
complications arising from a private config that isn't idempotent.
- Some ~bin/doom~ commands are available as elisp commands. e.g. ~doom/reload~
for ~doom sync~, ~doom/upgrade~ for ~doom upgrade~ ~doom//s~, ~doom//update~, etc. Feel free to use them, but
consider them highly experimental and subject to change without notice.
- You can quickly restart Emacs and restore the last session with
~doom/restart-and-restore~ (bound to =SPC q r=).
** Can Vim/Evil be removed for a more vanilla Emacs experience?
Yes! See the [[file:../modules/editor/evil/README.org::Removing evil-mode][Removing evil-mode]] section in [[file:../modules/editor/evil/README.org][:editor evil]]'s documentation.
** Should I use ~make~ or ~bin/doom~?
~bin/doom~ is recommended. Doom's Makefile (to manage your config, at least) is
deprecated. It forwards to ~bin/doom~ anyway.
** When should and shouldn't I use ~bin/doom~?
~bin/doom~ is your best friend. It'll keep all your secrets (mostly because it's
a shell script incapable of sentience and thus incapable of retaining, much less
divulging, your secrets to others).
You can run ~bin/doom help~ to see what it's capable of, but here are some
commands that you may find particularly useful:
+ ~doom doctor~ :: Diagnose common issues in your environment and list missing
external dependencies for your enabled modules.
+ ~doom sync~ :: Ensures that all missing packages are installed, orphaned
packages are removed, and metadata properly generated.
+ ~doom install~ :: Install any missing packages.
+ ~doom update~ :: Update all packages that Doom's (enabled) modules use.
+ ~doom env~ :: Regenerates your envvar file, which contains a snapshot of your
shell environment for Doom Emacs to load on startup. You need to run this for
changes to your shell environment to take effect.
+ ~doom purge -g~ :: Purge orphaned packages (i.e. ones that aren't needed
anymore) and regraft your repos.
+ ~doom upgrade~ :: Upgrade Doom to the latest version (then update your
packages). This is equivalent to:
#+BEGIN_SRC bash
git pull
doom sync
doom update
#+END_SRC
** When to run ~doom sync~
As a rule of thumb you should run ~doom sync~ whenever you:
+ Update Doom with ~git pull~ instead of ~doom upgrade~,
+ Change your ~doom!~ block in =$DOOMDIR/init.el=,
+ Change autoload files in any module (or =$DOOMDIR=),
+ Or change the packages.el file in any module (or =$DOOMDIR=).
+ Install an Emacs package or dependency outside of Emacs (i.e. through your OS
package manager).
If anything is misbehaving, it's a good idea to run ~doom sync~ first. ~doom
sync~ is responsible for regenerating your autoloads file (which tells Doom
where to find lazy-loaded functions and libraries), installing missing packages,
and uninstall orphaned (unneeded) packages.
** How to suppress confirmation prompts while ~bin/doom~ is running
The ~-y~ and ~--yes~ flags (or the ~YES~ environment variable) will force
~bin/doom~ to auto-accept confirmation prompts:
#+BEGIN_SRC bash
doom -y update
doom --yes update
YES=1 doom update
#+END_SRC
* Package Management
** How do I install a package from ELPA?
See the "[[file:getting_started.org::*Installing packages][Installing packages]]" section of the [[file:getting_started.org][Getting Started]] guide.
** How do I install a package from github/another source?
See the "[[file:getting_started.org::*Installing packages from external sources][Installing packages from external sources]]" section of the [[file:getting_started.org][Getting
Started]] guide.
** How do I change where an existing package is installed from?
See the "[[file:getting_started.org::*Changing a recipe for a included package][Changing a recipe for a included package]]" section of the [[file:getting_started.org][Getting
Started]] guide.
** How do I disable a package completely?
See the "[[file:getting_started.org::*Disabling packages][disabling packages]]" section of the [[file:getting_started.org][Getting Started]] guide.
** How do I reconfigure a package included in Doom?
See the "[[file:getting_started.org::*Configuring packages][configuring packages]]" section of the Getting Started guide.
** Where does straight clone/build packages to?
Straight clones packages to =~/.emacs.d/.local/straight/repos/REPO-NAME=, then
later symlinks and byte-compiles them to
=~/.emacs.d/.local/straight/build/PACKAGE-NAME= when they are "built".
* Defaults
** Why Ivy over Helm?
Short answer: ivy is simpler to maintain.
Long answer: Features and performance appear to be the main talking points when
comparing the two, but as far as I'm concerned they are equal in both respects
(not all across the board, but on average).
Instead, what is important to me is maintainability. As someone who frequently
extends and debugs his editor (and maintains a community config), I frequently
run up against issues with ivy and helm, but spend disproportionally more time
doing so with helm than I do ivy, for little or no gain. Though both frameworks
are excellent, the difference in complexity is also reflected in their plugin
ecosystems; ivy plugins tend to be lighter, simpler, more consistent and
significantly easier to hack if I want to change something. Unless you like helm
/just/ the way it is out of the box, ivy is just the simpler choice.
And since I dogfood it, Ivy's integration into Doom will always be a step or
three ahead of helm's.
** Why are there no default keybinds for Smartparens (for evil users)?
Doom only uses smartparens to manage pair "completion" (it does the job better
than electric-{pair,quote}-mode or the multitude of other pair-management
solutions in the Emacs ecosystem at the time of writing).
None of smartparen's commands have default keybinds for evil users because they
are redundant with motions and text-objects provided by evil/vim. If you
disagree, I recommend trying the =:editor lispy= or =:editor parinfer= modules.
** Why do non-evil users get expand-region, but not evil users?
~expand-region~ is redundant with and less precise than evil's text objects and
motions.
- There's a text object for every "step" of expansion that expand-region
provides (and more). To select the word at point = =viw=, symbol at point =
=vio=, line at point = =V=, the block at point (by indentation) = =vii=, the
block at point (by braces) = =vib=, sentence at point = =vis=, paragraph =
=vip=, and so on.
- Selection expansion can be emulated by using text objects consecutively: =viw=
to select a word, followed by =io= to expand to a symbol, then =ib= expands to
the surrounding brackets/parentheses, etc. There is no reverse of this
however; you'd have to restart visual state.
The expand-region way dictates you start at some point and expand/contract until
you have what you want selected. The vim/evil way would rather you select
exactly what you want from the get go. In the rare event a text object fails
you, a combination of =o= (swaps your cursor between the two ends of the region)
and motion keys can adjust the ends of your selection.
#+BEGIN_QUOTE
There are also text objects for xml tags (=x=), C-style function arguments
(=a=), angle brackets, and single/double quotes.
#+END_QUOTE
This is certainly more to remember compared to a pair of expand and contract
commands, but text objects (and motions) are the bread and butter of vim's modal
editing paradigm. Vimmers will feel right at home. To everyone else: mastering
them will have a far-reaching effect on your productivity. I highly recommend
putting in the time to learn them.
Otherwise, it is trivial to install expand-region and binds keys to it yourself:
#+BEGIN_SRC elisp
;;; add to ~/.doom.d/packages.el
(package! expand-region)
;;; add to ~/.doom.d/config.el
(map! :nv "C-=" #'er/contract-region
:nv "C-+" #'er/expand-region)
#+END_SRC
** Why not use exec-path-from-shell instead of ~doom env~?
The ~doom env~ approach is a faster and more reliable solution.
1. ~exec-path-from-shell~ must spawn (at least) one process at startup to scrape
your shell environment. This can be slow depending on the user's shell
configuration. A single program (like pyenv or nvm) or config framework (like
oh-my-zsh) could undo Doom's startup optimizations in one fell swoop.
2. ~exec-path-from-shell~ takes a whitelist approach and captures only ~PATH~
and ~MANPATH~ by default. You must be proactive in order to capture all the
envvars relevant to your development environment and tools.
~doom env~ takes the blacklist approach and captures all of your shell
environment. This front loads the debugging process, which is nicer than dealing
with it later, while you're getting work done.
That said, if you still want ~exec-path-from-shell~, it is trivial to install
yourself:
#+BEGIN_SRC emacs-lisp
;;; add to ~/.doom.d/packages.el
(package! exec-path-from-shell)
;;; add to ~/.doom.d/config.el
(require 'exec-path-from-shell)
(when (display-graphic-p)
(exec-path-from-shell-initialize))
#+END_SRC
** Why wsbutler over delete-trailing-whitespace or whitespace-cleanup?
TL;DR: =ws-butler= is less imposing.
Don't be that guy who PRs 99 whitespace adjustments around his one-line
contribution. Don't automate this aggressive behavior by attaching
~delete-trailing-whitespace~ (or ~whitespace-cleanup~) to ~before-save-hook~. If
you have rambunctious colleagues peppering trailing whitespace into your
project, you need to have a talk (with wiffle bats, preferably) rather than play
a passive-aggressive game of whack-a-mole.
Here at Doom Inc we believe that operations that mutate entire files should not
be automated. Rather, they should be invoked deliberately, when and where it is
needed, by someone that is aware of the potential consequences. This is where
=ws-butler= comes in. It only cleans up whitespace /on the lines you've touched/
*and* it leaves behind virtual whitespace (which is never written to the file)
so your cursor doesn't get thrown around in all that cleanup work.
In any case, if you had used =ws-butler= from the beginning, trailing whitespace
and newlines would never be a problem!
* Common Issues
** I get the vanilla Emacs splash screen at startup
The most common cause for this is a =~/.emacs= file. If it exists, Emacs will
read this file instead of the =~/.emacs.d= directory, ignoring Doom altogether.
If this isn't the case, try running ~bin/doom doctor~. It can detect a variety
of common issues and may give you some clues as to what is wrong.
** I see a blank scratch buffer at startup
This commonly means that Emacs can't find your private doom config (in
=~/.doom.d= or =~/.config/doom=). Make sure *only one of these two* folders
exist, and that it has an init.el file with a ~doom!~ block. Running ~doom
install~ will populate your private doom directory with the bare minimum you
need to get going.
If nothing else works, try running ~bin/doom doctor~. It can detect a variety of
common issues and may give you some clues as to what is wrong.
** Strange (or incorrect) icons are displayed everywhere
Many of Doom's UI modules use the =all-the-icons= plugin, which uses special
fonts to display icons. These fonts must be installed for them to work properly,
otherwise you'll get a bunch of squares and mismatched icons. When running ~doom
install~, you will be asked whether you want these installed for you or not.
If you did not accept or need to reinstall those fonts, MacOS and Linux users
can install them with ~M-x all-the-icons-install-fonts~. Windows users will need
to use this command to download the fonts somewhere, then they must install them
manually (e.g. by double-clicking each file in explorer).
** ~void-variable~ and ~void-function~ errors on startup
The most common culprit for these types of errors are:
1. An out-of-date autoloads file. Run ~doom sync~ to regenerate them.
To avoid this issue, remember to run ~doom sync~ whenever you modify your
~doom!~ block in =~/.doom.d/init.el=, or add ~package!~ declarations to
=~/.doom.d/packages.el=. Or if you modify =~/.emacs.d/.local= by hand, for
whatever reason.
See ~doom help sync~ for details on what this command does and when you
should use it.
2. Emacs byte-code isn't forward compatible. If you've recently switched to a
newer (or older) version of Emacs, you'll need to either reinstall or
recompile your installed plugins. This can be done by:
+ Running ~doom build~,
+ Or deleting =~/.emacs.d/.local/straight= then running ~doom install~ (this
will take a while).
** Doom can't find my executables/doesn't inherit the correct ~PATH~
The two most common causes for PATH issues in Doom are:
1. Your shell configuration doesn't configure ~PATH~ correctly. If ~which
<PROGRAM>~ doesn't emit the path you expect on the command line then this is
likely the case.
2. Your app launcher (rofi, albert, docky, dmenu, sxhkd, etc) is launching Emacs
with the wrong shell, either because it defaults to a different shell from
the one you use or the app launcher itself inherits the wrong environment
because /it/ was launched from the wrong shell.
3. You're a Mac user launching Emacs from an Emacs.app bundle. MacOS launches
these apps from an isolated environment.
As long as your shell is properly configured, there is a simple solution to
issues #1 and #3: generate an envvar file by running ~doom env~. This scrapes
your shell environment into a file that is loaded when Doom Emacs starts up.
Check out ~doom help env~ for details on how this works.
For issue #2, you'll need to investigate your launcher. [[https://discord.gg/qvGgnVx][Our Discord]] is a good
place to ask about it.
** There's artefacting on my icon fonts in GUI Emacs ([[https://github.com/hlissner/doom-emacs/issues/956][#956]])
Check your font rendering settings. Changing the RGBA order to "rgba" will often
fix this issue. See [[https://github.com/hlissner/doom-emacs/issues/956][#956]] for details.
** The =s= and =S= keys don't behave like they do in vim/evil ([[https://github.com/hlissner/doom-emacs/issues/1307][#1307]])
This is intentional. =s= and =S= have been replaced by the evil-snipe plugin,
which provides 2-character versions of the f/F motion keys, ala vim-seek or
vim-sneak.
These keys were changed because they are redundant with =cl= and =cc=
respectively (and the new behavior was deemed more useful).
If you still want to restore the old behavior, simply disable evil-snipe-mode:
#+BEGIN_SRC emacs-lisp
;; in ~/.doom.d/config.el
(after! evil-snipe
(evil-snipe-mode -1))
#+END_SRC
** Changes to my config aren't taking effect
1. Make sure you don't have both =~/.doom.d= and =~/.config/doom= directories.
Doom will ignore the former if the latter exists.
2. Remember to run ~doom sync~ when it is necessary. To get to know when,
exactly, you should run this command, run ~doom help sync~.
If neither of these solve your issue, try ~bin/doom doctor~. It will detect a
variety of common issues, and may give you some clues as to what is wrong.
** The frame goes black on MacOS, while in full-screen mode
There are known issues with childframes and macOS's fullscreen mode. There is no
known fix for this. To work around it, you must either:
1. Avoid MacOS native fullscreen by maximizing Emacs instead,
2. Disable childframes (controlled by the =+childframe= flag on the modules that
support it),
3. Install Emacs via the =emacs-mac= homebrew formula.
** Doom crashes when...
Here are a few common causes for random crashes:
+ You have enabled ~undo-tree-auto-save-history~. A bloated cache for a
particular file can cause a stack overflow. These caches are stored in
=~/.emacs.d/.local/cache/undo-tree-hist/=. Delete this folder to clear it.
+ On some systems (particularly MacOS), manipulating the fringes or window
margins can cause Emacs to crash. This is most prominent in the Doom Dashboard
(which tries to center its contents), in org-mode buffers (which uses
~org-indent-mode~ to create virtual indentation), or magit. There is currently
no known fix for this, as it can't be reliably reproduced. Your best bet is to
reinstall/rebuild Emacs or disable the errant plugins/modules. e.g.
To disable org-indent-mode:
#+BEGIN_SRC emacs-lisp
(after! org
(setq org-startup-indented nil))
#+END_SRC
Or disable the =:ui doom-dashboard= & =:tools magit= modules (see [[https://github.com/hlissner/doom-emacs/issues/1170][#1170]]).
** Can't load my theme; ~unable to find theme file for X~ errors
This means Emacs can't find the X-theme.el file for the theme you want to load.
Emacs will search for this file in ~custom-theme-load-path~ and
~custom-theme-directory~. There are a couple reasons why it can't be found:
1. It is generally expected that third party themes will [[https://github.com/hlissner/emacs-doom-themes/blob/master/doom-themes.el#L400-L405][add themselves]] to
~custom-theme-load-path~, but you will occasionally encounter a theme that
does not. This should be reported upstream.
In the meantime, you can get around this by eagerly loading the package:
#+BEGIN_SRC elisp
(require 'third-party-theme)
(setq doom-theme 'third-party)
#+END_SRC
2. You've appended ~-theme~ to the end of your theme's name.
#+BEGIN_SRC elisp
(setq doom-theme 'third-party-theme)
#+END_SRC
When you load a theme Emacs searches for ~X-theme.el~. If you set
~doom-theme~ to ~'third-party-theme~, it will search for
~third-party-theme-theme.el~. This is rarely intentional. Omit the ~-theme~
suffix.
3. Did you run ~doom sync~ after adding your third party theme plugin's
~package!~ declaration to =~/.doom.d/packages.el=?
** TRAMP connections hang forever when connecting
You'll find solutions [[https://www.emacswiki.org/emacs/TrampMode#toc7][on the emacswiki]].
** An upstream package was broken and I can't update it
Sometimes, if you've installed a [[https://github.com/hlissner/doom-emacs/issues/2213][broken package]] which was subsequently fixed
upstream, you can't run ~doom update~ to get the latest fixes due to evaluation
errors.
In those cases, you need to delete the broken local copy before you can install
the new one, which is achieved by either deleting it from
=~/.emacs.d/.local/straight/repos=, or by cycling the module that installs it:
1. Comment out the broken module/package.
2. Run ~doom sync~.
3. Uncomment the module/package.
4. Run ~doom sync~.
** Why do I see ugly indentation highlights for tabs?
[[https://github.com/hlissner/doom-emacs/blob/develop/core/core-ui.el#L132-L150][Doom highlights non-standard indentation]]. i.e. Indentation that doesn't match
the indent style you've set for that file. Spaces are Doom's default style for
most languages (excluding languages where tabs are the norm, like Go).
There are a couple ways to address this:
1. Fix your indentation! If it's highlighted, you have tabs when you should have
spaces (or spaces when you should be using tabs).
Two easy commands for that:
- =M-x tabify=
- =M-x untabify=
2. Change ~indent-tabs-mode~ (nil = spaces, t = tabs) in =~/.doom.d/config.el=:
#+BEGIN_SRC elisp
;; use tab indentation everywhere
(setq-default indent-tabs-mode t)
;; or only in certain modes
(setq-hook! 'sh-mode-hook indent-tabs-mode t) ; shell scripts
(setq-hook! '(c-mode-hook c++-mode-hook) indent-tabs-mode t) ; C/C++
#+END_SRC
3. Use [[https://editorconfig.org/][editorconfig]] to configure code style on a per-project basis. If you
enable Doom's =:tools editorconfig= module, Doom will recognize
=.editorconfigrc= files.
4. Or trust in dtrt-indent; a plugin Doom uses to analyze and detect indentation
when you open a file (that isn't in a project with an editorconfig file).
This isn't foolproof, and won't work for files that have no content in them,
but it can help in one-off scenarios.
* TODO Contributing
Reference in a new issue View git blame Copy permalink