#+title: :editor evil #+subtitle: The text editor Emacs was missing #+created: April 08, 2020 #+since: 2.0.0 * Description :unfold: This holy module brings the Vim editing model to Emacs. ** Maintainers - [[doom-user:][@hlissner]] [[doom-contrib-maintainer:][Become a maintainer?]] ** Module flags - +everywhere :: Enable evilified keybinds everywhere possible. Uses the [[https://github.com/emacs-evil/evil-collection][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, [[kbd:][*]] and [[kbd:][#]] 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 section will be machine generated. Don't edit it by hand. /This module does not have a changelog yet./ * Installation [[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] /This module has no external requirements./ * TODO Usage #+begin_quote 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] #+end_quote ** Ported vim plugins The following vim plugins have been ported to evil: | Vim Plugin | Emacs Plugin | Keybind(s) | |-----------------------+--------------------------------+--------------------------------| | vim-commentary | evil-nerd-commenter | omap [[kbd:][gc]] | | vim-easymotion | evil-easymotion | omap [[kbd:][gs]] | | vim-lion | evil-lion | omap [[kbd:][gl]] / [[kbd:][gL]] | | vim-seek or vim-sneak | evil-snipe | mmap [[kbd:][s]] / [[kbd:][S]], omap [[kbd:][z]] / [[kbd:][Z]] & [[kbd:][x]] / [[kbd:][X]] | | vim-surround | evil-embrace and evil-surround | vmap [[kbd:][S]], omap [[kbd:][ys]] | | vim-unimpaired | (provided by Doom) | [[https://github.com/hlissner/doom-emacs/blob/develop/modules/editor/evil/config.el#L413-L460][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]] => [[github:hlissner/vim-multiedit][vim-multiedit]] - [[doom-package:][evil-mc]] => [[https://github.com/terryma/vim-multiple-cursors][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: - [[kbd:][w W]] words - [[kbd:][s]] sentences - [[kbd:][p]] paragraphs - [[kbd:][b]] parenthesized blocks - [[kbd:][b ( ) { } [ ] < >]] braces, parentheses and brackets - [[kbd:][' " `]] quotes - [[kbd:][t]] tags - [[kbd:][o]] symbols And these are text objects added by this module: - [[kbd:][a]] C-style function arguments (provided by ~evil-args~) - [[kbd:][B]] any block delimited by braces, parentheses or brackets (provided by ~evil-textobj-anyblock~) - [[kbd:][c]] Comments - [[kbd:][f]] For functions (but relies on the major mode to have sane definitions for ~beginning-of-defun-function~ and ~end-of-defun-function~) - [[kbd:][g]] The entire buffer - [[kbd:][i j k]] by indentation ([[kbd:][k]] includes one line above; [[kbd:][j]] includes one line above and below) (provided by ~evil-indent-plus~) - [[kbd:][q]] For quotes (any kind) - [[kbd:][u]] For URLs - [[kbd:][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 #+begin_quote 🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] #+end_quote * Troubleshooting [[doom-report:][Report an issue?]] ** Can't access the universal argument key ([[kbd:][C-u]]) For maximum Vim emulation, this module commandeers the C-u key for scrolling (as it does in Vim). The same goes for [[kbd:][C-u]] in insert mode (which deletes to BOL). In both cases the universal argument has been moved to [[kbd:][ u]]. To undo this, use: #+begin_src emacs-lisp ;; add to $DOOMDIR/config.el (setq! evil-want-C-u-scroll nil evil-want-C-u-delete nil) #+end_src ** The [[kbd:][s]]/[[kbd:][S]] keys behave differently from Vim Doom replaces the [[kbd:][s]] and [[kbd:][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 [[kbd:][cl]] and [[kbd:][cc]], respectively; they do the same thing. ** The [[kbd:][Y]] key behaves differently from Vim (should yank the whole line) Doom changes the behavior of the [[kbd:][Y]] key in normal mode to yank-to-EOL (equivalent to [[kbd:][y$]]). This was to make it consistent with the [[kbd:][C]] and [[kbd:][D]] capital operators, and because it was redundant with [[kbd:][yy]], which is easier to type than [[kbd:][y$]]. If you prefer the old behavior, it can be reversed with: #+begin_src emacs-lisp ;; add to $DOOMDIR/config.el (setq! evil-want-Y-yank-to-eol nil) #+end_src * Frequently asked questions [[doom-suggest-faq:][Ask a question?]] ** How do I remove evil? :PROPERTIES: :ID: f3925da6-5f0b-4d11-aa08-7bb58bea1982 :END: 1. [[id:01cffea4-3329-45e2-a892-95a384ab2338][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 [[kbd:][C-c]] and [[kbd:][C-c l]] by default. #+begin_quote 🚧 Ignore ~doom-leader-key~ and ~doom-localleader-key~, they don't apply to non-evil sessions. #+end_quote 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 [[https://evil.readthedocs.io/en/latest/faq.html#underscore-is-not-a-word-character][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: #+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 * TODO Appendix #+begin_quote 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]] #+end_quote