Evil Collection

• Goals
• Installation
• Configuration
• Guidelines
• Rationale
  • Motion ([, ], {, }, (, ), gj, gk, C-j, C-k)
  • Quitting (q, ZQ, ZZ)
  • Refreshing / Reverting (gr)
  • Marking
  • Selecting / Filtering / Narrowing / Searching
  • Sorting
  • Go to definition (gd, gD)
  • Go to current entity
  • Open thing at point (RET, S-RET, M-RET, go, gO)
  • Emacs-style jumping (J)
  • Browse URL (gx)
  • Help (?)
  • History browsing (C-n, C-p)
  • Bookmarking
  • REPL (gz)
  • Zooming (+, -, =, 0)
  • Debugging
• Modes left behind
• Third-party packages
• FAQ
• Contributing

file:https://travis-ci.org/jojojames/evil-collection.svg?branch=master

This is a collection of Evil bindings for the parts of Emacs that Evil does not cover properly by default, such as help-mode, M-x calendar, Eshell and more.

Warning: This project is still in an early development phase, expect some default bindings to change in the future.

Goals

1. Reduce context switching: As soon as "moving around" gets hardwired to <hjkl>, it becomes frustratingly inefficient not to have it everywhere.
2. Community work: setting up bindings is tremendous work and joining force can only save hours for all of Evil users out there. While not everyone may agree on the chosen bindings, it helps to have something to start with rather than nothing at all. In the end, users are free to override a subset of the proposed bindings to best fit their needs.
3. Consistency: Having all bindings defined in one place allows for enforcing consistency across special modes and coordinating the community work to define a reference implementation.

Installation

• Get the package, either from MELPA:

M-x package-install RET evil-collection RET

Or clone / download this repository and modify your load-path:

(add-to-list 'load-path (expand-file-name "/path/to/evil-collection/" user-emacs-directory))

• Register the bindings, either all at once with evil-collection-init:

or mode-by-mode, for instance:

(with-eval-after-load 'calendar (require 'evil-collection-calendar) (evil-collection-calendar-setup))

The list of supported modes is configured by ~evil-collection-mode-list~.

evil-collection assumes evil-want-integration is set to nil before loading evil and evil-collection.

For example:

(setq evil-want-integration nil)
(require 'evil)
(when (require 'evil-collection nil t)
  (evil-collection-init))

Here's another full TLDR use-package example.

(use-package evil
  :ensure t
  :init
  (setq evil-want-integration nil)
  :config
  (evil-mode 1))

(use-package evil-collection
  :after evil
  :ensure t
  :config
  (evil-collection-init))

NOTE: If you don't like surprises but still want to use evil-collection-init, setting evil-collection-mode-list to nil and adding each mode manually might be a better option.

Configuration

Modify evil-collection-mode-list to disable or add any modes that should be evilified by evil-collection.

Variable	Default	Description
evil-collection-company-use-tng	t	Set up autocompletion to be similar to Vim's YouCompleteMe.
evil-collection-outline-bind-tab-p	t	Enable <tab>-based bindings in Outline mode.
evil-collection-term-sync-state-and-mode-p	t	Synchronize insert/normal state with char/line-mode in term-mode.
evil-collection-setup-minibuffer	nil	Set up Vim style bindings in the minibuffer.
evil-collection-setup-debugger-keys	t	Set up debugger keys for certain modes.

For example, if you want to enable Evil in the minibuffer, you'll have to turn it on explicitly by customizing evil-collection-setup-minibuffer to t.

use-package example:

(use-package evil-collection
:custom (evil-collection-setup-minibuffer t)
:init (evil-collection-init))

Guidelines

The following rules serve as guiding principles to define the set of standard Evil bindings for various modes. Since special modes are by definition structurally incomparable, those rules cannot be expected to be applied universally.

The rules are more-or-less sorted by priority.

0. Don't bind anything to : nor <escape>.
1. Keep the movement keys when possible and sensible.

• h, j, k, l
• w, W, b, B, e, E, ge, gE
• f, F, t, T, ;, ,
• gg, G
• |
• (, )
• {, }
• %
• +, -, 0, ^, $
• C-i, C-o

1. Keep the yanking and register keys when possible and sensible.

• y, Y
• "

1. Keep the search keys when possible and sensible.

• /, ?
• #, *

1. Keep the mark keys when possible and sensible.

• m
• ', ~

1. Keep the windowing keys when possible and sensible.

• H, L, M
• C-e, C-y
• C-f, C-b
• C-d, C-u
• C-w-prefixed bindings.
• Some z-prefixed bindings (see below).

1. The following keys are free when insert state does not make sense in the current mode:

• a, A, i, I
• c, C, r, R, s, S
• d, D, x, X
• o, O
• p, P
• =, <, >
• J
• ~

Any of those keys can be set to be a prefix key.

1. Prefix keys: g and z are the ubiquitous prefix keys.

• g generally stands for "go" and is best used for movements.
• z is used for scrolling, folding, spell-checking and more.

1. Macro and action keys

• @, q
• .

Rationale

Many special modes share the same set of similar actions. Those actions should share the same bindings across all modes whenever feasible.

Motion ([, ], {, }, (, ), gj, gk, C-j, C-k)

• [ and ]: Use [- and ]- prefixed keys for navigation between sections. If the mode makes no difference between the end of a section and the beginning of the next, use [ and ].
• gj and gk: synonym for [ and ]. That's what evil-magit does.

Question: Should gj / gk rather be synonyms for C-j / C-k? They cannot emulate the behaviour of [] or ][.

• C-j, C-k: If there is granularity, i.e. subsections, use C-j and C-k to browse them. This reflects evil-magit and evil-mu4e default bindings.
• {, }: If there is no paragraph structure, { and } can be used for sub-sectioning.
• (, ): If there is no sentence structure, ( and ) can be used for sub-sectioning.
• HJKL: hjkl can be used for atomic movements, but HJKL can usually not be used because H, K and L are all universal (J is evil-join and usually does not make sense in special modes).

• C-h should not be remapped: Since we have C-j and C-k for vertical motion, it would make sense to use C-h and C-l for horizontal motion. There are some shortcomings though:

  • In Vim, C-h works as backspace, but Evil does not follow that behaviour.
  • In Emacs, it is a prefix key for all help-related commands, and so is <f1>.
  • Most importantly, C-h is too widespread and ubiquitous to be replaced. So we don't.
• C-l: As a consequence of the former point, C-l is available.
• M-<hjkl>: Those keys are usually free in Evil but still bound to their Emacs default (e.g. M-l is downcase-word). Besides, if C-j and C-k are already used, having M-j and M-k might add up to the confusion.

Quitting (q, ZQ, ZZ)

In Vim, q is for recording macros. Vim quits with ZZ or ZQ. In most Emacs special modes, it stands for quitting while macros are recorded/played with <f3> and <f4>.

A good rule of thumb would be:

• Always bind ZZ and ZQ to the quitting function(s), evil-quit if nothing else makes sense.
• Bind q to evil-quit if macros don't make sense in current mode.
• If macros don't make sense in current mode, then @ is available.

Refreshing / Reverting (gr)

• gr is used for refreshing in evil-magit, evil-mu4e, and some Spacemacs configurations (org-agenda and neotree among others).

C-l is traditionally used to refresh the terminal screen. Since there does not seem to be any existing use of it, we leave the binding free for other uses.

Marking

m defaults to evil-set-marker which might not be very useful in special modes. ' can still be used as it can jump to other buffers.

• m: Mark or toggle mark, depending on what the mode offers.

In visual mode, always mark. With a numeric argument, toggle mark on that many following lines.

• u: Unmark current selection.
• U: Unmark all.
• ~: Toggle all marks. This mirrors the "invert-char" Vim command bound to ~

by default.

• M: Mark all, if available. Otherwise use U~.
• *: Mark-prefix or mark all if current mode has no prefix. * is traditionally a wildcard.
• %: Mark regexp.
• x: Execute action on marks. This mirrors Dired's binding of x.

If * is used for marking, then # is free.

Also note that Emacs inconsistently uses u and U to unmark.

Selecting / Filtering / Narrowing / Searching

• s and S seem to be used in some places like mu4e.

  • s: [s]elect/[s]earch/filter candidates according to a pattern.
  • S: Remove filter and select all.
• = is usually free and its significance is obvious. It's taken for zooming though.
• | is not free but the pipe symbolic is very tantalizing.

Sorting

• o: Change the sort [o]rder.
• O: Sort in reverse order.

package-menu uses S.

M-x proced and Dired use s.

profiler uses A and D.

mu4e uses O.

ranger uses o, inspired from Mutt.

Go to definition (gd, gD)

• gd: [g]o to [d]efinition. This is mostly for programming modes. If there's a corresponding 'pop' action, use C-t.

Go to current entity

• .: go to current entity (day for calendar, playing track for EMMS). Bind only if more relevant than evil-repeat.

Open thing at point (RET, S-RET, M-RET, go, gO)

• RET, S-RET, M-RET: Open thing at point in current window, open in other window and display in other window respectively. The latter is like the former with the focus remaining on the current window.
• go, gO: When available, same as S-RET and M-RET respectively. This is useful in terminals where S-RET and M-RET might not work.

Emacs-style jumping (J)

• J: mu4e has j and evil-mu4e uses J, so we use J too.

Some special modes like mu4e and ibuffer offer to to "jump" to a different buffer. This sometimes depends on the thing at point.

This is not related to Evil jumps like C-i and C-o, nor to "go to definition".

Browse URL (gx)

gx: go to URL. This is a default Vim binding.

Help (?)

• g? : is the standard key for help related commands.
• ? in places where backward search is not very useful.

History browsing (C-n, C-p)

C-n and C-p are standard bindings to browse the history elements.

Bookmarking

?

REPL (gz)

If the mode has a Go To REPL-type command, set it to gz.

Zooming (+, -, =, 0)

• + and - have obvious meanings.
• 0 has a somewhat intuitive meaning, plus it is next to + and - on QWERTY.
• = is useful as a synonym for + because it is the unshifted key of + on QWERTY.

Debugging

When debugging is on, debugger keys takes the most precedence.

These keys will be set when there's an available command for them.

• n : Step Over
• i : Step Into
• o : Step Out
• c : Continue/Resume Execution
• L : Locals
• t : Tracing
• q : Quit Debugging
• H : Continue until Point
• e : Evaluate Expression
• b : Set Breakpoint
• u : Unset Breakpoint
• > : Navigate to Next Frame
• < : Navigate to Previous Frame
• g? : Help
• J : Jump to debugger location
• R : Restart

For debugging outside of debugger being on (e.g. setting initial breakpoints), we use similar keys to realgud.

• f5 Start/Continue/Resume Execution
• S-f5 Continue Execution
• Mouse-1 Toggle Breakpoint
• f9 Toggle Breakpoint
• f10 Step Over
• f11 Step Into
• S-f11 Step Out

Modes left behind

Some modes might still remain unsupported by this package. Should you be missing your <hjkl>, feel free to file an issue or even a pull request.

Third-party packages

Third-party packages are provided by several parties:

• evil-ediff
• evil-magit
• evil-mu4e
• Lispy: lispyville or evil-lispy
• Org-mode: https://github.com/GuiltyDolphin/org-evil or https://github.com/Somelauw/evil-org-mode

Should you know any suitable package not mentioned in this list, let us know and file an issue.

Other references:

• Spacemacs
• Doom Emacs

FAQ

• Making SPC work similarly to spacemacs. evil-collection binds over SPC in many packages. To use SPC as a leader key: I use general.

  (use-package general
    :ensure t
    :config
    (setq general-override-states '(insert
                                    emacs
                                    hybrid
                                    normal
                                    visual
                                    motion
                                    operator
                                    replace))
    (general-override-mode)
    (general-define-key
     :states '(normal visual motion)
     :keymaps 'override
     "SPC" 'hydra-space/body))

See noctuid's evil guide for other approaches.

This should also be accomplishable using key translation from general.

Contributing

Please do!

We welcome any additional modes that are not already supported.

All bindings in evil-collection are still open to change so if there's a better or more consistent binding, please open an issue or submit a PR.

Follow The Emacs Lisp Style Guide for coding conventions.

This is also a good read for helpful commit messages.