doomemacs/modules/feature/evil/README.org

feature/evil

• Description
  • Module Flags
  • Plugins
  • Hacks
• Prerequisites
• Features
  • Ported vim plugins
  • Custom Text Objects
  • Custom Ex Commands
  • A hybrid code-folding system
  • Differences from vim
• Configuration
  • Removing evil-mode

Description

This holy module brings the vim experience to Emacs.

Module Flags

• +everywhere Enables evilified keybinds everywhere possible, utilizing the evil-collection plugin.

Plugins

• evil
• evil-args
• evil-commentary
• evil-easymotion
• evil-embrace
• evil-escape
• evil-exchange
• evil-indent-plus
• evil-matchit
• evil-numbers
• evil-textobj-anyblock
• evil-snipe
• evil-surround
• evil-vimish-fold
• evil-visualstar
• exato
• evil-collection*

Hacks

• When a window is split, the new window will be focused.
• The o/O keys will respect and continue commented lines (can be disabled by setting +evil-want-o/O-to-continue-comments to nil).
• From 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 incrementally.
• 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).

Prerequisites

This module has no external prerequisites.

Features

Ported vim plugins

The following vim plugins have been ported to evil:

Vim Plugin	Emacs Plugin	Keybind(s)
vim-commentary	evil-commentary	omap gc
vim-easymotion	evil-easymotion	omap gs
vim-seek or vim-sneak	evil-snipe	mmap s=/=S
vim-surround	evil-embrace and evil-surround	vmap S, omap ys

In other modules:

• The tools/neotree & tools/treemacs modules contain a NERDTree equivalent.

• The editor/multiple-cursors module contains:

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

Custom Text Objects

• A list of new text objects:

  • Blocks: B (from evil-textobj-anyblock)
  • Args: a (from evil-args)
  • Indentation: i / I / J (from evil-indent-plus)

Custom Ex Commands

Ex Command	Description
:al[ign][!] REGEXP	Align text to the first match of REGEXP. If BANG, align all matches on each line
:mv[!] NEWPATH	Move the current file to NEWPATH
:cp[!] NEWPATH	Copy the current file to NEWPATH
:rm[!] [PATH]	Delete the current buffer's file and buffer

A hybrid code-folding system

This module combines vimish-fold and hideshow. The former allows arbitrary folds and the latter allows folds on markers and indentation. Together, they create a more consistent (and feature-complete) code-folding system.

Most vim folding keys should work, e.g. zr, zm, za, zo, etc.

Differences from vim

• Column-wise ranges in ex commands are enabled by default. i.e. the range in :'<,'>s/a/b will only affects the visual selection, not full lines (see evil-ex-visual-char-range).
• :g will incrementally highlight buffer matches.

Configuration

Removing evil-mode

You must do two things to remove Evil:

1. Remove :feature evil from ~/.doom.d/init.el,
2. Run bin/doom refresh to clean up lingering dependencies and refresh yuor autoloads files.
3. [OPTIONAL] You may want a new doom-leader-alt-key and doom-localleader-alt-key. By default, these are bound to M-SPC and M-SPC m.

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

Note that evil-specific configuration and keybinds (defined with map!) will be ignored without evil present (and stripped out when byte-compiling).

Unfortunately, since Doom was designed by a vimmer, for vimmers, little consideration into a keybinding scheme for vanilla Emacs users.