Keymaps ​

Evil’s key bindings are stored in a number of different keymaps. Each state has a `global keymap', where the default bindings for that state are stored. They are named evil-normal-state-map, evil-insert-state-map, and so on. The bindings in these maps are visible in all buffers currently in the corresponding state.

These keymaps function like ordinary Emacs keymaps and may be modified using the Emacs function define-key:

emacs-lisp
(define-key evil-normal-state-map (kbd "w") 'some-function)

This binds the key w to the command some-function in normal state. The use of kbd is optional for simple key sequences, like this one, but recommended in general.

Most of Evil’s bindings are defined in the file evil-maps.el.

To facilitate shared keybindings between states, some states may activate keybindings from other states as well. For example, motion state bindings are visible in normal and visual state, and normal state bindings are also visible in visual state.

Each state also has a `buffer-local keymap' which is specific to the current buffer, and which takes precedence over the global keymap. These maps are most suitably modified by a mode hook. They are named evil-normal-state-local-map, evil-insert-state-local-map, and so on.

emacs-lisp
(add-hook 'some-mode-hook
          (lambda ()
            (define-key evil-normal-state-local-map
                        (kbd "w") 'some-function)))

For convenience, the functions evil-global-set-key and evil-local-set-key are available for setting global and local state keys.

Emacs Lisp Autofunction: (evil-global-set-key STATE KEY DEF) ​

Bind `KEY' to `DEF' in `STATE'.

Emacs Lisp Autofunction: (evil-local-set-key STATE KEY DEF) ​

Bind `KEY' to `DEF' in `STATE' in the current buffer.

The above examples could therefore have been written as follows:

emacs-lisp
(evil-global-set-key 'normal (kbd "w") 'some-function)

(add-hook 'some-mode-hook
          (lambda ()
            (evil-local-set-key 'normal (kbd "w") 'some-function)))