doomemacs/modules/editor/evil/README.org

:editor evil

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
• Usage
  • Ported vim plugins
  • Custom Text Objects
  • Custom Ex Commands
• Configuration
• Troubleshooting
  • Can't access the universal argument key (C-u)
  • The s/S keys behave differently from Vim
  • The Y key behaves differently from Vim (should yank the whole line)
• Frequently asked questions
  • How do I remove evil?
  • Include underscores in evil word motions?
• Appendix

Description   unfold

This holy module brings the Vim editing model to Emacs.

Maintainers

• @hlissner

Become a maintainer?

Module flags

+everywhere

Enable evilified keybinds everywhere possible. Uses the evil-collection plugin as a foundation.

Packages

• evil
• evil-args
• evil-collection if +everywhere
• evil-easymotion
• evil-embrace
• evil-escape
• evil-exchange
• evil-indent-plus
• evil-lion
• evil-nerd-commentary
• evil-numbers
• evil-quick-diff
• evil-snipe
• evil-surround
• evil-textobj-anyblock
• evil-vimish-fold
• evil-visualstar
• exato

Hacks

• The o/O keys will respect and continue commented lines (can be disabled by setting +evil-want-o/O-to-continue-comments to nil).
• In visual mode, * and # will search for the current selection instead of the word-at-point.
• The :g[lobal] ex command has been modified to highlight matches.
• More of vim's filename modifiers are supported in ex commands (like :p, :p:h or :t) than vanilla evil-mode offers.
• A custom filename modifier is available in Doom: :P, which expands to the project root (throws an error if not in a project).

TODO Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

This module has no external requirements.

TODO Usage

🔨 This module's usage documentation is incomplete. Complete it?

Ported vim plugins

The following vim plugins have been ported to evil:

Vim Plugin	Emacs Plugin	Keybind(s)
vim-commentary	evil-nerd-commenter	omap gc
vim-easymotion	evil-easymotion	omap gs
vim-lion	evil-lion	omap gl / gL
vim-seek or vim-sneak	evil-snipe	mmap s / S, omap z / Z & x / X
vim-surround	evil-embrace and evil-surround	vmap S, omap ys
vim-unimpaired	(provided by Doom)	see the list

This module has also ported vim-unimpaired keybinds to Emacs.

In other modules:

• The :ui neotree & :ui treemacs modules provide a NERDTree equivalent.

• The :editor multiple-cursors module contains functionality equal to the following vim plugins:

  • evil-multiedit => vim-multiedit
  • evil-mc => vim-multiple-cursors

Custom Text Objects

This module provides a couple extra text objects, along with the built-in ones. For posterity, here are the built-in ones:

• w W words
• s sentences
• p paragraphs
• b parenthesized blocks
• d:][b ( ) { } [ ] < >]] braces, parentheses and brackets
• ' " ` quotes
• t tags
• o symbols

And these are text objects added by this module:

• a C-style function arguments (provided by evil-args)
• B any block delimited by braces, parentheses or brackets (provided by evil-textobj-anyblock)
• c Comments
• f For functions (but relies on the major mode to have sane definitions for beginning-of-defun-function and end-of-defun-function)
• g The entire buffer
• i j k by indentation (k includes one line above; j includes one line above and below) (provided by evil-indent-plus)
• q For quotes (any kind)
• u For URLs
• x XML attributes (provided by exato)

Custom Ex Commands

Ex Command	Description
:@	Apply macro on selected lines
:al[ign][!] REGEXP	Align text to the first match of REGEXP. If BANG, align all matches on each line
:cp[!] NEWPATH	Copy the current file to NEWPATH
:dash QUERY	Look up QUERY (or the symbol at point) in dash docsets
:dehtml [INPUT]	HTML decode selected text / inserts result if INPUT is given
:enhtml [INPUT]	HTML encode selected text / inserts result if INPUT is given
:iedit REGEXP	Invoke iedit on all matches for REGEXP
:k[ill]all[!]	Kill all buffers (if BANG, affect buffer across workspaces)
:k[ill]b	Kill all buried buffers
:k[ill]m[!] REGEXP	Kill buffers whose name matches REGEXP (if BANG, affect buffers across workspaces)
:k[ill]o	Kill all other buffers besides the selected one
:k[ill]	Kill the current buffer
:lo[okup] QUERY	Look up QUERY on an online search engine
:mc REGEXP	Invoke multiple cursors on all matches for REGEXP
:mv[!] NEWPATH	Move the current file to NEWPATH
:na[rrow]	Narrow the buffer to the selection
:pad	Open a scratch pad for running code quickly
:ral[ign][!] REGEXP	Right-Align text that matches REGEXP. If BANG, align all matches on each line
:repl	Open a REPL and/or copy the current selection to it
:retab	Convert indentation to the default within the selection
:rev[erse]	Reverse the selected lines
:rm[!] [PATH]	Delete the current buffer's file and buffer
:tcd[!]	Send cd X to tmux. X = the project root if BANG, X = default-directory otherwise

TODO Configuration

🔨 This module has no configuration documentation yet. Write some?

Troubleshooting

Report an issue?

Can't access the universal argument key (C-u)

For maximum Vim emulation, this module commandeers the C-u key for scrolling (as it does in Vim). The same goes for C-u in insert mode (which deletes to BOL). In both cases the universal argument has been moved to <leader> u.

To undo this, use:

;; add to $DOOMDIR/config.el
(setq! evil-want-C-u-scroll nil
       evil-want-C-u-delete nil)

The s/S keys behave differently from Vim

Doom replaces the s and S keys with the evil-snipe package (a port of vim-seek/vim-sneak for 2-character versions of f/F/t/T).

To disable evil-snipe on s/S, you can either:

1. Disable evil-snipe-mode by adding (remove-hook 'doom-first-input-hook #'evil-snipe-mode) to $DOOMDIR/config.el,
2. Or disable evil-snipe completely with (package! evil-snipe :disable t) added to $DOOMDIR/packages.el, but this will also disable incremental highlighting for the f/F/t/T motions keys.
3. Or use cl and cc, respectively; they do the same thing.

The Y key behaves differently from Vim (should yank the whole line)

Doom changes the behavior of the Y key in normal mode to yank-to-EOL (equivalent to y$). This was to make it consistent with the C and D capital operators, and because it was redundant with yy, which is easier to type than y$.

If you prefer the old behavior, it can be reversed with:

;; add to $DOOMDIR/config.el
(setq! evil-want-Y-yank-to-eol nil)

Frequently asked questions

Ask a question?

How do I remove evil?

1. Disable this module.
2. Run $ doom sync to clean up lingering dependencies and regenerate your autoloads files.
3. [OPTIONAL] Change doom-leader-alt-key and doom-localleader-alt-key. These are bound to C-c and C-c l by default.

🚧 Ignore doom-leader-key and doom-localleader-key, they don't apply to non-evil sessions.

Evil-specific configuration and keybindings (defined with map!) will be ignored without :editor evil present (and omitted when byte-compiling).

Include underscores in evil word motions?

A more in-depth answer and explanation for this can be found in Evil's documentation.

TL;DR If you want the underscore to be recognized as word character, you can modify its entry in the syntax-table:

(modify-syntax-entry ?_ "w")

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.

;; 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"))

TODO Appendix

🔨 This module has no appendix yet. Write one?