Home

Ivy User Guide

This guide is written in Org mode. You might prefer to view the raw file in Emacs.

Prerequisites

Ivy should run fine on a typical Emacs bundled in your OS’s package manager, the oldest of which is Emacs 24.3.1. However, the faces display will work much better for Emacs 24.5.2, which is the latest stable version.

Installation

Install from GNU ELPA

M-x package-install swiper should install everything.

Install from MELPA

In MELPA, the code is split up into swiper and counsel packages.

Install from Git

Using Git has the advantage of getting the updates earlier (by an hour or two, compared to MELPA), being able to see each update summary and to revert.

git clone https://github.com/abo-abo/swiper ~/git

(add-to-list 'load-path "~/git/swiper/")
(require 'counsel)

Configuration

Minimal config

(ivy-mode 1)
(global-set-key "\C-s" 'swiper)

This configuration is enough if you only want to try Ivy with minimum hassle. If you intent to use it, the extended config is a must.

Extended config

Recommended key bindings

(ivy-mode 1)
(global-set-key "\C-s" 'swiper)
(global-set-key (kbd "C-c g") 'counsel-git)
(global-set-key (kbd "C-c j") 'counsel-git-grep)
(global-set-key (kbd "C-c k") 'counsel-ag)
(global-set-key (kbd "C-x l") 'counsel-locate)
(global-set-key (kbd "<f1> f") 'counsel-describe-function)
(global-set-key (kbd "<f1> v") 'counsel-describe-variable)
(global-set-key (kbd "<f1> l") 'counsel-load-library)
(global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
(global-set-key (kbd "<f2> u") 'counsel-unicode-char)
(global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
(global-set-key (kbd "C-x C-f") 'counsel-find-file)
(global-set-key (kbd "C-t") 'counsel-M-x)
(global-set-key (kbd "<f6>") 'ivy-resume)

Other settings

You can get by without customizing the following variables. The following code serves to provide an example of the interesting settings.

(setq ivy-use-virtual-buffers t)
(setq ivy-height 10)
(setq ivy-count-format "(%d/%d) ")

Code Overview

The code is composed of 3 major parts:

• Ivy is the library that provides ivy-mode - a global minor mode that updates all completion to Ivy, and ivy-read - the API function, similar to completing-read.
• Swiper is an isearch replacement that uses ivy-read.
• Counsel is a collection of commands that use ivy-read. A large portion of these commands rely on external tools, like git-grep, ag, locate, recoll, rhythmbox, cider, slime, smex and jedi. The other portion are the improved variants of the built-in commands that weren’t possible to implement with only ivy-mode, like counsel-find-file, counsel-M-x, counsel-describe-variable, counsel-describe-function etc.

Function Index

ivy-mode

Ivy mode improves your minibuffer during a completion session. Any time you type in anything into the minibuffer, it will filter all candidates based on your query and immediately re-display them.

Default matcher

The default matcher is very simple and powerful: single spaces are interpreted as a regular expression .* wildcard. So the query "for example" is transformed into "\\(for\\).*\\(example\\)". All other regexp syntax, like ^, $, \b is accepted as well. If you’d like to match literal spaces, input that amount of spaces plus one.

Custom matchers

The default matcher is the ivy--regex-plus function. Other rule functions are available as well:

• ivy--regex is a simpler ivy--regex-plus that doesn’t use ! for negation.
• ivy--regex-ignore-order is a version that makes “for example” match “example test for”, i.e. the order of the input parts doesn’t matter.
• ivy--regex-fuzzy will insert .*? in between each letter, i.e. “irf” will match “ivy–regex-fuzzy”.
• regexp-quote will simply quote the input, making it literal instead of a regex.

You can customize the matchers per collection or globally.

This following setting assigns ivy--regex-fuzzy to all completions:

(setq ivy-re-builders-alist
      '((t . ivy--regex-fuzzy)))

The following setting assigns ivy--regex-plus to file name completion, and ivy--regex-fuzzy to all other completion.

(setq ivy-re-builders-alist
      '((read-file-name-internal . ivy--regex-plus)
        (t . ivy--regex-fuzzy)))

The keys in this alist can be either collection functions that are passed to completing-read-function by Emacs, or a particular value this-command. The latter is easier to understand, but not very flexible.

For the former approach, you can find the name of the key function by edebugging ivy-read and calling your command. Then check the value of collection argument. If you’re lucky, it’s a function, like read-file-name-internal. Sometimes, you’re not lucky and it’s just a list of strings.

Changing matchers on the fly

It’s possible to toggle between ivy--regex-plus and ivy--regex-fuzzy on the fly by pressing m while the options panel is open.

Options panel

During any Ivy completion session, you can toggle the options panel with C-o. All the shortcuts that the panel adds are displayed in a straightforward way.

The option panel serves several purposes:

Shorten key bindings that are already available.

For instance, suppose you want to scroll through a large amount the matches. You can do so with C-n C-n C-n C-p C-p .... However, it’s also possible to do this with C-o jjkk ....

For even more gain, suppose you want to execute the action for several items. You can do so with e.g. C-n C-M-m C-n C-n C-M-m - this will forward a match, execute action, forward two matches and execute action. However, it’s shorter to do this with C-o gjjg.

Add a short description of what is possible to do.

While this applies to all of the bindings on the C-o map, it’s especially true for the w / s bindings that allow to change the current action. An action represents what’s to be done with the string that you select. In the default Emacs completion, only one action is available. However, for example ivy-switch-buffer has 4:

• the “default” action that calls switch-buffer,
• the “kill” action that kills the buffer instead of switching,
• the “other” action that calls switch-buffer-other-window,
• the “rename” action that allows to rename the selected buffer.

The additional actions are all customizable, you can do so like this:

(ivy-set-actions
 'ivy-switch-buffer
 '(("k"
    (lambda (x)
      (kill-buffer x)
      (ivy--reset-state ivy-last))
    "kill")
   ("j"
    ivy--switch-buffer-other-window-action
    "other")
   ("r"
    ivy--rename-buffer-action
    "rename")))

Each entry consists of a key, a lambda, and a docstring. The key applies during M-o (ivy-dispatching-done), C-M-o (ivy-dispatching-call), and C-o a (ivy-read-action). The docstring is additionally visible during C-o and updates with C-o w and C-o s.

Add key bindings that aren’t normally available

For example, you can adjust the size of the minibuffer with < / >. These commands aren’t important enough to bind in the main map. But since the C-o map has a lot of space, they can be bound here.

Same for toggling case folding and candidate display truncation.

counsel-* commands

The main advantage of using counsel- functions over their basic equivalents with ivy-mode enabled are the following:

1. You can use C-M-n (ivy-next-line-and-call) and C-M-p (ivy-previous-line-and-call) for them to execute the selected action without exiting the completion.
2. You can use ivy-resume to resume your last completion session.
3. You can customize them further with ivy-set-actions, ivy-re-builders-alist.
4. You can customize their individual keymaps, like counsel-describe-map, counsel-git-grep-map, or counsel-find-file-map, instead of just customizing ivy-minibuffer-map that applies to all completion sessions.

Key Bindings

The unifying idea behind ivy-minibuffer-map, unlike e.g. isearch-mode-map or Ido keymap is that the minibuffer is a fully capable editing area: bindings like C-a, C-f, M-d, M-DEL, M-b, M-w, C-k, C-y all work as if you were in a fundamental-mode buffer.

However, the bindings that aren’t related to the single current line like C-n, C-p and C-o are used for other things.

Basic bindings

While in the minibuffer, one of the candidates that match the current input is always selected.

• Use C-m (ivy-done) to exit the minibuffer and call the action for this candidate.
• Use C-n (ivy-next-line) to select the next matching candidate
• Use C-p (ivy-previous-line) to select the previous matching candidate

These 3 bindings should be just enough to get by.

By default C-n and C-p don’t wrap around, i.e. the last candidate isn’t selected if you’re at the first candidate and press C-p. If you want this behavior, use:

(setq ivy-wrap nil)

Note also that you can use <down> for C-n and <up> for C-p.

Entering text literally

Sometimes, especially when creating new directories, you enter a name that isn’t on the candidate list, but still matches a candidate. In that case, C-m or C-j won’t work for you, since they will select the matching candidate.

In that case, use C-M-j (ivy-immediate-done) to exit the minibuffer with the literal text that you entered.

TAB behavior

<tab> or C-i is bound to ivy-partial-or-done that’s meant to resemble how these bindings behave with ivy-mode off.

Pressing C-i the first time extends the input up to the closest difference. Here’s an example in ERT terms:

(should
 (equal (ivy-with
         '(progn
           (ivy-read "Test: " '("can do" "can't, sorry" "other"))
           ivy-text)
         "c <tab>")
        "can"))

To explain it in words, if the candidate list is the above 3 words, you input “c” and press <tab>, the minibuffer input should be “can”, since that’s the longest common sub-string for all candidates that match “c” .

When pressing C-i C-i, the second one is equivalent to C-m.

File name completion bindings

ivy-alt-done

When completing file names, with either find-file and enabled ivy-mode, or counsel-find-file, C-j (ivy-alt-done) is a very useful command. While doing the same thing as C-m for all other completions, when completing file names, this command will enter the selected directory and continue the completion.

To paraphrase, you can use a combination of C-j, C-n and C-p to navigate to any file on your file system, and after each C-j you’ll see in the minibuffer the ls result for the directory that you selected.

When either a file or “./” is selected, C-j will finish the completion session with that candidate.

ivy-backward-delete-char

During the completion, the current directory will be displayed read-only as part of the prompt. Pressing DEL (ivy-backward-delete-char) when there’s no input to delete will result in a cd to the parent of the current directory.

magic tilde and slash

When there’s no current input, pressing “~” will move to the home directory.

Inputting “//” works similarly to move to the root directory.

Inputting “/” while the input perfectly matches a directory is equivalent to C-j, i.e. it will move to that directory.

using TRAMP

Completion for TRAMP is supported in a peculiar way. From any directory, with the empty input, inputting /ssh: and pressing C-j (or RET which is the same thing) will give you a completion for host and user names.

You can also input /ssh:user@ to get domain completion with user name already selected.

Described above is a recommended and simple method of interaction. If you find it lacking, you can still use C-i, which does largely the same as the default completion does.

History

The history works with M-p, M-n, and C-r, as in all other completion sessions. I just mention it here because a custom history code was implemented for file name completion. This code will cycle you through all previous files that you opened, including the input with which the file was opened. It also works well with TRAMP.

History

The M-p (ivy-previous-history-element) and M-n (ivy-next-history-element) bindings and commands are very straightforward, same as in the default completion.

One thing to mention is that most counsel-* commands have their own history variable, which is nice to have. All commands that don’t supply their own history variable, use and contribute to ivy-history. This isn’t as convenient, since inputs for one command usually don’t make sense for another command, so individual history is usually better.

The C-r (ivy-reverse-i-search) launches a recursive completion session to get a previous input. It can be a lot faster than pressing M-p multiple times, and the binding is the same as in Bash.

Non-exit Action bindings

With default Emacs completion, the completion function isn’t aware of what will be done with the string that it returns. Not the case with many Ivy functions. Having this information, you can do advanced things, like executing the action without exiting the minibuffer.

Take counsel-git-grep for instance. Pressing C-m will open the selected file on selected match and exit completion. But pressing C-M-m will do the same without exiting completion. Which means that you can examine the context of the match in its own file, and perhaps select another match with C-M-n. By holding C-M-n you can see all of the matches in their file context.

Similarly, you can use C-M-n to quickly flip through buffers in selected window when you call C-x b (ivy-switch-buffer). A nice feature is that if you press C-g (keyboard-quit) while in the minibuffer, you go back to your original buffer.

So here’s an overview of the action bindings:

• C-M-m (ivy-call) will execute the action for current item
• C-M-n (ivy-next-line-and-call) will select the next item and execute the action
• C-M-p (ivy-previous-line-and-call) will select the previous item and execute the action

Multiple Action bindings

• M-o (ivy-dispatching-done) is like C-m (ivy-done), but will prompt you for an action, in case many are available.
• C-M-o (ivy-dispatching-call) is like C-M-m (ivy-call), but will prompt you for an action, in case many are available.

Each completion session has at least one action - the default one, and it’s bound to o, i.e. M-o o is the same as C-m, and C-M-o o is the same as C-M-m.

Extra scrolling bindings

To scroll faster than C-n and C-p you can use:

• M-< (ivy-beginning-of-buffer) - selects the first candidate,
• M-> (ivy-end-of-buffer) - selects the last candidate,
• C-v (ivy-scroll-up-command) - scrolls up by one screen,
• M-v (ivy-scroll-down-command) - scrolls down by one screen.

Other useful bindings

To reproduce what C-w does for Isearch, you can use M-j (ivy-yank-word). The reason for not using C-w is that it should be bound to kill-region - an important editing binding.

To insert symbol-at-point into the minibuffer, press M-n (ivy-next-history-element) when the input is empty.

To copy all matching candidates, press M-w (ivy-kill-ring-save) while the region isn’t active. This can be useful in a variety of scenarios, for instance you can generate a filtered file list by pressing M-w during counsel-find-file.

To erase the current input and launch a new completion session with all currently matching candidates press S-SPC (ivy-restrict-to-matches).

To quickly select a candidate on the current screen, press C-' (ivy-avy). This requires avy to be installed. For example, if you’re on the first match of the screen, C-' 5 is equivalent to C-n C-n C-n C-n C-m. This binding is great for swiper, since it’s the only way to resolve multiple matches on the same line.