1 \input texinfo @c -*- texinfo -*-
3 @setfilename ./ivy.info
4 @settitle Ivy User Manual
5 @documentencoding UTF-8
11 Ivy manual, version 0.7.0
13 Ivy is an interactive interface for completion in Emacs. Emacs uses
14 completion mechanism in a variety of contexts: code, menus, commands,
15 variables, functions, etc. Completion entails listing, sorting,
16 filtering, previewing, and applying actions on selected items. When
17 active, @code{ivy-mode} completes the selection process by narrowing
18 available choices while previewing in the minibuffer. Selecting the
19 final candidate is either through simple keyboard character inputs or
20 through powerful regular expressions. @end ifnottex
22 Copyright @copyright{} 2015 Free Software Foundation, Inc.
25 Permission is granted to copy, distribute and/or modify this document
26 under the terms of the GNU Free Documentation License, Version 1.3 or
27 any later version published by the Free Software Foundation; with no
28 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
29 and with the Back-Cover Texts as in (a) below. A copy of the license
30 is included in the section entitled ``GNU Free Documentation License.''
32 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
33 modify this GNU manual.''
39 * Ivy: (ivy). Using Ivy for completion.
44 @title Ivy User Manual
47 @vskip 0pt plus 1filll
68 --- The Detailed Node Listing ---
72 * Installing from Emacs Package Manager::
73 * Installing from the Git repository::
77 * Basic customization::
81 * Global key bindings::
82 * Minibuffer key bindings::
84 Minibuffer key bindings
86 * Key bindings for navigation::
87 * Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
88 * Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
89 * Key bindings that alter minibuffer input::
90 * Other key bindings::
91 * Hydra in the minibuffer::
92 * Saving the current completion session to a buffer::
96 * ivy--regex-ignore-order::
102 @chapter Introduction
104 Ivy is for quick and easy selection from a list. When Emacs prompts
105 for a string from a list of several possible choices, Ivy springs into
106 action to assist in narrowing and picking the right string from a vast
109 Ivy strives for minimalism, simplicity, customizability and
112 @subsubheading Minimalism
113 Uncluttered minibuffer is minimalism. Ivy shows the completion
114 defaults, the number of matches, and 10 candidate matches below the
115 input line. Customize @code{ivy-length} to adjust the number of candidate
116 matches displayed in the minibuffer.
118 @subsubheading Simplicity
119 Simplicity is about Ivy's behavior in the minibuffer. It is also about
120 the code interface to extend Ivy's functionality. The minibuffer area
121 behaves as close to @code{fundamental-mode} as possible. @kbd{SPC} inserts a
122 space, for example, instead of being bound to the more complex
123 @code{minibuffer-complete-word}. Ivy's code uses easy-to-examine global
124 variables; avoids needless complications with branch-introducing
127 @subsubheading Customizability
128 Customizability is about being able to use different methods and
129 interfaces of completion to tailor the selection process. For example,
130 adding a custom display function that points to a selected candidate
131 with @code{->}, instead of highlighting the selected candidate with the
132 @code{ivy-current-match} face. Or take the customization of actions, say
133 after the candidate function is selected. @kbd{RET} uses
134 @code{counsel-describe-function} to describe the function, whereas @kbd{M-o d}
135 jumps to that function's definition in the code. The @kbd{M-o} prefix can
136 be uniformly used with characters like @kbd{d} to group similar actions.
138 @subsubheading Discoverability
139 Ivy displays easily discoverable commands through the hydra facility.
140 @kbd{C-o} in the minibuffer displays a hydra menu. It opens up within an
141 expanded minibuffer area. Each menu item comes with short
142 documentation strings and highlighted one-key completions. So
143 discovering even seldom used keys is simply a matter of @kbd{C-o} in the
144 minibuffer while in the midst of the Ivy interaction. This
145 discoverability minimizes exiting Ivy interface for documentation
149 @chapter Installation
151 Install Ivy automatically through Emacs's package manager, or manually
152 from Ivy's development repository.
154 * Installing from Emacs Package Manager::
155 * Installing from the Git repository::
158 @node Installing from Emacs Package Manager
159 @section Installing from Emacs Package Manager
161 @kbd{M-x} @code{package-install} @kbd{RET} @code{swiper} @kbd{RET}
163 Ivy is installed as part of @code{swiper} package. @code{swiper} is available
164 from two different package archives, GNU ELPA and MELPA. For the
165 latest stable version, use the GNU ELPA archives using the above M-x
168 For current hourly builds, use the MELPA archives. See the code below
169 for adding MELPA to the list of package archives:
174 (add-to-list 'package-archives
175 '("melpa" . "http://melpa.org/packages/"))
178 After this do @kbd{M-x} @code{package-refresh-contents} @kbd{RET}, followed by
179 @kbd{M-x} @code{package-install} @kbd{RET} @code{swiper} @kbd{RET}.
181 For package manager details, see @ref{Packages,,,emacs,}.
183 @node Installing from the Git repository
184 @section Installing from the Git repository
186 Why install from Git?
190 No need to wait for MELPA's hourly builds
192 Easy to revert to previous versions
194 Contribute to Ivy's development; send patches; pull requests
197 @strong{Configuration steps}
199 First clone the Swiper repository:
202 cd ~/git && git clone https://github.com/abo-abo/swiper
203 cd swiper && make compile
206 Then add this to Emacs init:
209 (add-to-list 'load-path "~/git/swiper/")
220 @node Getting started
221 @chapter Getting started
223 First enable Ivy completion everywhere:
230 Note: @code{ivy-mode} can be toggled on and off with @kbd{M-x} @code{ivy-mode}.
232 * Basic customization::
235 @node Basic customization
236 @section Basic customization
238 Here are some basic settings particularly useful for new Ivy
242 (setq ivy-use-virtual-buffers t)
244 (setq ivy-display-style 'fancy)
245 (setq ivy-count-format "(%d/%d) ")
248 For additional customizations, refer to @code{M-x describe-variable}
252 @chapter Key bindings
255 * Global key bindings::
256 * Minibuffer key bindings::
259 @node Global key bindings
260 @section Global key bindings
262 Recommended key bindings are:
263 @subsubheading Ivy-based interface to standard commands
266 (global-set-key (kbd "C-s") 'swiper)
267 (global-set-key (kbd "M-x") 'counsel-M-x)
268 (global-set-key (kbd "C-x C-f") 'counsel-find-file)
269 (global-set-key (kbd "<f1> f") 'counsel-describe-function)
270 (global-set-key (kbd "<f1> v") 'counsel-describe-variable)
271 (global-set-key (kbd "<f1> l") 'counsel-load-library)
272 (global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
273 (global-set-key (kbd "<f2> u") 'counsel-unicode-char)
275 @subsubheading Ivy-based interface to shell and system tools
278 (global-set-key (kbd "C-c g") 'counsel-git)
279 (global-set-key (kbd "C-c j") 'counsel-git-grep)
280 (global-set-key (kbd "C-c k") 'counsel-ag)
281 (global-set-key (kbd "C-x l") 'counsel-locate)
282 (global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
284 @subsubheading Ivy-resume and other commands
285 @code{ivy-resume} resumes the last Ivy-based completion.
288 (global-set-key (kbd "C-c C-r") 'ivy-resume)
291 @node Minibuffer key bindings
292 @section Minibuffer key bindings
294 Ivy includes several minibuffer bindings, which are defined in the
295 @code{ivy-minibuffer-map} keymap variable. The most frequently used ones
298 @code{swiper} or @code{counsel-M-x} add more through the @code{keymap} argument to
299 @code{ivy-read}. These keys, also active in the minibuffer, are described
300 under their respective commands.
302 * Key bindings for navigation::
303 * Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
304 * Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
305 * Key bindings that alter minibuffer input::
306 * Other key bindings::
307 * Hydra in the minibuffer::
308 * Saving the current completion session to a buffer::
311 @node Key bindings for navigation
312 @subsection Key bindings for navigation
316 @kbd{C-n} (@code{ivy-next-line}) selects the next candidate
318 @kbd{C-p} (@code{ivy-previous-line}) selects the previous candidate
320 @kbd{M-<} (@code{ivy-beginning-of-buffer}) selects the first candidate
322 @kbd{M->} (@code{ivy-end-of-buffer}) selects the last candidate
324 @kbd{C-v} (@code{ivy-scroll-up-command}) scrolls up by @code{ivy-height} lines
326 @kbd{M-v} (@code{ivy-scroll-down-command}) scrolls down by @code{ivy-height} lines
330 This user option allows to get the wrap-around behavior for @kbd{C-n} and
331 @kbd{C-p}. When set to @code{t}, @code{ivy-next-line} and @code{ivy-previous-line} will
332 cycle past the last and the first candidates respectively.
334 This behavior is off by default.
338 Use this variable to adjust the minibuffer height, and therefore the
339 scroll size for @kbd{C-v} and @kbd{M-v}.
342 @node Key bindings for single selection action then exit minibuffer
343 @subsection Key bindings for single selection, action, then exit minibuffer
345 Ivy can offer several actions from which to choose which action to
346 run. This "calling an action" operates on the selected candidate. For
347 example, when viewing a list of files, one action could open it for
348 editing, one to view it, another to invoke a special function, and so
349 on. Custom actions can be added to this interface. The precise action
350 to call on the selected candidate can be delayed until after the
351 narrowing is completed. No need to exit the interface if unsure which
352 action to run. This delayed flexibility and customization of actions
353 extends usability of lists in Emacs.
355 @kbd{C-m} or @kbd{RET} (@code{ivy-done}) calls the default action and exits the
358 @kbd{M-o} (@code{ivy-dispatching-done}) presents all available valid actions
359 from which to choose. When there is only one action available, there
360 is no difference between @kbd{M-o} and @kbd{C-m}.
362 @kbd{C-j} (@code{ivy-alt-done}) calls the alternate action, such as completing
363 a directory name in a file list whereas @kbd{C-m} will select that directory
364 and exit the minibuffer.
366 Exiting the minibuffer also closes the Ivy window (as specified by
367 @code{ivy-height}). This closing and exiting sequence is conveniently off
368 when applying multiple actions. Multiple actions and multiple
369 selections as covered in the next section of this manual.
371 @kbd{TAB} (@code{ivy-partial-or-done}) attempts partial completion, extending
372 current input as much as possible.
374 @kbd{TAB TAB} is the same as @kbd{C-j}.
376 @kbd{C-M-j} (@code{ivy-immediate-done}) is useful when there is no match for
377 the given input. Or there is an incorrect partial match. @kbd{C-M-j} with
378 @code{find-file} lists ignores the partial match and instead takes the
379 current input to create a new directory with @code{dired-create-directory}.
381 @code{ivy-immediate-done} illustrates how Ivy distinguishes between calling
382 an action on the @emph{currently selected} candidate and calling an action
383 on the @emph{current input}.
385 Invoking avy completion with @kbd{C-'} (@code{ivy-avy}).
386 @kbd{C-`} uses avy's visible jump mechanism, which can further reduce
387 Ivy's line-by-line scrolling that requires multiple @kbd{C-n} or @kbd{C-p}
390 @node Key bindings for multiple selections and actions keep minibuffer open
391 @subsection Key bindings for multiple selections and actions, keep minibuffer open
393 For repeatedly applying multiple actions or acting on multiple
394 candidates, Ivy does not close the minibuffer between commands. It
395 keeps the minibuffer open for applying subsequent actions.
397 Adding an extra meta key to the normal key chord invokes the special
398 version of the regular commands that enables applying multiple
401 @kbd{C-M-m} (@code{ivy-call}) is the non-exiting version of the default action,
402 @kbd{C-m} (@code{ivy-done}). Instead of closing the minibuffer, @kbd{C-M-m} allows
403 selecting another candidate or another action. For example, @kbd{C-M-m} on
404 functions list invokes @code{describe-function}. When combined with @kbd{C-n},
405 function descriptions can be invoked quickly in succession.
407 @kbd{RET} exits the minibuffer.
409 @code{ivy-resume} recalls the state of the completion session just before
410 its last exit. Useful after an accidental @kbd{C-m} (@code{ivy-done}).
412 @kbd{C-M-o} (@code{ivy-dispatching-call}) is a non-exiting version of @kbd{M-o}
413 (@code{ivy-dispatching-done}) that can accumulate candidates into a queue.
414 For example, for playback in @code{counsel-rhythmbox}, @kbd{C-M-o e} en-queues
415 the selected candidate, and @kbd{C-n C-m} plays the next one in the queue.
417 @kbd{C-M-n} (@code{ivy-next-line-and-call}) combines @kbd{C-n} and @kbd{C-M-m}. Applies
418 an action and moves to next line. Comes in handy when opening multiple
419 files from @code{counsel-find-file}, @code{counsel-git-grep}, @code{counsel-ag}, or
420 @code{counsel-locate} lists. Just hold @kbd{C-M-n} for rapid-fire default
421 action on each successive element of the list.
423 @kbd{C-M-p} (@code{ivy-previous-line-and-call}) combines @kbd{C-p} and @kbd{C-M-m}. Is
424 the same as above except that it moves through the list in the other
427 @node Key bindings that alter minibuffer input
428 @subsection Key bindings that alter minibuffer input
430 @kbd{M-n} (@code{ivy-next-history-element}) and @kbd{M-p}
431 (@code{ivy-previous-history-element}) cycle through the Ivy command
432 history. Ivy updates an internal history list after each action. When
433 this history list is empty, @kbd{M-n} inserts symbol (or URL) at point
436 @kbd{M-i} (@code{ivy-insert-current}) inserts the current candidate into the
437 minibuffer. Useful for copying and renaming files, for example: @kbd{M-i}
438 to insert the original file name string, edit it, and then @kbd{C-m} to
439 complete the renaming.
441 @kbd{M-j} (@code{ivy-yank-word}) inserts sub-word at point into minibuffer. This
442 is similar to @kbd{C-s C-w} with @code{isearch}. Ivy reserves @kbd{C-w} for
445 @kbd{S-SPC} (@code{ivy-restrict-to-matches}) deletes the current input, and
446 resets the candidates list to the currently restricted matches. This
447 is how Ivy provides narrowing in successive tiers.
449 @kbd{C-r} (@code{ivy-reverse-i-search}) works just like @kbd{C-r} at bash command
450 prompt, where the completion candidates are the history items. Upon
451 completion, the selected candidate string is inserted into the
454 @node Other key bindings
455 @subsection Other key bindings
457 @kbd{M-w} (@code{ivy-kill-ring-save}) copies selected candidates to the kill
458 ring; when the region is active, copies active region.
460 @node Hydra in the minibuffer
461 @subsection Hydra in the minibuffer
463 @kbd{C-o} (@code{hydra-ivy/body}) invokes Hydra menus with key shortcuts.
465 @kbd{C-o} or @kbd{i} resumes editing.
467 Hydra reduces key strokes, for example: @kbd{C-n C-n C-n C-n} is @kbd{C-o
468 jjjj} in Hydra. Hydra has other benefits besides certain shorter key
472 @kbd{<} and @kbd{>} to adjust height of minibuffer,
474 describes the current completion state, such as case folding and the
478 Minibuffer editing is disabled when Hydra is active.
480 @node Saving the current completion session to a buffer
481 @subsection Saving the current completion session to a buffer
483 @kbd{C-c C-o} (@code{ivy-occur}) saves the current candidates to a new buffer;
484 the list is active in the new buffer.
486 @kbd{RET} or @kbd{mouse-1} in the new buffer calls the appropriate action on
487 the selected candidate.
489 Ivy has no limit on the number of active buffers like these.
491 Ivy takes care of making these buffer names unique. It applies
492 descriptive names, for example: @code{*ivy-occur counsel-describe-variable
495 @node Completion styles
496 @chapter Completion styles
498 Ivy's completion functions rely on the highly configurable regex
504 (setq ivy-re-builders-alist
505 '((t . ivy--regex-plus)))
508 The default @code{ivy--regex-plus} narrowing is always invoked unless
509 specified otherwise. For example, file name completion may have a
510 custom completion function:
513 (setq ivy-re-builders-alist
514 '((read-file-name-internal . ivy--regex-fuzzy)
515 (t . ivy--regex-plus)))
518 Ivy's flexibility extends to using different styles of completion
519 mechanics (regex-builders) for different types of lists. Despite this
520 flexibility, Ivy operates within a consistent and uniform interface.
521 The main regex-builders currently in Ivy are:
524 * ivy--regex-ignore-order::
528 @node ivy--regex-plus
529 @section ivy--regex-plus
531 @code{ivy--regex-plus} is Ivy's default completion method.
533 @code{ivy--regex-plus} matches by splitting the input by spaces and
534 rebuilding it into a regex.
536 As the search string is typed in Ivy's minibuffer, it is transformed
537 into proper regex syntax. If the string is "for example", it is
541 "\\(for\\).*\\(example\\)"
544 which in regex terminology matches "for" followed by a wild card and
545 then "example". Note how Ivy uses the space character to build
546 wild cards. For literal white space matching in Ivy, use an extra space:
547 to match one space type two spaces, to match two spaces type three
550 As Ivy transforms typed characters into regex strings, it provides an
551 intuitive feedback through font highlights.
553 Ivy supports regexp negation with "!". For example, "define key ! ivy
554 quit" first selects everything matching "define.*key", then removes
555 everything matching "ivy", and finally removes everything matching
556 "quit". What remains is the final result set of the negation regexp.
559 Standard regexp identifiers work:
561 "^", "$", "\b" or "[a-z]"
564 Since Ivy treats minibuffer input as a regexp, standard regexp
565 identifiers work as usual. The exceptions are spaces, which
566 translate to ".*", and "!" that signal the beginning of a negation
569 @node ivy--regex-ignore-order
570 @section ivy--regex-ignore-order
572 @code{ivy--regex-ignore-order} ignores the order of regexp tokens when
573 searching for matching candidates. For instance, the input "for
574 example" will match "example test for". Otherwise @code{ivy--regex-plus}
575 normal behavior is to honor the order of regexp tokens.
577 @node ivy--regex-fuzzy
578 @section ivy--regex-fuzzy
580 @code{ivy--regex-fuzzy} splits each character with a wild card. Searching
581 for "for" returns all "f.*o.*r" matches, resulting in a large number
582 of hits. Yet some searches need these extra hits. Ivy sorts such
583 large lists using @code{flx} package's scoring mechanism, if it's
587 @chapter Variable Index