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
andevil-buffer-regexps
). The value may be one ofnormal
,insert
,visual
,replace
,operator
,motion
andemacs
.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 ofnormal
,insert
,visual
,replace
,operator
,motion
,emacs
andnil
. If STATE isnil
, 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 ofC-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 ofC-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/Ex/Search 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
Search¶
- evil-search-module¶
The search module to be used. May be either
isearch
, for Emacs’ isearch module, orevil-search
, for Evil’s own interactive search module. N.b. changing this will not affect keybindings. To swap out relevant keybindings, seeevil-select-search-module
function.Default:
isearch
- evil-regexp-search¶
Whether to use regular expressions for searching in / and ?.
Default:
t
- evil-search-wrap¶
Whether search with / and ? wraps around the buffer. If this is non-nil, search stops at the buffer boundaries.
Default:
t
- evil-flash-delay¶
Time in seconds to flash search matches after n and N.
Default:
2
- evil-ex-hl-update-delay¶
Time in seconds of idle before updating search highlighting. Setting this to a period shorter than that of keyboard’s repeat rate allows highlights to update while scrolling.
Default:
0.02
- evil-ex-search-incremental¶
If t, use incremental search. Note that this only affects the search command if
evil-search-module
is set toevil-search
.Default:
t
Indentation¶
- evil-auto-indent¶
Whether to auto-indent when opening lines with o and O.
Default:
t
- evil-shift-width¶
The number of columns by which a line is shifted. This applies to the shifting operators > and <.
Default:
4
- 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
- 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.
See also
evil-move-beyond-eol
.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-v$-excludes-newline¶
If non-nil,
evil-end-of-line
does not move as far as to include the `` `` char at eol. This makesv$
consistent with$
used as a motion (e.g.v$y
is consistent withy$
in normal state).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 ofvisual-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
- evil-start-of-line¶
Analogue of vim’s
startofline
. If nil, preserve column when making relevant movements of the cursor. Otherwise, move the cursor to the start of the line.Default:
nil
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 toset-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 maximum 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 asnil
. 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
orundo-fu
, those packages must be installed. If equal toundo-tree
,undo-tree-mode
must also be activated. If equal toundo-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
orafter
, 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 eitherbefore
orafter
, and WHICH is a symbol inmode-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
orevil-WORD
.Default:
evil-word
- evil-transient-mouse-selection¶
Whether the region selected by the mouse is discarded by the next command. By default, the region is not discarded. If non-nil, exit visual state immediately before the next command. To use the region selected by the mouse, execute a command which would usually enter visual state, such as M-x evil-visual-char or M-x evil-visual-block.
Default:
nil
- 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"
- 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 toinput-decode-map
. This does not apply in Emacs state, and may also be inhibited by settingevil-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 toalways
, 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 for
p
. This value is flipped byevil-paste-before
(M-x evil-paste-before).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
- evil-want-empty-ex-last-command¶
Whether to default to evil-ex-previous-command at empty ex prompt.
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. |