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.
23 Copyright (C) 2015 Free Software Foundation, Inc.
26 Permission is granted to copy, distribute and/or modify this document
27 under the terms of the GNU Free Documentation License, Version 1.3 or
28 any later version published by the Free Software Foundation; with no
29 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
30 and with the Back-Cover Texts as in (a) below. A copy of the license
31 is included in the section entitled ``GNU Free Documentation License.''
33 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
34 modify this GNU manual.''
40 * Ivy: (ivy). Using Ivy for completion.
45 @title Ivy User Manual
48 @vskip 0pt plus 1filll
73 --- The Detailed Node Listing ---
77 * Installing from Emacs Package Manager::
78 * Installing from the Git repository::
82 * Basic customization::
86 * Global key bindings::
87 * Minibuffer key bindings::
89 Minibuffer key bindings
91 * Key bindings for navigation::
92 * Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
93 * Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
94 * Key bindings that alter the minibuffer input::
95 * Other key bindings::
96 * Hydra in the minibuffer::
97 * Saving the current completion session to a buffer::
101 * ivy--regex-ignore-order::
113 * What are actions?::
114 * How can different actions be called?::
115 * How to modify the actions list?::
116 * Example - add two actions to each command::
117 * Example - define a new command with several actions::
119 Example - add two actions to each command
121 * How to undo adding the two actions::
122 * How to add actions to a specific command::
124 Example - define a new command with several actions
126 * Test the above function with @code{ivy-occur}::
129 * File Name Completion::
130 * Buffer Name Completion::
135 * Required arguments for @code{ivy-read}::
136 * Optional arguments for @code{ivy-read}::
137 * Example - @code{counsel-describe-function}::
138 * Example - @code{counsel-locate}::
143 @chapter Introduction
145 Ivy is for quick and easy selection from a list. When Emacs prompts
146 for a string from a list of several possible choices, Ivy springs into
147 action to assist in narrowing and picking the right string from a vast
150 Ivy strives for minimalism, simplicity, customizability and
153 @subsubheading Minimalism
155 Uncluttered minibuffer is minimalism. Ivy shows the completion
156 defaults, the number of matches, and 10 candidate matches below
157 the input line. Customize @code{ivy-height} to adjust the number of
158 candidate matches displayed in the minibuffer.
160 @subsubheading Simplicity
162 Simplicity is about Ivy's behavior in the minibuffer. It is also
163 about the code interface to extend Ivy's functionality. The
164 minibuffer area behaves as close to @code{fundamental-mode} as
165 possible. @kbd{SPC} inserts a space, for example, instead of being
166 bound to the more complex @code{minibuffer-complete-word}. Ivy's code
167 uses easy-to-examine global variables; avoids needless
168 complications with branch-introducing custom macros.
170 @subsubheading Customizability
172 Customizability is about being able to use different methods and
173 interfaces of completion to tailor the selection process. For
174 example, adding a custom display function that points to a
175 selected candidate with @code{->}, instead of highlighting the
176 selected candidate with the @code{ivy-current-match} face. Or take the
177 customization of actions, say after the candidate function is
178 selected. @kbd{RET} uses @code{counsel-describe-function} to describe the
179 function, whereas @kbd{M-o d} jumps to that function's definition in
180 the code. The @kbd{M-o} prefix can be uniformly used with characters
181 like @kbd{d} to group similar actions.
183 @subsubheading Discoverability
185 Ivy displays easily discoverable commands through the hydra
186 facility. @kbd{C-o} in the minibuffer displays a hydra menu. It
187 opens up within an expanded minibuffer area. Each menu item comes
188 with short documentation strings and highlighted one-key
189 completions. So discovering even seldom used keys is simply a
190 matter of @kbd{C-o} in the minibuffer while in the midst of the Ivy
191 interaction. This discoverability minimizes exiting Ivy interface
192 for documentation look-ups.
196 @chapter Installation
198 Install Ivy automatically through Emacs's package manager, or manually
199 from Ivy's development repository.
201 Emacs 24.3.1 is the oldest version to run Ivy. Emacs 24.5.1 is the
202 oldest version that runs Ivy with fancy faces display.
204 * Installing from Emacs Package Manager::
205 * Installing from the Git repository::
208 @node Installing from Emacs Package Manager
209 @section Installing from Emacs Package Manager
211 @kbd{M-x} @code{package-install} @kbd{RET} @code{swiper} @kbd{RET}
213 Ivy is installed as part of @code{swiper} package. @code{swiper} is available
214 from two different package archives, GNU ELPA and MELPA. For the
215 latest stable version, use the GNU ELPA archives using the above M-x
218 For current hourly builds, use the MELPA archives. See the code below
219 for adding MELPA to the list of package archives:
223 (add-to-list 'package-archives
224 '("melpa" . "http://melpa.org/packages/"))
227 After this do @kbd{M-x} @code{package-refresh-contents} @kbd{RET}, followed by
228 @kbd{M-x} @code{package-install} @kbd{RET} @code{swiper} @kbd{RET}.
230 For package manager details, see @ref{Packages,,,emacs,}.
232 @node Installing from the Git repository
233 @section Installing from the Git repository
235 @subsubheading Why install from Git?
239 No need to wait for MELPA's hourly builds
241 Easy to revert to previous versions
243 Contribute to Ivy's development; send patches; pull requests
248 @subsubheading Configuration steps
250 First clone the Swiper repository with:
253 cd ~/git && git clone https://github.com/abo-abo/swiper
254 cd swiper && make compile
257 Second, add these lines to the Emacs init file:
260 (add-to-list 'load-path "~/git/swiper/")
264 Then, update the code with:
272 @node Getting started
273 @chapter Getting started
275 First enable Ivy completion everywhere:
281 Note: @code{ivy-mode} can be toggled on and off with @kbd{M-x} @code{ivy-mode}.
283 * Basic customization::
286 @node Basic customization
287 @section Basic customization
289 Here are some basic settings particularly useful for new Ivy users:
292 (setq ivy-use-virtual-buffers t)
294 (setq ivy-count-format "(%d/%d) ")
297 If you want, you can go without any customizations at all. The above
298 settings are the most bang for the buck in terms of customization. So
299 users that typically don't like customize a lot are advised to look at
300 these settings first.
302 For more advanced customizations, refer to @code{M-x describe-variable}
306 @chapter Key bindings
309 * Global key bindings::
310 * Minibuffer key bindings::
313 @node Global key bindings
314 @section Global key bindings
316 The recommended key bindings are:
318 @subsubheading Ivy-based interface to standard commands
321 (global-set-key (kbd "C-s") 'swiper)
322 (global-set-key (kbd "M-x") 'counsel-M-x)
323 (global-set-key (kbd "C-x C-f") 'counsel-find-file)
324 (global-set-key (kbd "<f1> f") 'counsel-describe-function)
325 (global-set-key (kbd "<f1> v") 'counsel-describe-variable)
326 (global-set-key (kbd "<f1> l") 'counsel-load-library)
327 (global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
328 (global-set-key (kbd "<f2> u") 'counsel-unicode-char)
331 @subsubheading Ivy-based interface to shell and system tools
334 (global-set-key (kbd "C-c g") 'counsel-git)
335 (global-set-key (kbd "C-c j") 'counsel-git-grep)
336 (global-set-key (kbd "C-c k") 'counsel-ag)
337 (global-set-key (kbd "C-x l") 'counsel-locate)
338 (global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
341 @subsubheading Ivy-resume and other commands
343 @code{ivy-resume} resumes the last Ivy-based completion.
346 (global-set-key (kbd "C-c C-r") 'ivy-resume)
350 @node Minibuffer key bindings
351 @section Minibuffer key bindings
353 @vindex ivy-minibuffer-map
354 Ivy includes several minibuffer bindings, which are defined in the
355 @code{ivy-minibuffer-map} keymap variable. The most frequently used ones
358 @code{swiper} or @code{counsel-M-x} add more key bindings through the @code{keymap}
359 argument to @code{ivy-read}. These keys, also active in the minibuffer, are
360 described under their respective commands.
362 A key feature of @code{ivy-minibuffer-map} is its full editing capability
363 where the familiar @kbd{C-a}, @kbd{C-f}, @kbd{M-d}, @kbd{M-DEL}, @kbd{M-b}, @kbd{M-w}, @kbd{C-k},
364 @kbd{C-y} key bindings work the same as in @code{fundamental-mode}.
366 * Key bindings for navigation::
367 * Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
368 * Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
369 * Key bindings that alter the minibuffer input::
370 * Other key bindings::
371 * Hydra in the minibuffer::
372 * Saving the current completion session to a buffer::
375 @node Key bindings for navigation
376 @subsection Key bindings for navigation
380 @kbd{C-n} (@code{ivy-next-line}) selects the next candidate
382 @kbd{C-p} (@code{ivy-previous-line}) selects the previous candidate
384 @kbd{M-<} (@code{ivy-beginning-of-buffer}) selects the first candidate
386 @kbd{M->} (@code{ivy-end-of-buffer}) selects the last candidate
388 @kbd{C-v} (@code{ivy-scroll-up-command}) scrolls up by @code{ivy-height} lines
390 @kbd{M-v} (@code{ivy-scroll-down-command}) scrolls down by @code{ivy-height} lines
395 Specifies the wrap-around behavior for @kbd{C-n} and @kbd{C-p}. When
396 @code{ivy-wrap} is set to @code{t}, @code{ivy-next-line} and @code{ivy-previous-line}
397 will cycle past the last and the first candidates respectively.
399 Warp-around behavior is off by default.
403 Use this option to adjust the minibuffer height, which also
404 affects scroll size when using @kbd{C-v} and @kbd{M-v} key bindings.
406 @code{ivy-height} is 10 lines by default.
409 @node Key bindings for single selection action then exit minibuffer
410 @subsection Key bindings for single selection, action, then exit minibuffer
412 Ivy can offer several actions from which to choose which action to
413 run. This "calling an action" operates on the selected candidate. For
414 example, when viewing a list of files, one action could open it for
415 editing, one to view it, another to invoke a special function, and so
416 on. Custom actions can be added to this interface. The precise action
417 to call on the selected candidate can be delayed until after the
418 narrowing is completed. No need to exit the interface if unsure which
419 action to run. This delayed flexibility and customization of actions
420 extends usability of lists in Emacs.
422 @subsubheading @kbd{C-m} or @kbd{RET} (@code{ivy-done})
427 Calls the default action and then exits the minibuffer.
429 @subsubheading @kbd{M-o} (@code{ivy-dispatching-done})
430 @vindex ivy-dispatching-done
433 Presents valid actions from which to choose. When only one action
434 is available, there is no difference between @kbd{M-o} and @kbd{C-m}.
436 @subsubheading @kbd{C-j} (@code{ivy-alt-done})
440 When completing file names, selects the current directory
441 candidate and starts a new completion session there. Otherwise,
442 it is the same as @code{ivy-done}.
444 @subsubheading @kbd{TAB} (@code{ivy-partial-or-done})
445 @vindex ivy-partial-or-done
448 Attempts partial completion, extending current input as much as
449 possible. @kbd{TAB TAB} is the same as @kbd{C-j} (@code{ivy-alt-done}).
457 (ivy-read "Test: " '("can do" "can't, sorry" "other"))
463 @subsubheading @kbd{C-M-j} (@code{ivy-immediate-done})
464 @vindex ivy-immediate-done
467 Exits with @emph{the current input} instead of @emph{the current candidate}
468 (like other commands).
470 This is useful e.g. when you call @code{find-file} to create a new
471 file, but the desired name matches an existing file. In that
472 case, using @kbd{C-j} would select that existing file, which isn't
473 what you want - use this command instead.
475 @subsubheading @kbd{C-'} (@code{ivy-avy})
479 Uses avy to select one of the candidates on the current candidate
480 page. This can often be faster than multiple @kbd{C-n} or @kbd{C-p}
481 keystrokes followed by @kbd{C-m}.
484 @node Key bindings for multiple selections and actions keep minibuffer open
485 @subsection Key bindings for multiple selections and actions, keep minibuffer open
487 For repeatedly applying multiple actions or acting on multiple
488 candidates, Ivy does not close the minibuffer between commands. It
489 keeps the minibuffer open for applying subsequent actions.
491 Adding an extra meta key to the normal key chord invokes the special
492 version of the regular commands that enables applying multiple
495 @subsubheading @kbd{C-M-m} (@code{ivy-call})
499 Is the non-exiting version of @kbd{C-m} (@code{ivy-done}).
501 Instead of closing the minibuffer, @kbd{C-M-m} allows selecting
502 another candidate or another action. For example, @kbd{C-M-m} on
503 functions list invokes @code{describe-function}. When combined with
504 @kbd{C-n}, function descriptions can be invoked quickly in
507 @subsubheading @kbd{C-M-o} (@code{ivy-dispatching-call})
508 @vindex ivy-dispatching-call
511 Is the non-exiting version of @kbd{M-o} (@code{ivy-dispatching-done}).
513 For example, during the @code{counsel-rhythmbox} completion, press
514 @kbd{C-M-o e} to en-queue the selected candidate, followed by @kbd{C-n
515 C-m} to play the next candidate - the current action reverts to
516 the default one after @kbd{C-M-o}.
518 @subsubheading @kbd{C-M-n} (@code{ivy-next-line-and-call})
519 @vindex ivy-next-line-and-call
522 Combines @kbd{C-n} and @kbd{C-M-m}. Applies an action and moves to next
525 Comes in handy when opening multiple files from
526 @code{counsel-find-file}, @code{counsel-git-grep}, @code{counsel-ag}, or
527 @code{counsel-locate} lists. Just hold @kbd{C-M-n} for rapid-fire default
528 action on each successive element of the list.
530 @subsubheading @kbd{C-M-p} (@code{ivy-previous-line-and-call})
531 @vindex ivy-previous-line-and-call
534 Combines @kbd{C-p} and @kbd{C-M-m}.
536 Similar to the above except it moves through the list in the
539 @subsubheading @code{ivy-resume}
542 Recalls the state of the completion session just before its last
545 Useful after an accidental @kbd{C-m} (@code{ivy-done}).
548 @node Key bindings that alter the minibuffer input
549 @subsection Key bindings that alter the minibuffer input
551 @subsubheading @kbd{M-n} (@code{ivy-next-history-element})
552 @vindex ivy-next-history-element
555 Cycles forward through the Ivy command history.
557 Ivy updates an internal history list after each action. When this
558 history list is empty, @kbd{M-n} inserts symbol (or URL) at point
561 @subsubheading @kbd{M-p} (@code{ivy-previous-history-element})
562 @vindex ivy-previous-history-element
565 Cycles forward through the Ivy command history.
567 @subsubheading @kbd{M-i} (@code{ivy-insert-current})
568 @vindex ivy-insert-current
571 Inserts the current candidate into the minibuffer.
573 Useful for copying and renaming files, for example: @kbd{M-i} to
574 insert the original file name string, edit it, and then @kbd{C-m} to
575 complete the renaming.
577 @subsubheading @kbd{M-j} (@code{ivy-yank-word})
578 @vindex ivy-yank-word
581 Inserts the sub-word at point into the minibuffer.
583 This is similar to @kbd{C-s C-w} with @code{isearch}. Ivy reserves @kbd{C-w}
584 for @code{kill-region}.
586 @subsubheading @kbd{S-SPC} (@code{ivy-restrict-to-matches})
587 @vindex ivy-restrict-to-matches
590 Deletes the current input, and resets the candidates list to the
591 currently restricted matches.
593 This is how Ivy provides narrowing in successive tiers.
595 @subsubheading @kbd{C-r} (@code{ivy-reverse-i-search})
596 @vindex ivy-reverse-i-search
599 Starts a recursive completion session through the command's
602 This works just like @kbd{C-r} at the bash command prompt, where the
603 completion candidates are the history items. Upon completion, the
604 selected candidate string is inserted into the minibuffer.
607 @node Other key bindings
608 @subsection Other key bindings
610 @subsubheading @kbd{M-w} (@code{ivy-kill-ring-save})
611 @vindex ivy-kill-ring-save
614 Copies selected candidates to the kill ring.
616 Copies the region if the region is active.
619 @node Hydra in the minibuffer
620 @subsection Hydra in the minibuffer
622 @subsubheading @kbd{C-o} (@code{hydra-ivy/body})
625 Invokes the hydra menu with short key bindings.
628 When Hydra is active, minibuffer editing is disabled and menus
629 display short aliases:
631 @multitable {aaaaa} {aaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaa}
637 @tab @code{keyboard-escape-quit}
640 @tab @code{ivy-next-line}
643 @tab @code{ivy-previous-line}
646 @tab @code{ivy-beginning-of-buffer}
649 @tab @code{ivy-end-of-buffer}
655 @tab @code{ivy-alt-done}
661 @tab @code{ivy-occur}
664 Hydra reduces key strokes, for example: @kbd{C-n C-n C-n C-n} is @kbd{C-o
667 Hydra menu offers these additioanl bindings:
669 @subsubheading @kbd{c} (@code{ivy-toggle-calling})
670 @vindex ivy-toggle-calling
673 Toggle calling the action after each candidate change. It
674 modifies @kbd{j} to @kbd{jg}, @kbd{k} to @kbd{kg} etc.
676 @subsubheading @kbd{m} (@code{ivy-toggle-fuzzy})
677 @vindex ivy-toggle-fuzzy
680 Toggle the current regexp matcher.
682 @subsubheading @kbd{>} (@code{ivy-minibuffer-grow})
683 @vindex ivy-minibuffer-grow
686 Increase @code{ivy-height} for the current minibuffer.
688 @subsubheading @kbd{<} (@code{ivy-minibuffer-shrink})
689 @vindex ivy-minibuffer-shrink
692 Decrease @code{ivy-height} for the current minibuffer.
694 @subsubheading @kbd{w} (@code{ivy-prev-action})
695 @vindex ivy-prev-action
698 Select the previous action.
700 @subsubheading @kbd{s} (@code{ivy-next-action})
701 @vindex ivy-next-action
704 Select the next action.
706 @subsubheading @kbd{a} (@code{ivy-read-action})
707 @vindex ivy-read-action
710 Use a menu to select an action.
712 @subsubheading @kbd{C} (@code{ivy-toggle-case-fold})
713 @vindex ivy-toggle-case-fold
716 Toggle case folding (match both upper and lower case
717 characters for lower case input).
720 @node Saving the current completion session to a buffer
721 @subsection Saving the current completion session to a buffer
723 @subsubheading @kbd{C-c C-o} (@code{ivy-occur})
727 Saves the current candidates to a new buffer and exits
731 The new buffer is read-only and has a few useful bindings defined.
733 @subsubheading @kbd{RET} or @kbd{j} (@code{ivy-occur-press})
734 @vindex ivy-occur-press
738 Call the current action on the selected candidate.
740 @subsubheading @kbd{mouse-1} (@code{ivy-occur-click})
741 @vindex ivy-occur-click
744 Call the current action on the selected candidate.
746 @subsubheading @kbd{j} (@code{next-line})
751 @subsubheading @kbd{k} (@code{previous-line})
754 Move to previous line.
756 @subsubheading @kbd{a} (@code{ivy-occur-read-action})
757 @vindex ivy-occur-read-action
760 Read an action and make it current for this buffer.
762 @subsubheading @kbd{o} (@code{ivy-occur-dispatch})
763 @vindex ivy-occur-dispatch
766 Read an action and call it on the selected candidate.
768 @subsubheading @kbd{q} (@code{quit-window})
771 Bury the current buffer.
775 Ivy has no limit on the number of active buffers like these.
777 Ivy takes care of naming buffers uniquely by constructing descriptive
778 names. For example: @code{*ivy-occur counsel-describe-variable
781 @node Completion Styles
782 @chapter Completion Styles
784 Ivy's completion functions rely on a regex builder - a function that
785 transforms a string input to a string regex. All current candidates
786 simply have to match this regex. Each collection can be assigned its
787 own regex builder by customizing @code{ivy-re-builders-alist}.
789 The keys of this alist are collection names, and the values are one of
795 @code{ivy--regex-plus}
797 @code{ivy--regex-ignore-order}
799 @code{ivy--regex-fuzzy}
804 A catch-all key, @code{t}, applies to all collections that don't have their
810 (setq ivy-re-builders-alist
811 '((t . ivy--regex-plus)))
814 This example shows a custom regex builder assigned to file name
818 (setq ivy-re-builders-alist
819 '((read-file-name-internal . ivy--regex-fuzzy)
820 (t . ivy--regex-plus)))
823 Here, @code{read-file-name-internal} is a function that is passed as the
824 second argument to @code{completing-read} for file name completion.
826 The regex builder resolves as follows (in order of priority):
829 @code{re-builder} argument passed to @code{ivy-read}.
831 @code{collection} argument passed to @code{ivy-read} is a function and has an
832 entry on @code{ivy-re-builders-alist}.
834 @code{caller} argument passed to @code{ivy-read} has an entry on
835 @code{ivy-re-builders-alist}.
837 @code{this-command} has an entry on @code{ivy-re-builders-alist}.
839 @code{t} has an entry on @code{ivy-re-builders-alist}.
845 * ivy--regex-ignore-order::
849 @node ivy--regex-plus
850 @section ivy--regex-plus
852 @code{ivy--regex-plus} is Ivy's default completion method.
854 @code{ivy--regex-plus} matches by splitting the input by spaces and
855 rebuilding it into a regex.
857 As the search string is typed in Ivy's minibuffer, it is transformed
858 into valid regex syntax. If the string is @code{"for example"}, it is
862 "\\(for\\).*\\(example\\)"
865 which in regex terminology matches @code{"for"} followed by a wild card and
866 then @code{"example"}. Note how Ivy uses the space character to build wild
867 cards. To match a literal white space, use an extra space. So to match
868 one space type two spaces, to match two spaces type three spaces, and
871 As Ivy transforms typed characters into regex strings, it provides an
872 intuitive feedback through font highlights.
874 Ivy supports regexp negation with @code{"!"}.
875 For example, @code{"define key ! ivy quit"} first selects everything
876 matching @code{"define.*key"}, then removes everything matching @code{"ivy"},
877 and finally removes everything matching @code{"quit"}. What remains is the
878 final result set of the negation regexp.
880 Since Ivy treats minibuffer input as a regexp, the standard regexp
881 identifiers work: @code{"^"}, @code{"$"}, @code{"\b"} or @code{"[a-z]"}. The exceptions
882 are spaces, which translate to @code{".*"}, and @code{"!"} that signal the
883 beginning of a negation group.
885 @node ivy--regex-ignore-order
886 @section ivy--regex-ignore-order
888 @code{ivy--regex-ignore-order} ignores the order of regexp tokens when
889 searching for matching candidates. For instance, the input
890 @code{"for example"} will match @code{"example test for"}.
892 @node ivy--regex-fuzzy
893 @section ivy--regex-fuzzy
895 @code{ivy--regex-fuzzy} splits each character with a wild card. Searching
896 for @code{"for"} returns all @code{"f.*o.*r"} matches, resulting in a large
897 number of hits. Yet some searches need these extra hits. Ivy sorts
898 such large lists using @code{flx} package's scoring mechanism, if it's
901 @kbd{C-o m} toggles the current regexp builder.
904 @chapter Customization
916 @subsubheading @code{ivy-current-match}
917 @vindex ivy-current-match
919 Highlights the currently selected candidate.
921 @subsubheading @code{ivy-minibuffer-match-face-1}
922 @vindex ivy-minibuffer-match-face-1
924 Highlights the background of the match.
926 @subsubheading @code{ivy-minibuffer-match-face-2}
927 @vindex ivy-minibuffer-match-face-2
929 Highlights the first (modulo 3) matched group.
931 @subsubheading @code{ivy-minibuffer-match-face-3}
932 @vindex ivy-minibuffer-match-face-3
934 Highlights the second (modulo 3) matched group.
936 @subsubheading @code{ivy-minibuffer-match-face-4}
937 @vindex ivy-minibuffer-match-face-4
939 Highlights the third (modulo 3) matched group.
941 @subsubheading @code{ivy-confirm-face}
942 @vindex ivy-confirm-face
944 Highlights the "(confirm)" part of the prompt.
946 When @code{confirm-nonexistent-file-or-buffer} set to @code{t}, then
947 confirming non-existent files in @code{ivy-mode} requires an
948 additional @kbd{RET}.
950 The confirmation prompt will use this face.
955 (setq confirm-nonexistent-file-or-buffer t)
958 Then call @code{find-file}, enter "eldorado" and press @kbd{RET} - the
959 prompt will be appended with "(confirm)". Press @kbd{RET} once more
960 to confirm, or any key to continue the completion.
962 @subsubheading @code{ivy-match-required-face}
963 @vindex ivy-match-required-face
965 Highlights the "(match required)" part of the prompt.
967 When completions have to match available candidates and cannot
968 take random input, the "(match required)" prompt signals this
971 For example, call @code{describe-variable}, enter "waldo" and press
972 @kbd{RET} - "(match required)" is prompted.
973 Press any key for the prompt to disappear.
975 @subsubheading @code{ivy-subdir}
978 Highlights directories when completing file names.
980 @subsubheading @code{ivy-remote}
983 Highlights remote files when completing file names.
985 @subsubheading @code{ivy-virtual}
988 Highlights virtual buffers when completing buffer names.
990 Virtual buffers correspond to bookmarks and recent files list,
993 Enable virtual buffers with:
996 (setq ivy-use-virtual-buffers t)
1003 @defopt ivy-count-format
1004 A string that specifies display of number of candidates and
1005 current candidate, if one exists.
1007 The number of matching candidates by default is shown as a right-
1008 padded integer value.
1010 To disable showing the number of candidates:
1013 (setq ivy-count-format "")
1016 To also display the current candidate:
1019 (setq ivy-count-format "(%d/%d) ")
1022 The @code{format}-style switches this variable uses are described
1023 in the @code{format} documentation.
1026 @defopt ivy-display-style
1027 Specifies highlighting candidates in the minibuffer.
1029 The default setting is @code{'fancy} and valid only in Emacs versions
1032 Set @code{ivy-display-style} to @code{nil} for a plain minibuffer.
1035 @defopt ivy-on-del-error-function
1036 Specify what when @kbd{DEL} (@code{ivy-backward-delete-char}) throws.
1038 The default behavior is to quit the completion after @kbd{DEL} -- a
1039 handy key to invoke after mistakenly triggering a completion.
1046 * What are actions?::
1047 * How can different actions be called?::
1048 * How to modify the actions list?::
1049 * Example - add two actions to each command::
1050 * Example - define a new command with several actions::
1053 @node What are actions?
1054 @subsection What are actions?
1056 An action is a function that is called after you select a candidate
1057 during completion. This function takes a single string argument, which
1058 is the selected candidate.
1060 @subsubheading Window context when calling an action
1062 Currently, the action is executed in the minibuffer window
1063 context. This means e.g. that if you call @code{insert} the text will
1064 be inserted into the minibuffer.
1066 If you want to execute the action in the initial window from
1067 which the completion started, use the @code{with-ivy-window} wrapper
1071 (defun ivy-insert-action (x)
1077 @node How can different actions be called?
1078 @subsection How can different actions be called?
1082 @kbd{C-m} (@code{ivy-done}) calls the current action.
1084 @kbd{M-o} (@code{ivy-dispatching-done}) presents available actions for
1085 selection, calls it after selection, and then exits.
1087 @kbd{C-M-o} (@code{ivy-dispatching-call}) presents available actions for
1088 selection, calls it after selection, and then does not exit.
1091 @node How to modify the actions list?
1092 @subsection How to modify the actions list?
1094 Currently, you can append any amount of your own actions to the
1095 default list of actions. This can be done either for a specific
1096 command, or for all commands at once.
1098 Usually, the command has only one default action. The convention is to
1099 use single letters when selecting a command, and the letter @kbd{o} is
1100 designated for the default command. This way, @kbd{M-o o} should be always
1101 equivalent to @kbd{C-m}.
1103 @node Example - add two actions to each command
1104 @subsection Example - add two actions to each command
1106 The first action inserts the current candidate into the Ivy window -
1107 the window from which @code{ivy-read} was called.
1109 The second action copies the current candidate to the kill ring.
1112 (defun ivy-yank-action (x)
1115 (defun ivy-copy-to-buffer-action (x)
1121 '(("i" ivy-copy-to-buffer-action "insert")
1122 ("y" ivy-yank-action "yank")))
1125 Then in any completion session, @kbd{M-o y} invokes @code{ivy-yank-action}, and
1126 @kbd{M-o i} invokes @code{ivy-copy-to-buffer-action}.
1128 * How to undo adding the two actions::
1129 * How to add actions to a specific command::
1132 @node How to undo adding the two actions
1133 @subsubsection How to undo adding the two actions
1135 Since @code{ivy-set-actions} modifies the internal dictionary with new
1136 data, set the extra actions list to @code{nil} by assigning @code{nil} value to
1137 the @code{t} key as follows:
1140 (ivy-set-actions t nil)
1143 @node How to add actions to a specific command
1144 @subsubsection How to add actions to a specific command
1146 Use the command name as the key:
1151 '(("i" ivy-copy-to-buffer-action "insert")
1152 ("y" ivy-yank-action "yank")))
1155 @node Example - define a new command with several actions
1156 @subsection Example - define a new command with several actions
1159 (defun my-action-1 (x)
1160 (message "action-1: %s" x))
1162 (defun my-action-2 (x)
1163 (message "action-2: %s" x))
1165 (defun my-action-3 (x)
1166 (message "action-3: %s" x))
1168 (defun my-command-with-3-actions ()
1170 (ivy-read "test: " '("foo" "bar" "baz")
1172 ("o" my-action-1 "action 1")
1173 ("j" my-action-2 "action 2")
1174 ("k" my-action-3 "action 3"))))
1177 The number 1 above is the index of the default action. Each
1178 action has its own string description for easy selection.
1180 * Test the above function with @code{ivy-occur}::
1183 @node Test the above function with @code{ivy-occur}
1184 @subsubsection Test the above function with @code{ivy-occur}
1186 To examine each action with each candidate in a key-efficient way, try:
1190 Call @code{my-command-with-3-actions}
1192 Press @kbd{C-c C-o} to close the completion window and move to an
1195 Press @kbd{kkk} to move to the first candidate, since the point is most
1196 likely at the end of the buffer
1198 Press @kbd{oo} to call the first action
1200 Press @kbd{oj} and @kbd{ok} to call the second and the third actions
1202 Press @kbd{j} to move to the next candidate
1204 Press @kbd{oo}, @kbd{oj}, @kbd{ok}
1206 Press @kbd{j} to move to the next candidate
1214 @subsubheading @code{org-mode}
1216 @code{org-mode} versions 8.3.3 or later obey
1217 @code{completing-read-function} (which @code{ivy-mode} sets). Try refiling
1218 headings with similar names to appreciate @code{ivy-mode}.
1220 @subsubheading @code{magit}
1222 Magit requries this setting for ivy completion:
1225 (setq magit-completing-read-function 'ivy-completing-read)
1228 @subsubheading @code{find-file-in-project}
1230 It uses ivy by default if Ivy is installed.
1232 @subsubheading @code{projectile}
1234 Projectile requires this seeting for ivy completion:
1237 (setq projectile-completion-system 'ivy)
1240 @subsubheading @code{helm-make}
1242 Helm-make requires this seeting for ivy completion.
1245 (setq helm-make-completion-method 'ivy)
1253 * File Name Completion::
1254 * Buffer Name Completion::
1255 * Counsel commands::
1258 @node File Name Completion
1259 @section File Name Completion
1261 Since file name completion is ubiquitious, Ivy provides extra
1262 bindings that work here:
1265 @subsubheading @kbd{C-j} (@code{ivy-alt-done})
1266 @vindex ivy-alt-done
1269 On a directory, restarts completion from that directory.
1271 On a file or @code{./}, exit completion with the selected candidate.
1273 @subsubheading @kbd{DEL} (@code{ivy-backward-delete-char})
1274 @vindex ivy-backward-delete-char
1277 Restart the completion in the parent directory if current input
1280 @subsubheading @kbd{//} (@code{self-insert-command})
1283 Switch to the root directory.
1285 @subsubheading @kbd{~} (@code{self-insert-command})
1288 Switch to the home directory.
1290 @subsubheading @kbd{/} (@code{self-insert-command})
1293 If the current input matches an existing directory name exactly,
1294 switch the completion to that directory.
1296 @subsubheading @kbd{M-q} (@code{ivy-toggle-regexp-quote})
1297 @vindex ivy-toggle-regexp-quote
1300 Toggle between input as regexp or not.
1302 Switch to matching literally since file names include @code{.}, which
1303 is for matching any char in regexp mode.
1305 @defopt ivy-extra-directories
1306 Decide if you want to see @code{../} and @code{./} during file name
1309 Reason to remove: @code{../} is the same as @kbd{DEL}.
1311 Reason not to remove: navigate anywhere with only @kbd{C-n}, @kbd{C-p}
1314 Likewise, @code{./} can be removed.
1317 @subsubheading Using TRAMP
1319 From any directory, with the empty input, inputting @code{/ssh:} and
1320 pressing @kbd{C-j} (or @kbd{RET}, which is the same thing) completes for
1321 host and user names.
1323 For @code{/ssh:user@@} input, completes the domain name.
1325 @kbd{C-i} works in a similar way to the default completion.
1327 @subsubheading History
1329 File history works the same with @kbd{M-p}, @kbd{M-n}, and @kbd{C-r}, but
1330 uses a custom code for file name completion that cycles through
1331 files previously opened. It also works with TRAMP files.
1334 @node Buffer Name Completion
1335 @section Buffer Name Completion
1337 @defopt ivy-use-virtual-buffers
1338 When non-nil, add @code{recentf-mode} and bookmarks to
1339 @code{ivy-switch-buffer} completion candidates.
1341 Adding this to Emacs init file:
1344 (setq ivy-use-virtual-buffers t)
1346 will add additional virual buffers to the buffers list for recent
1347 files. Selecting such virtual buffers, which are highlighted with
1348 @code{ivy-virtual} face, will open the corresponding file.
1351 @node Counsel commands
1352 @section Counsel commands
1354 The main advantages of @code{counsel-} functions over their basic
1355 equivalents in @code{ivy-mode} are:
1359 Multi-actions and non-exiting actions work.
1361 @code{ivy-resume} can resume the last completion session.
1363 Customize @code{ivy-set-actions}, @code{ivy-re-builders-alist}.
1365 Customize individual keymaps, such as @code{counsel-describe-map},
1366 @code{counsel-git-grep-map}, or @code{counsel-find-file-map}, instead of
1367 customizing @code{ivy-minibuffer-map} that applies to all completion
1374 The main (and only) entry point is the @code{ivy-read} function. It takes
1375 two required arguments and many optional arguments that can be passed
1376 by a key. The optional @code{:action} argument is highly recommended for
1377 features such as multi-actions, non-exiting actions, @code{ivy-occur} and
1380 * Required arguments for @code{ivy-read}::
1381 * Optional arguments for @code{ivy-read}::
1382 * Example - @code{counsel-describe-function}::
1383 * Example - @code{counsel-locate}::
1386 @node Required arguments for @code{ivy-read}
1387 @section Required arguments for @code{ivy-read}
1389 @subsubheading @code{prompt}
1391 A format string normally ending in a colon and a space.
1393 @code{%d} anywhere in the string is replaced by the current number of
1394 matching candidates. To use a literal @code{%} character, escape it as
1395 @code{%%}. See also @code{ivy-count-format}.
1397 @subsubheading @code{collection}
1399 Either a list of strings, a function, an alist or a hash table.
1401 If a function, then it has to be compatible with
1402 @code{all-completions}.
1405 @node Optional arguments for @code{ivy-read}
1406 @section Optional arguments for @code{ivy-read}
1408 @subsubheading @code{predicate}
1410 Is a function to filter the initial collection. It has to be
1411 compatible with @code{all-completions}.
1413 @subsubheading @code{require-match}
1415 When set to a non-nil value, input must match one of the
1416 candidates. Custom input is not accepted.
1418 @subsubheading @code{initial-input}
1420 This string argument is included for compatibility with
1421 @code{completing-read}, which inserts it into the minibuffer.
1423 It's recommended to use the @code{preselect} argument instead of this.
1425 @subsubheading @code{history}
1427 Name of the symbol to store history. See @code{completing-read}.
1429 @subsubheading @code{preselect}
1431 When set to a string value, select the first candidate matching
1434 When set to an integer value, select the candidate with that
1437 Every time the input becomes empty, the item corresponding to to
1438 @code{preselect} is selected.
1440 @subsubheading @code{keymap}
1442 A keymap to be composed with @code{ivy-minibuffer-map}. This keymap
1443 has priority over @code{ivy-minibuffer-map} and can be modified at any
1446 @subsubheading @code{update-fn}
1448 Is the function called each time the current candidate changes.
1449 This function takes no arguments and is called in the
1450 minibuffer's @code{post-command-hook}. See @code{swiper} for an example
1453 @subsubheading @code{sort}
1455 When non-nil, use @code{ivy-sort-functions-alist} to sort the
1456 collection as long as the collection is not larger than
1457 @code{ivy-sort-max-size}.
1459 @subsubheading @code{action}
1461 Is the function to call after selection. It takes a string
1464 @subsubheading @code{unwind}
1466 Is the function to call before exiting completion. It takes no
1467 arguments. This function is called even if the completion is
1468 interrupted with @kbd{C-g}. See @code{swiper} for an example usage.
1470 @subsubheading @code{re-builder}
1472 Is a function that takes a string and returns a valid regex. See
1473 @code{Completion Styles} for details.
1475 @subsubheading @code{matcher}
1477 Is a function that takes a regex string and a list of strings and
1478 returns a list of strings matching the regex. Any ordinary Emacs
1479 matching function will suffice, yet finely tuned mathing
1480 functions can be used. See @code{counsel-find-file} for an example
1483 @subsubheading @code{dynamic-collection}
1485 When non-nil, @code{collection} will be used to dynamically generate
1486 the candidates each time the input changes, instead of being used
1487 once statically with @code{all-completions} to generate a list of
1488 strings. See @code{counsel-locate} for an example usage.
1490 @subsubheading @code{caller}
1492 Is a symbol that uniquely identifies the function that called
1493 @code{ivy-read}, which may be useful for further customizations.
1496 @node Example - @code{counsel-describe-function}
1497 @section Example - @code{counsel-describe-function}
1499 This is a typical example of a function with a non-async collection,
1500 which is a collection where all the strings in the collection are
1501 known prior to any input from the user.
1503 Only the first two arguments (along with @code{action}) are essential - the
1504 rest of the arguments are for fine-tuning, and could be omitted.
1506 The @code{action} argument could also be omitted - but then @code{ivy-read}
1507 would do nothing except returning the string result, which you could
1508 later use yourself. However, it's recommended that you use the
1509 @code{action} argument.
1512 (defun counsel-describe-function ()
1513 "Forward to `describe-function'."
1515 (ivy-read "Describe function: "
1520 (push (symbol-name x) cands))))
1522 :keymap counsel-describe-map
1523 :preselect (counsel-symbol-at-point)
1524 :history 'counsel-describe-symbol-history
1530 :caller 'counsel-describe-function))
1533 Here are the interesting features of the above function, in the order that they appear:
1537 The @code{prompt} argument is a simple string ending in ": ".
1539 The @code{collection} argument evaluates to a (large) list of strings.
1541 The @code{keymap} argument is for a custom keymap to supplement @code{ivy-minibuffer-map}.
1543 The @code{preselect} is provided by @code{counsel-symbol-at-point}, which
1544 returns a symbol near the point. Ivy then selects the first
1545 candidate from the collection that matches this symbol. To select
1546 this pre-selected candidate, a @kbd{RET} will suffice. No further user
1549 The @code{history} argument is for keeping the history of this command
1550 separate from the common history in @code{ivy-history}.
1552 The @code{require-match} is set to @code{t} since it doesn't make sense to
1553 call @code{describe-function} on an un-interned symbol.
1555 The @code{sort} argument is set to @code{t} so choosing between similar
1556 candidates becomes easier. Sometimes, the collection size will
1557 exceed @code{ivy-sort-max-size}, which is 30000 by default. In that case
1558 the sorting will not happen to avoid delays.
1560 Adjust this variable to choose between sorting time and completion
1563 The @code{action} argument calls @code{describe-function} on the interned
1566 The @code{caller} argument identifies this completion session. This is
1567 important, since with the collection being a list of strings and not
1568 a function name, the only other way for @code{ivy-read} to identify
1569 "who's calling" and to apply the appropriate customizations is to
1570 examine @code{this-command}. But @code{this-command} would be modified if
1571 another command called @code{counsel-describe-function}.
1574 @node Example - @code{counsel-locate}
1575 @section Example - @code{counsel-locate}
1577 This is a typical example of a function with an async collection.
1578 Since the collection function cannot pre-compute all the locatable
1579 files in memory within reasonable limits (time or memory), it relies
1580 on user input to filter the universe of possible candidates to a
1581 manageable size while also continuing to search asynchronously for
1582 possible candidates. Both the filtering and searching continues with
1583 each character change of the input with rapid updates to the
1584 collection presented without idle waiting times. This live update will
1585 continue as long as there are likely candidates. Eventually updates to
1586 the minibuffer will stop after user input, filtering, and searching
1587 have exhausted looking for possible candidates.
1589 Async collections suit long-running shell commands, such as @code{locate}.
1590 With each new input, a new process starts while the old process is
1591 killed. The collection is refreshed anew with each new process.
1592 Meanwhile the user can provide more input characters (for further
1593 narrowing) or select a candidate from the visible collection.
1596 (defun counsel-locate-function (str)
1597 (if (< (length str) 3)
1598 (counsel-more-chars 3)
1599 (counsel--async-command
1600 (format "locate %s '%s'"
1601 (mapconcat #'identity counsel-locate-options " ")
1602 (counsel-unquote-regex-parens
1604 '("" "working...")))
1607 (defun counsel-locate (&optional initial-input)
1608 "Call the \"locate\" shell command.
1609 INITIAL-INPUT can be given as the initial minibuffer input."
1611 (ivy-read "Locate: " #'counsel-locate-function
1612 :initial-input initial-input
1613 :dynamic-collection t
1614 :history 'counsel-locate-history
1615 :action (lambda (file)
1619 :unwind #'counsel-delete-process
1620 :caller 'counsel-locate))
1623 Here are the interesting features of the above functions, in the order
1628 @code{counsel-locate-function} takes a string argument and returns a list
1629 of strings. Note that it's not compatible with @code{all-completions},
1630 but since we're not using that here, might as well use one argument
1633 @code{counsel-more-chars} is a simple function that returns e.g.
1634 @code{'("2 chars more")} asking the user for more input.
1636 @code{counsel--async-command} is a very easy API simplification that
1637 takes a single string argument suitable for
1638 @code{shell-command-to-string}. So you could prototype your function as
1639 non-async using @code{shell-command-to-string} and @code{split-string} to
1640 produce a collection, then decide that you want async and simply swap in
1641 @code{counsel--async-command}.
1643 @code{counsel-locate} is an interactive function with an optional @code{initial-input}.
1645 @code{#'counsel-locate-function} is passed as the @code{collection} argument.
1647 @code{dynamic-collection} is set to t, since this is an async collection.
1649 @code{action} argument uses @code{with-ivy-window} wrapper, since we want to open the
1650 selected file in the same window from which @code{counsel-locate} was
1653 @code{unwind} argument is set to @code{#'counsel-delete-process}: when we press @kbd{C-g}
1654 we want to kill the running process created by
1655 @code{counsel--async-command}.
1657 @code{caller} argument identifies this command for easier customization.
1660 @node Variable Index
1661 @unnumbered Variable Index
1665 @node Keystroke Index
1666 @unnumbered Keystroke Index