   Ivy manual, version 0.13.0

   Ivy is an interactive interface for completion in Emacs. Emacs uses
completion mechanism in a variety of contexts: code, menus, commands,
variables, functions, etc. Completion entails listing, sorting,
filtering, previewing, and applying actions on selected items. When
active, `ivy-mode' completes the selection process by narrowing
available choices while previewing in the minibuffer. Selecting the
final candidate is either through simple keyboard character inputs or
through powerful regular expressions.

   Copyright (C) 2015-2019 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts.  A copy of the license is included in the
     section entitled "GNU Free Documentation License".

Ivy User Manual
***************

1 Introduction
**************

Ivy is for quick and easy selection from a list. When Emacs prompts for
a string from a list of several possible choices, Ivy springs into
action to assist in narrowing and picking the right string from a vast
number of choices.

   Ivy strives for minimalism, simplicity, customizability and
discoverability.

Minimalism
..........

Uncluttered minibuffer is minimalism. Ivy shows the completion
defaults, the number of matches, and 10 candidate matches below the
input line. Customize `ivy-height' to adjust the number of candidate
matches displayed in the minibuffer.

Simplicity
..........

Simplicity is about Ivy's behavior in the minibuffer. It is also about
the code interface to extend Ivy's functionality. The minibuffer area
behaves as close to `fundamental-mode' as possible. `SPC' inserts a
space, for example, instead of being bound to the more complex
`minibuffer-complete-word'. Ivy's code uses easy-to-examine global
variables; avoids needless complications with branch-introducing custom
macros.

Customizability
...............

Customizability is about being able to use different methods and
interfaces of completion to tailor the selection process. For example,
adding a custom display function that points to a selected candidate
with `>', instead of highlighting the selected candidate with the
`ivy-current-match' face (see `ivy-format-functions-alist'). Or take
the customization of actions, say after the candidate function is
selected. `RET' uses `counsel-describe-function' to describe the
function, whereas `M-o d' jumps to that function's definition in the
code. The `M-o' prefix can be uniformly used with characters like `d' to
group similar actions.

Discoverability
...............

Ivy displays easily discoverable commands through the hydra facility.
`C-o' in the minibuffer displays a hydra menu. It opens up within an
expanded minibuffer area. Each menu item comes with short documentation
strings and highlighted one-key completions. So discovering even seldom
used keys is simply a matter of `C-o' in the minibuffer while in the
midst of the Ivy interaction. This discoverability minimizes exiting
Ivy interface for documentation look-ups.

2 Installation
**************

Install Ivy automatically through Emacs's package manager, or manually
from Ivy's development repository.

   Emacs 24.3 is the oldest version to run Ivy. Emacs 24.4 is the oldest
version that runs Ivy with fancy faces display.

2.1 Installing from Emacs Package Manager
=========================================

`M-x' `package-install' `RET' `ivy' `RET'

   Ivy is installed as part of `ivy' package, which is available from
two different package archives, GNU ELPA and MELPA. For the latest
stable version, use the GNU ELPA archives using the above M-x command.

   For current hourly builds, use the MELPA archives. In MELPA, Ivy is
split into three packages: `ivy', `swiper' and `counsel'; you can simply
install `counsel' which will bring in the other two as dependencies.
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 Packages (emacs).

2.2 Installing from the Git repository
======================================

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

3 Getting started
*****************

First enable Ivy completion everywhere:

     (ivy-mode 1)

   Note: `ivy-mode' can be toggled on and off with `M-x' `ivy-mode'.

3.1 Basic customization
=======================

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.

4 Key bindings
**************

4.1 Global key bindings
=======================

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.

4.2 Minibuffer key bindings
===========================

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'.

4.2.1 Key bindings for navigation
---------------------------------

   * `C-n' (`ivy-next-line') selects the next candidate

   * `C-p' (`ivy-previous-line') selects the previous candidate

   * `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 `ivy-height' lines

   * `M-v' (`ivy-scroll-down-command') scrolls down by `ivy-height'
     lines

 -- User Option: ivy-wrap
     Specifies the wrap-around behavior for `C-n' and `C-p'. When
     `ivy-wrap' is set to `t', `ivy-next-line' and `ivy-previous-line'
     will cycle past the last and the first candidates respectively.

     Wrap-around behavior is off by default.

 -- User Option: ivy-height
     Use this option to adjust the minibuffer height, which also
     affects scroll size when using `C-v' and `M-v' key bindings.

     `ivy-height' is 10 lines by default.

4.2.2 Key bindings for single selection, action, then exit minibuffer
---------------------------------------------------------------------

Ivy can offer several actions from which to choose which action to run.
This "calling an action" operates on the selected candidate. For
example, when viewing a list of files, one action could open it for
editing, one to view it, another to invoke a special function, and so
on. Custom actions can be added to this interface. The precise action
to call on the selected candidate can be delayed until after the
narrowing is completed. No need to exit the interface if unsure which
action to run. This delayed flexibility and customization of actions
extends usability of lists in Emacs.

`C-m' or `RET' (`ivy-done')
...........................

Calls the default action and then exits the minibuffer.

`M-o' (`ivy-dispatching-done')
..............................

Presents valid actions from which to choose. When only one action is
available, there is no difference between `M-o' and `C-m'.

`C-j' (`ivy-alt-done')
......................

When completing file names, selects the current directory candidate and
starts a new completion session there. Otherwise, it is the same as
`ivy-done'.

`TAB' (`ivy-partial-or-done')
.............................

Attempts partial completion, extending current input as much as
possible. `TAB TAB' is the same as `C-j' (`ivy-alt-done').

   Example ERT test:

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

`C-M-j' (`ivy-immediate-done')
..............................

Exits with _the current input_ instead of _the current candidate_ (like
other commands).

   This is useful e.g. when you call `find-file' to create a new file,
but the desired name matches an existing file. In that case, using
`C-j' would select that existing file, which isn't what you want - use
this command instead.

`C-'' (`ivy-avy')
.................

Uses avy to select one of the candidates on the current candidate page.
This can often be faster than multiple `C-n' or `C-p' keystrokes
followed by `C-m'.

4.2.3 Key bindings for multiple selections and actions, keep minibuffer open
----------------------------------------------------------------------------

For repeatedly applying multiple actions or acting on multiple
candidates, Ivy does not close the minibuffer between commands. It
keeps the minibuffer open for applying subsequent actions.

   Adding an extra meta key to the normal key chord invokes the special
version of the regular commands that enables applying multiple actions.

`C-M-m' (`ivy-call')
....................

Is the non-exiting version of `C-m' (`ivy-done').

   Instead of closing the minibuffer, `C-M-m' allows selecting another
candidate or another action. For example, `C-M-m' on functions list
invokes `describe-function'. When combined with `C-n', function
descriptions can be invoked quickly in succession.

`C-M-o' (`ivy-dispatching-call')
................................

Is the non-exiting version of `M-o' (`ivy-dispatching-done').

   For example, during the `counsel-rhythmbox' completion, press `C-M-o
e' to en-queue the selected candidate, followed by `C-n      C-m' to
play the next candidate - the current action reverts to the default one
after `C-M-o'.

`C-M-n' (`ivy-next-line-and-call')
..................................

Combines `C-n' and `C-M-m'. Moves to next line and applies an action.

   Comes in handy when opening multiple files from `counsel-find-file',
`counsel-git-grep', `counsel-ag', `counsel-rg', or `counsel-locate'
lists. Just hold `C-M-n' for rapid-fire default action on each
successive element of the list.

`C-M-p' (`ivy-previous-line-and-call')
......................................

Combines `C-p' and `C-M-m'.

   Similar to the above except it moves through the list in the other
direction.

`ivy-resume'
............

Recalls the state of the completion session just before its last exit.

   Useful after an accidental `C-m' (`ivy-done').

4.2.4 Key bindings that alter the minibuffer input
--------------------------------------------------

`M-n' (`ivy-next-history-element')
..................................

Cycles forward through the Ivy command history.

   Ivy updates an internal history list after each action. When this
history list is empty, `M-n' inserts symbol (or URL) at point into the
minibuffer.

`M-p' (`ivy-previous-history-element')
......................................

Cycles forward through the Ivy command history.

`M-i' (`ivy-insert-current')
............................

Inserts the current candidate into the minibuffer.

   Useful for copying and renaming files, for example: `M-i' to insert
the original file name string, edit it, and then `C-m' to complete the
renaming.

`M-j' (`ivy-yank-word')
.......................

Inserts the sub-word at point into the minibuffer.

   This is similar to `C-s C-w' with `isearch'.  Ivy reserves `C-w' for
`kill-region'.  See also `ivy-yank-symbol' and `ivy-yank-char'.

`S-SPC' (`ivy-restrict-to-matches')
...................................

Deletes the current input, and resets the candidates list to the
currently restricted matches.

   This is how Ivy provides narrowing in successive tiers.

`C-r' (`ivy-reverse-i-search')
..............................

Starts a recursive completion session through the command's history.

   This works just like `C-r' at the bash command prompt, where the
completion candidates are the history items. Upon completion, the
selected candidate string is inserted into the minibuffer.

4.2.5 Other key bindings
------------------------

`M-w' (`ivy-kill-ring-save')
............................

Copies selected candidates to the kill ring.

   Copies the region if the region is active.

4.2.6 Hydra in the minibuffer
-----------------------------

`C-o' (`hydra-ivy/body')
........................

Invokes the hydra menu with short key bindings.

   When Hydra is active, minibuffer editing is disabled and menus
display short aliases:

Short   Normal      Command name
------------------------------------------------
`o'     `C-g'       `keyboard-escape-quit'
`j'     `C-n'       `ivy-next-line'
`k'     `C-p'       `ivy-previous-line'
`h'     `M-<'       `ivy-beginning-of-buffer'
`l'     `M->'       `ivy-end-of-buffer'
`d'     `C-m'       `ivy-done'
`f'     `C-j'       `ivy-alt-done'
`g'     `C-M-m'     `ivy-call'
`u'     `C-c C-o'   `ivy-occur'

   Hydra reduces key strokes, for example: `C-n C-n C-n C-n' is `C-o
jjjj' in Hydra.

   Hydra menu offers these additional bindings:

`c' (`ivy-toggle-calling')
..........................

Toggle calling the action after each candidate change. It modifies `j'
to `jg', `k' to `kg' etc.

`m' (`ivy-rotate-preferred-builders')
.....................................

Rotate the current regexp matcher.

`>' (`ivy-minibuffer-grow')
...........................

Increase `ivy-height' for the current minibuffer.

`<' (`ivy-minibuffer-shrink')
.............................

Decrease `ivy-height' for the current minibuffer.

`w' (`ivy-prev-action')
.......................

Select the previous action.

`s' (`ivy-next-action')
.......................

Select the next action.

`a' (`ivy-read-action')
.......................

Use a menu to select an action.

`C' (`ivy-toggle-case-fold')
............................

Toggle case folding (match both upper and lower case characters for
lower case input).

   Hydra menu also offers bindings for marking multiple candidates:

Key     Command name
--------------------------------
`m'     `ivy-mark'
`u'     `ivy-unmark'
`DEL'   `ivy-unmark-backward'
`t'     `ivy-toggle-marks'

   The action is called on each marked candidate one by one.

4.2.7 Saving the current completion session to a buffer
-------------------------------------------------------

`C-c C-o' (`ivy-occur')
.......................

Saves the current candidates to a new buffer and exits completion.

   The new buffer is read-only and has a few useful bindings defined.

`RET' or `f' (`ivy-occur-press')
................................

Call the current action on the selected candidate.

`mouse-1' (`ivy-occur-click')
.............................

Call the current action on the selected candidate.

`j' (`next-line')
.................

Move to next line.

`k' (`previous-line')
.....................

Move to previous line.

`a' (`ivy-occur-read-action')
.............................

Read an action and make it current for this buffer.

`o' (`ivy-occur-dispatch')
..........................

Read an action and call it on the selected candidate.

`q' (`quit-window')
...................

Bury the current buffer.

   Ivy has no limit on the number of active buffers like these.

   Ivy takes care of naming buffers uniquely by constructing descriptive
names. For example: `*ivy-occur counsel-describe-variable "function$*'.

5 Completion Styles
*******************

Ivy's completion functions rely on a regex builder - a function that
transforms a string input to a string regex. All current candidates
simply have to match this regex. Each collection can be assigned its
own regex builder by customizing `ivy-re-builders-alist'.

   The keys of this alist are collection names, and the values are one
of the following:
   * `ivy--regex'

   * `ivy--regex-plus'

   * `ivy--regex-ignore-order'

   * `ivy--regex-fuzzy'

   * `regexp-quote'

   A catch-all key, `t', applies to all collections that don't have
their own key.

   The default is:

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

   This example shows a custom regex builder assigned to file name
completion:

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

   Here, `read-file-name-internal' is a function that is passed as the
second argument to `completing-read' for file name completion.

   The regex builder resolves as follows (in order of priority):
  1. `re-builder' argument passed to `ivy-read'.

  2. `collection' argument passed to `ivy-read' is a function and has an
     entry on `ivy-re-builders-alist'.

  3. `caller' argument passed to `ivy-read' has an entry on
     `ivy-re-builders-alist'.

  4. `this-command' has an entry on `ivy-re-builders-alist'.

  5. `t' has an entry on `ivy-re-builders-alist'.

  6. `ivy--regex'.

5.1 ivy-regex-plus
==================

`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.

5.2 ivy-regex-ignore-order
==========================

`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"'.

5.3 ivy-regex-fuzzy
===================

`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.

6 Customization
***************

6.1 Faces
=========

`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'
.........................