Settings

Evil’s behaviour can be adjusted by setting some variables. The list of all available variables and their current values can be inspected by doing:

M-x customize-group RET evil RET

To change the value of a variable, you can use this interface, or add a setq form to your Emacs init file, preferably before Evil is loaded. [1]

(setq evil-shift-width 0)
;; Load Evil
(require 'evil)

What follows is a non-exhaustive list of the most relevant customization options.

The initial state

The initial state of a buffer is determined by its major mode. Evil maintains an association between major modes and their corresponding states, which is most easily modified using the function evil-set-initial-state.

(evil-set-initial-state MODE STATE)

Set the initial state for major mode MODE to STATE. This is the state the buffer comes up in.

If no state can be found, Evil uses the default initial state.

evil-default-state

The default Evil state. This is the state a buffer starts in when it is not otherwise configured (see evil-set-initial-state and evil-buffer-regexps). The value may be one of normal, insert, visual, replace, operator, motion and emacs.

Default: normal

Alternatively, it is possible to select the initial state based on the buffer name rather than its major mode. This is checked first, so it takes precedence over the other methods for setting the state.

evil-buffer-regexps

Regular expressions determining the initial state for a buffer. Entries have the form (REGEXP . STATE), where REGEXP is a regular expression matching the buffer’s name and STATE is one of normal, insert, visual, replace, operator, motion, emacs and nil. If STATE is nil, Evil is disabled in the buffer.

Default: (("^ \\*load\\*"))

Keybindings and other behaviour

Evil comes with a rich system for modifying its key bindings Keymaps. For the most common tweaks, the following variables are available.

evil-toggle-key

The key used to change to and from Emacs state. Must be readable by read-kbd-macro. For example: “C-z”.

Default: "C-z"

evil-want-C-i-jump

Whether C-i jumps forward in the jump list (like Vim). Otherwise, C-i inserts a tab character.

Default: t

evil-want-C-u-delete

Whether C-u deletes back to indentation in insert state. Otherwise, C-u applies a prefix argument. The binding of C-u mirrors Emacs behaviour by default due to the relative ubiquity of prefix arguments.

Default: nil

evil-want-C-u-scroll

Whether C-u scrolls up (like Vim). Otherwise, C-u applies a prefix argument. The binding of C-u mirrors Emacs behaviour by default due to the relative ubiquity of prefix arguments.

Default: nil

evil-want-C-d-scroll

Whether C-d scrolls down (like Vim).

Default: t

evil-want-C-w-delete

Whether C-w deletes a word in Insert state.

Default: t

evil-want-C-w-in-emacs-state

Whether C-w prefixes windows commands in Emacs state.

Default: nil

evil-want-Y-yank-to-eol

Whether Y yanks to the end of the line. The default behavior is to yank the whole line, like Vim.

Default: nil

evil-disable-insert-state-bindings

Whether insert state bindings should be used. Bindings for escape, delete and evil-toggle-key are always available. If this is non-nil, default Emacs bindings are by and large accessible in insert state.

Default: nil

Indentation

evil-auto-indent

Whether to auto-indent when opening lines with o and O.

Default: t, buffer-local

evil-shift-width

The number of columns by which a line is shifted. This applies to the shifting operators > and <.

Default: 4, buffer-local

evil-shift-round

Whether shifting rounds to the nearest multiple. If non-nil, > and < adjust line indentation to the nearest multiple of evil-shift-width.

Default: t, buffer-local

evil-indent-convert-tabs

If non-nil, the = operator converts between leading tabs and spaces. Whether tabs are converted to spaces or vice versa depends on the value of indent-tabs-mode.

Default: t

Cursor movement

In standard Emacs terms, the cursor is generally understood to be located between two characters. In Vim, and therefore also Evil, this is the case in insert state, but in other states the cursor is understood to be on a character, and that this character is not a newline.

Forcing this behaviour in Emacs is the source of some potentially surprising results (especially for traditional Emacs users—users used to Vim may find the default behavior to their satisfaction). Many of them can be tweaked using the following variables.

evil-repeat-move-cursor

Whether repeating commands with . may move the cursor. If nil, the original cursor position is preserved, even if the command normally would have moved the cursor.

Default: t

evil-move-cursor-back

Whether the cursor is moved backwards when exiting insert state. If non-nil, the cursor moves “backwards” when exiting insert state, so that it ends up on the character to the left. Otherwise it remains in place, on the character to the right.

Default: t

evil-move-beyond-eol

Whether the cursor can move past the end of the line. If non-nil, the cursor is allowed to move one character past the end of the line, as in Emacs.

Default: nil

evil-cross-lines

Whether horizontal motions may move to other lines. If non-nil, certain motions that conventionally operate in a single line may move the cursor to other lines. Otherwise, they are restricted to the current line. This applies to h, SPC, f, F, t, T, ~.

Default: nil

evil-respect-visual-line-mode

Whether movement commands respect visual-line-mode. If non-nil, visual-line-mode is generally respected when it is on. In this case, motions such as j and k navigate by visual lines (on the screen) rather than “physical” lines (defined by newline characters). If nil, the setting of visual-line-mode is ignored.

This variable must be set before Evil is loaded.

Default: nil

evil-track-eol

Whether $ “sticks” the cursor to the end of the line. If non-nil, vertical motions after $ maintain the cursor at the end of the line, even if the target line is longer. This is analogous to track-eol, but respects Evil’s interpretation of end-of-line.

Default: t

Cursor display

A state may change the appearance of the cursor. Use the variable evil-default-cursor to set the default cursor, and the variables evil-normal-state-cursor, evil-insert-state-cursor etc. to set the cursors for specific states. The acceptable values for all of them are the same.

evil-default-cursor

The default cursor. May be a cursor type as per cursor-type, a color string as passed to set-cursor-color, a zero-argument function for changing the cursor, or a list of the above.

Default: t

Window management

evil-auto-balance-windows

If non-nil window creation and deletion trigger rebalancing.

Default: t

evil-split-window-below

If non-nil split windows are created below.

Default: nil

evil-vsplit-window-right

If non-nil vertically split windows with are created to the right.

Default: nil

Parenthesis highlighting

These settings concern the integration between Evil and show-paren-mode. They take no effect if this mode is not enabled.

evil-show-paren-range

The minimal distance between point and a parenthesis which causes the parenthesis to be highlighted.

Default: 0

evil-highlight-closing-paren-at-point-states

The states in which the closing parenthesis at point should be highlighted. All states listed here highlight the closing parenthesis at point (which is Vim’s default behavior). All others highlight the parenthesis before point (which is Emacs default behavior). If this list contains the symbol not then its meaning is inverted, i.e. all states listed here highlight the closing parenthesis before point.

Default: (not emacs insert replace)

Miscellaneous

evil-want-fine-undo

Whether actions are undone in several steps. There are two possible choices: nil (“no”) means that all changes made during insert state, including a possible delete after a change operation, are collected in a single undo step. Non-nil (“yes”) means that undo steps are determined according to Emacs heuristics, and no attempt is made to aggregate changes.

For backward compatibility purposes, the value fine is interpreted as nil. This option was removed because it did not work consistently.

Default: nil

evil-undo-system

Undo system Evil should use. If equal to undo-tree or undo-fu, those packages must be installed. If equal to undo-tree, undo-tree-mode must also be activated. If equal to undo-redo, Evil uses commands natively available in Emacs 28.

Default: nil

evil-backspace-join-lines

Whether backward delete in insert state may join lines.

Default: t

evil-kbd-macro-suppress-motion-error

Whether left/right motions signal errors in keyboard macros. This variable only affects beginning-of-line or end-of-line errors regarding the motions h and SPC respectively. This may be desired since such errors cause macro definition or execution to be terminated. There are four possibilities:

  • record: errors are suppressed when recording macros, but not when replaying them.
  • replay: errors are suppressed when replaying macros, but not when recording them.
  • t: errors are suppressed in both cases.
  • nil: errors are never suppressed.

Default: nil

evil-mode-line-format

The position of the state tag in the mode line. If set to before or after, the tag is placed at the beginning or the end of the mode-line, respectively. If nil, there is no tag. Otherwise it should be a cons cell (WHERE . WHICH), where WHERE is either before or after, and WHICH is a symbol in mode-line-format. The tag is then placed before or after that symbol, respectively.

Default: before

evil-mouse-word

The thing-at-point symbol for double click selection. The double-click starts visual state in a special word selection mode. This symbol is used to determine the words to be selected. Possible values are evil-word or evil-WORD.

Default: evil-word

evil-bigword

The set of characters to be interpreted as WORD boundaries. This is enclosed with square brackets and used as a regular expression. By default, whitespace characters are considered WORD boundaries.

Default: "^ \t\r\n", buffer-local

evil-esc-delay

The time, in seconds, to wait for another key after escape. If no further event arrives during this time, the event is translated to ESC. Otherwise, it is translated according to input-decode-map. This does not apply in Emacs state, and may also be inhibited by setting evil-inhibit-esc.

Default: 0.01

evil-intercept-esc

Whether Evil should intercept the escape key. In the terminal, escape and a meta key sequence both generate the same event. In order to distingush these, Evil uses input-decode-map. It is not necessary to do this in a graphical Emacs session. However, if you prefer to use C-[ as escape (which is identical to the terminal escape key code), this interception must also happen in graphical Emacs sessions. Set this variable to always, t (only in the terminal) or nil (never intercept).

Default: always

evil-kill-on-visual-paste

Whether pasting in visual state adds the replaced text to the kill ring, making it the default for the next paste. The default, replicates the default Vim behavior.

Default: t

evil-echo-state

Whether to signal the current state in the echo area.

Default: t

evil-complete-all-buffers

Whether completion looks for matches in all buffers. This applies to C-n and C-p in insert state.

Default: t

Footnotes

[1]Strictly speaking, the order only matters if the variable affects the way Evil is loaded. This is the case with some variables.