doomemacs/modules/editor/evil

: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?
  • How do I disable synchronization between the kill ring and system clipboard?
• 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

• doom-package:evil
• doom-package:evil-args
• doom-package:evil-collection if doom-module:+everywhere
• doom-package:evil-easymotion
• doom-package:evil-embrace
• doom-package:evil-escape
• doom-package:evil-exchange
• doom-package:evil-indent-plus
• doom-package:evil-lion
• doom-package:evil-nerd-commentary
• doom-package:evil-numbers
• doom-package:evil-quick-diff
• doom-package:evil-snipe
• doom-package:evil-surround
• doom-package:evil-textobj-anyblock
• doom-package:evil-vimish-fold
• doom-package:evil-visualstar
• doom-package: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 doom-module::ui neotree & doom-module::ui treemacs modules provide a NERDTree equivalent.

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

  • doom-package:evil-multiedit => vim-multiedit
  • doom-package: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 doom-package: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 doom-package: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 doom-module::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"))

How do I disable synchronization between the kill ring and system clipboard?

In vim, operations that put or delete text (kill and yank in Emacs terminology) act on the unnamed register by default. The unnamed register unrelated the system clipboard. Evil uses the kill ring instead of the unnamed register. As the kill ring is synchronized with the system clipboard by default, operations like dd or cw place the killed text in the system clipboard, surprisingly so for users who are used to the vim behavior.

The synchronization between the system clipboard and kill ring can be disabled, making these operations behave closer to their vim counterparts:

(setq select-enable-clipboard nil)

Like in vim, the clipboard can still be accessed by using the + register, e.g. "+dd or "+cw.

TODO Appendix

󱌣 This module has no appendix yet. Write one?