Ivy User Manual

M-x package-install RET counsel RET

Ivy is installed as part of the counsel package, which is available from two different package archives, GNU ELPA and MELPA. For the latest stable version, use the GNU ELPA archives. For current hourly builds, use the MELPA archives.

Ivy is split into three packages: ivy, swiper and counsel; by installing counsel, the other two are brought in as dependencies. If you are not interested in the extra functionality provided by swiper and counsel, you can install only ivy.

See the code below for adding MELPA to the list of package archives:

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "https://melpa.org/packages/"))

After this do M-x package-refresh-contents RET, followed by M-x package-install RET counsel RET.

For package manager details, see emacs#Packages.

Why install from Git?

• No need to wait for MELPA's hourly builds
• Easy to revert to previous versions
• Contribute to Ivy's development; send patches; pull requests

Configuration steps

First clone the Swiper repository with:

cd ~/git && git clone https://github.com/abo-abo/swiper
cd swiper && make compile

Second, add these lines to the Emacs init file:

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

Then, update the code with:

git pull
make

Here are some basic settings particularly useful for new Ivy users:

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

If you want, you can go without any customizations at all. The above settings are the most bang for the buck in terms of customization. So users that typically don't like customize a lot are advised to look at these settings first.

For more advanced customizations, refer to M-x describe-variable documentation.

Here is a list of commands that are useful to be bound globally, along with some sample bindings:

Ivy-based interface to standard commands

(global-set-key (kbd "C-s") 'swiper-isearch)
(global-set-key (kbd "M-x") 'counsel-M-x)
(global-set-key (kbd "C-x C-f") 'counsel-find-file)
(global-set-key (kbd "M-y") 'counsel-yank-pop)
(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-find-library)
(global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
(global-set-key (kbd "<f2> u") 'counsel-unicode-char)
(global-set-key (kbd "<f2> j") 'counsel-set-variable)
(global-set-key (kbd "C-x b") 'ivy-switch-buffer)
(global-set-key (kbd "C-c v") 'ivy-push-view)
(global-set-key (kbd "C-c V") 'ivy-pop-view)

Ivy-based interface to shell and system tools

(global-set-key (kbd "C-c c") 'counsel-compile)
(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 L") 'counsel-git-log)
(global-set-key (kbd "C-c k") 'counsel-rg)
(global-set-key (kbd "C-c m") 'counsel-linux-app)
(global-set-key (kbd "C-c n") 'counsel-fzf)
(global-set-key (kbd "C-x l") 'counsel-locate)
(global-set-key (kbd "C-c J") 'counsel-file-jump)
(global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
(global-set-key (kbd "C-c w") 'counsel-wmctrl)

Ivy-resume and other commands

ivy-resume resumes the last Ivy-based completion.

(global-set-key (kbd "C-c C-r") 'ivy-resume)
(global-set-key (kbd "C-c b") 'counsel-bookmark)
(global-set-key (kbd "C-c d") 'counsel-descbinds)
(global-set-key (kbd "C-c g") 'counsel-git)
(global-set-key (kbd "C-c o") 'counsel-outline)
(global-set-key (kbd "C-c t") 'counsel-load-theme)
(global-set-key (kbd "C-c F") 'counsel-org-file)

You can also enable counsel-mode to make some global key binding remapping for you.

Ivy includes several minibuffer bindings, which are defined in the ivy-minibuffer-map keymap variable. The most frequently used ones are described here.

swiper or counsel-M-x add more key bindings through the keymap argument to ivy-read. These keys, also active in the minibuffer, are described under their respective commands.

A key feature of ivy-minibuffer-map is its full editing capability where the familiar C-a, C-f, M-d, M-DEL, M-b, M-w, C-k, C-y key bindings work the same as in fundamental-mode.

ivy--regex-plus is Ivy's default completion method.

ivy--regex-plus matches by splitting the input by spaces and rebuilding it into a regex.

As the search string is typed in Ivy's minibuffer, it is transformed into valid regex syntax. If the string is "for example", it is transformed into

"\\(for\\).*\\(example\\)"

which in regex terminology matches "for" followed by a wild card and then "example". Note how Ivy uses the space character to build wild cards. To match a literal white space, use an extra space. So to match one space type two spaces, to match two spaces type three spaces, and so on.

As Ivy transforms typed characters into regex strings, it provides an intuitive feedback through font highlights.

Ivy supports regexp negation with "!". For example, "define key ! ivy quit" first selects everything matching "define.*key", then removes everything matching "ivy", and finally removes everything matching "quit". What remains is the final result set of the negation regexp.

Since Ivy treats minibuffer input as a regexp, the standard regexp identifiers work: "^", "$", "\b" or "[a-z]". The exceptions are spaces, which translate to ".*", and "!" that signal the beginning of a negation group.

ivy--regex-ignore-order ignores the order of regexp tokens when searching for matching candidates. For instance, the input "for example" will match "example test for".

ivy--regex-fuzzy splits each character with a wild card. Searching for "for" returns all "f.*o.*r" matches, resulting in a large number of hits. Yet some searches need these extra hits. Ivy sorts such large lists using flx package's scoring mechanism, if it's installed.

C-o m toggles the current regexp builder.

ivy-current-match

Highlights the currently selected candidate.

ivy-minibuffer-match-face-1

Highlights the background of the match.

ivy-minibuffer-match-face-2

Highlights the first (modulo 3) matched group.

ivy-minibuffer-match-face-3

Highlights the second (modulo 3) matched group.

ivy-minibuffer-match-face-4

Highlights the third (modulo 3) matched group.

ivy-confirm-face

Highlights the "(confirm)" part of the prompt.

When confirm-nonexistent-file-or-buffer set to t, then confirming non-existent files in ivy-mode requires an additional RET.

The confirmation prompt will use this face.

For example:

(setq confirm-nonexistent-file-or-buffer t)

Then call find-file, enter "eldorado" and press RET - the prompt will be appended with "(confirm)". Press RET once more to confirm, or any key to continue the completion.

ivy-match-required-face

Highlights the "(match required)" part of the prompt.

When completions have to match available candidates and cannot take random input, the "(match required)" prompt signals this constraint.

For example, call describe-variable, enter "waldo" and press RET - "(match required)" is prompted. Press any key for the prompt to disappear.

ivy-subdir

Highlights directories when completing file names.

ivy-remote

Highlights remote files when completing file names.

ivy-virtual

Highlights virtual buffers when completing buffer names.

Virtual buffers correspond to bookmarks and recent files list, recentf.

Enable virtual buffers with:

(setq ivy-use-virtual-buffers t)

ivy-modified-buffer

Highlights modified buffers when switching buffer.

ivy-modified-outside-buffer

Highlights buffers modified outside Emacs when switching buffer.

This takes precedence over ivy-modified-buffer.

User Option ivy-count-format

A string that specifies display of number of candidates and current candidate, if one exists.

The number of matching candidates by default is shown as a right- padded integer value.

To disable showing the number of candidates:

(setq ivy-count-format "")

To also display the current candidate:

(setq ivy-count-format "(%d/%d) ")

The format-style switches this variable uses are described in the format documentation.

User Option ivy-display-style

Specifies highlighting candidates in the minibuffer.

The default setting is 'fancy in Emacs versions 24.4 or newer.

Set ivy-display-style to nil for a plain minibuffer.

User Option ivy-on-del-error-function

Specifies what to do when DEL (ivy-backward-delete-char) fails.

This is usually the case when there is no text left to delete, i.e., when DEL is typed at the beginning of the minibuffer.

The default behavior is to quit the completion after DEL – a handy key to invoke after mistakenly triggering a completion.

org-mode

org-mode versions 8.3.3 or later obey completing-read-function (which ivy-mode sets). Try refiling headings with similar names to appreciate ivy-mode.

magit

Uses ivy by default if Ivy is installed.

find-file-in-project

Uses ivy by default if Ivy is installed.

projectile

Projectile requires this setting for ivy completion:

(setq projectile-completion-system 'ivy)

helm-make

Helm-make requires this setting for ivy completion.

(setq helm-make-completion-method 'ivy)

automatically integrated packages

Ivy re-uses the following packages if they are installed: avy, amx or smex, flx, and wgrep.

Since file name completion is ubiquitous, Ivy provides extra bindings that work here:

C-j (ivy-alt-done)

On a directory, restarts completion from that directory.

On a file or ./, exit completion with the selected candidate.

DEL (ivy-backward-delete-char)

Restart the completion in the parent directory if current input is empty.

// (self-insert-command)

Switch to the root directory.

~ (self-insert-command)

Switch to the home directory.

/ (self-insert-command)

If the current input matches an existing directory name exactly, switch the completion to that directory.

C-M-y (ivy-insert-current-full)

Insert the current full path, in case you want to edit a part of it.

M-r (ivy-toggle-regexp-quote)

Toggle between input as regexp or not.

Switch to matching literally since file names include ., which is for matching any char in regexp mode.

User Option ivy-extra-directories

Decide if you want to see ../ and ./ during file name completion.

Reason to remove: ../ is the same as DEL.

Reason not to remove: navigate anywhere with only C-n, C-p and C-j.

Likewise, ./ can be removed.

History

File history works the same with M-p, M-n, and C-r, but uses a custom code for file name completion that cycles through files previously opened. It also works with TRAMP files.

User Option ivy-use-virtual-buffers

When non-nil, add recentf-mode and bookmarks to ivy-switch-buffer completion candidates.

Adding this to Emacs init file:

(setq ivy-use-virtual-buffers t)

will add additional virtual buffers to the buffers list for recent files. Selecting such virtual buffers, which are highlighted with ivy-virtual face, will open the corresponding file.

The main advantages of counsel- functions over their basic equivalents in ivy-mode are:

1. Multi-actions and non-exiting actions work.
2. ivy-resume can resume the last completion session.
3. Customize ivy-set-actions, ivy-re-builders-alist.
4. Customize individual keymaps, such as counsel-describe-map, counsel-git-grep-map, or counsel-find-file-map, instead of customizing ivy-minibuffer-map that applies to all completion sessions.

prompt

A prompt string normally ending in a colon and a space. ivy-count-format is prepended to it during completion.

collection

Either a list of strings, a function, an alist or a hash table.

If a function, then it has to be compatible with all-completions.

predicate

Is a function to filter the initial collection. It has to be compatible with all-completions. Tip: most of the time, it's simpler to just apply this filter to the collection argument itself, e.g. (cl-remove-if-not predicate collection).

require-match

When set to a non-nil value, input must match one of the candidates. Custom input is not accepted.

initial-input

This string argument is included for compatibility with completing-read, which inserts it into the minibuffer.

It's recommended to use the preselect argument instead of this.

history

Name of the symbol to store history. See completing-read.

preselect

Determines which one of the candidates to initially select.

When set to an integer value, select the candidate with that index value.

When set to any other non-nil value, select the first candidate matching this value. Comparison is first done with equal. If this fails, and when applicable, match preselect as a regular expression.

Every time the input becomes empty, the item corresponding to preselect is selected.

keymap

A keymap to be composed with ivy-minibuffer-map. This keymap has priority over ivy-minibuffer-map and can be modified at any later stage.

update-fn

Is the function called each time the current candidate changes. This function takes no arguments and is called in the minibuffer's post-command-hook. See swiper for an example usage.

sort

When non-nil, use ivy-sort-functions-alist to sort the collection as long as the collection is not larger than ivy-sort-max-size.

action

Is the function to call after selection. It takes a string argument.

unwind

Is the function to call before exiting completion. It takes no arguments. This function is called even if the completion is interrupted with C-g. See swiper for an example usage.

re-builder

Is a function that takes a string and returns a valid regex. See Completion Styles for details.

matcher

Is a function that takes a regex string and a list of strings and returns a list of strings matching the regex. Any ordinary Emacs matching function will suffice, yet finely tuned matching functions can be used. See counsel-find-file for an example usage.

dynamic-collection

When non-nil, collection will be used to dynamically generate the candidates each time the input changes, instead of being used once statically with all-completions to generate a list of strings. See counsel-locate for an example usage.

caller

Is a symbol that uniquely identifies the function that called ivy-read, which may be useful for further customizations.

This is a typical example of a function with a non-async collection, which is a collection where all the strings in the collection are known prior to any input from the user.

Only the first two arguments (along with action) are essential - the rest of the arguments are for fine-tuning, and could be omitted.

The action argument could also be omitted - but then ivy-read would do nothing except returning the string result, which you could later use yourself. However, it's recommended that you use the action argument.

(defun counsel-describe-function ()
  "Forward to `describe-function'."
  (interactive)
  (ivy-read "Describe function: "
            (let (cands)
              (mapatoms
               (lambda (x)
                 (when (fboundp x)
                   (push (symbol-name x) cands))))
              cands)
            :keymap counsel-describe-map
            :preselect (ivy-thing-at-point)
            :history 'counsel-describe-symbol-history
            :require-match t
            :action (lambda (x)
                      (describe-function
                       (intern x)))
            :caller 'counsel-describe-function))

Here are the interesting features of the above function, in the order that they appear:

• The prompt argument is a simple string ending in ": ".
• The collection argument evaluates to a (large) list of strings.
• The keymap argument is for a custom keymap to supplement ivy-minibuffer-map.
• The preselect is provided by ivy-thing-at-point, which returns a symbol near the point. Ivy then selects the first candidate from the collection that matches this symbol. To select this pre-selected candidate, a RET will suffice. No further user input is necessary.
• The history argument is for keeping the history of this command separate from the common history in ivy-history.
• The require-match is set to t since it doesn't make sense to call describe-function on an un-interned symbol.
• The action argument calls describe-function on the interned selected candidate.
• The caller argument identifies this completion session. This is important, since with the collection being a list of strings and not a function name, the only other way for ivy-read to identify "who's calling" and to apply the appropriate customizations is to examine this-command. But this-command would be modified if another command called counsel-describe-function.

This is a typical example of a function with an async collection. Since the collection function cannot pre-compute all the locatable files in memory within reasonable limits (time or memory), it relies on user input to filter the universe of possible candidates to a manageable size while also continuing to search asynchronously for possible candidates. Both the filtering and searching continues with each character change of the input with rapid updates to the collection presented without idle waiting times. This live update will continue as long as there are likely candidates. Eventually updates to the minibuffer will stop after user input, filtering, and searching have exhausted looking for possible candidates.

Async collections suit long-running shell commands, such as locate. With each new input, a new process starts while the old process is killed. The collection is refreshed anew with each new process. Meanwhile the user can provide more input characters (for further narrowing) or select a candidate from the visible collection.

(defun counsel-locate-function (str)
  (or
   (ivy-more-chars)
   (progn
     (counsel--async-command
      (format "locate %s '%s'"
              (mapconcat #'identity counsel-locate-options " ")
              (counsel--elisp-to-pcre
               (ivy--regex str))))
     '("" "working..."))))

;;;###autoload
(defun counsel-locate (&optional initial-input)
  "Call the \"locate\" shell command.
INITIAL-INPUT can be given as the initial minibuffer input."
  (interactive)
  (ivy-read "Locate: " #'counsel-locate-function
            :initial-input initial-input
            :dynamic-collection t
            :history 'counsel-locate-history
            :action (lambda (file)
                      (with-ivy-window
                        (when file
                          (find-file file))))
            :unwind #'counsel-delete-process
            :caller 'counsel-locate))

Here are the interesting features of the above functions, in the order that they appear:

• counsel-locate-function takes a string argument and returns a list of strings. Note that it's not compatible with all-completions, but since we're not using that here, might as well use one argument instead of three.
• ivy-more-chars is a simple function that returns e.g. '("2 chars more") asking the user for more input.
• counsel--async-command is a very easy API simplification that takes a single string argument suitable for shell-command-to-string. So you could prototype your function as non-async using shell-command-to-string and split-string to produce a collection, then decide that you want async and simply swap in counsel--async-command.
• counsel-locate is an interactive function with an optional initial-input.
• #'counsel-locate-function is passed as the collection argument.
• dynamic-collection is set to t, since this is an async collection.
• action argument uses with-ivy-window wrapper, since we want to open the selected file in the same window from which counsel-locate was called.
• unwind argument is set to #'counsel-delete-process: when we press C-g we want to kill the running process created by counsel--async-command.
• caller argument identifies this command for easier customization.

This is another example to show how to associate additional values to each displayed strings.

(defun find-candidates-function (str pred _)
  (let ((props '(1 2))
        (strs '("foo" "foo2")))
    (cl-mapcar (lambda (s p) (propertize s 'property p))
               strs
               props)))

(defun find-candidates ()
  (interactive)
  (ivy-read "Find symbols: "
            #'find-candidates-function
            :action (lambda (x)
                      (message "Value: %s" (get-text-property 0 'property x)
                       ))))

Here are the interesting features of the above function:

• find-candidates-function builds up a list of strings and associates "foo" with the value 1 and "foo2" with 2.
• find-candidates is an interactive function.
• #'find-candidates is passed as the collection argument.
• action gets passed the selected string with the associated value. It then retrieves that value and displays it.