1 #+TITLE: Ivy User Manual
3 #+EMAIL: ohwoeowho@gmail.com
6 #+TEXINFO_DIR_CATEGORY: Emacs
7 #+TEXINFO_DIR_TITLE: Ivy: (ivy).
8 #+TEXINFO_DIR_DESC: Using Ivy for completion.
9 #+SETUPFILE: ~/git/org-html-themes/setup/theme-readtheorg.setup
10 #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="kbd-style.css"/>
11 #+OPTIONS: H:6 num:6 toc:4
14 #+BEGIN_SRC elisp :exports results :results silent
15 (add-to-list 'load-path default-directory)
18 * Writing this manual :noexport:
19 To highlight a section without introducing a new subheading use
20 definition lists. The definition list "owns" the subsequent text if
21 the text is indented by 5 spaces. Use ~C-q~ to indent the
22 paragraphs. Start new paragraphs with 5 spaces indented. To separate
23 definition lists from regular lists, use two newlines.
25 A typical definition list:
27 - ~C-M-j~ (=ivy-immediate-done=) ::
29 The code and kbd part is recognized and added as =@vindex= and
30 =@kindex= respectively.
32 Use definition lists to declare a =@defopt= section for =defcustom=
33 or =defvar=. For proper Texinfo export, use this form:
36 User Option =ivy-wrap= ::
39 Set =CUSTOM_ID= property to name each heading. For example, =worf='s
40 ~C-u L~. This will result in consistent HTML node names.
42 Keep one empty line before each source block for proper Texinfo
50 Ivy manual, version 0.7.0
52 Ivy is an interactive interface for completion in Emacs. Emacs uses
53 completion mechanism in a variety of contexts: code, menus, commands,
54 variables, functions, etc. Completion entails listing, sorting,
55 filtering, previewing, and applying actions on selected items. When
56 active, =ivy-mode= completes the selection process by narrowing
57 available choices while previewing in the minibuffer. Selecting the
58 final candidate is either through simple keyboard character inputs or
59 through powerful regular expressions.
60 #+TEXINFO: @end ifnottex
62 Copyright (C) 2015 Free Software Foundation, Inc.
65 Permission is granted to copy, distribute and/or modify this document
66 under the terms of the GNU Free Documentation License, Version 1.3 or
67 any later version published by the Free Software Foundation; with no
68 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
69 and with the Back-Cover Texts as in (a) below. A copy of the license
70 is included in the section entitled ``GNU Free Documentation License.''
72 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
73 modify this GNU manual.''
76 #+HTML: <a href="https://github.com/abo-abo/swiper/blob/master/doc/ivy.org">This manual source</a>
79 :CUSTOM_ID: introduction
81 Ivy is for quick and easy selection from a list. When Emacs prompts
82 for a string from a list of several possible choices, Ivy springs into
83 action to assist in narrowing and picking the right string from a vast
86 Ivy strives for minimalism, simplicity, customizability and
90 Uncluttered minibuffer is minimalism. Ivy shows the completion
91 defaults, the number of matches, and 10 candidate matches below
92 the input line. Customize =ivy-height= to adjust the number of
93 candidate matches displayed in the minibuffer.
96 Simplicity is about Ivy's behavior in the minibuffer. It is also
97 about the code interface to extend Ivy's functionality. The
98 minibuffer area behaves as close to =fundamental-mode= as
99 possible. ~SPC~ inserts a space, for example, instead of being
100 bound to the more complex =minibuffer-complete-word=. Ivy's code
101 uses easy-to-examine global variables; avoids needless
102 complications with branch-introducing custom macros.
105 Customizability is about being able to use different methods and
106 interfaces of completion to tailor the selection process. For
107 example, adding a custom display function that points to a
108 selected candidate with =->=, instead of highlighting the
109 selected candidate with the =ivy-current-match= face. Or take the
110 customization of actions, say after the candidate function is
111 selected. ~RET~ uses =counsel-describe-function= to describe the
112 function, whereas ~M-o d~ jumps to that function's definition in
113 the code. The ~M-o~ prefix can be uniformly used with characters
114 like ~d~ to group similar actions.
117 Ivy displays easily discoverable commands through the hydra
118 facility. ~C-o~ in the minibuffer displays a hydra menu. It
119 opens up within an expanded minibuffer area. Each menu item comes
120 with short documentation strings and highlighted one-key
121 completions. So discovering even seldom used keys is simply a
122 matter of ~C-o~ in the minibuffer while in the midst of the Ivy
123 interaction. This discoverability minimizes exiting Ivy interface
124 for documentation look-ups.
128 :CUSTOM_ID: installation
131 Install Ivy automatically through Emacs's package manager, or manually
132 from Ivy's development repository.
134 Emacs 24.3.1 is the oldest version to run Ivy. Emacs 24.5.1 is the
135 oldest version that runs Ivy with fancy faces display.
137 ** Installing from Emacs Package Manager
139 :CUSTOM_ID: installing-from-emacs-package-manager
142 ~M-x~ =package-install= ~RET~ =swiper= ~RET~
144 Ivy is installed as part of =swiper= package. =swiper= is available
145 from two different package archives, GNU ELPA and MELPA. For the
146 latest stable version, use the GNU ELPA archives using the above M-x
149 For current hourly builds, use the MELPA archives. See the code below
150 for adding MELPA to the list of package archives:
154 (add-to-list 'package-archives
155 '("melpa" . "http://melpa.org/packages/"))
158 After this do ~M-x~ =package-refresh-contents= ~RET~, followed by
159 ~M-x~ =package-install= ~RET~ =swiper= ~RET~.
161 For package manager details, see [[info:emacs#Packages]].
163 ** Installing from the Git repository
165 :CUSTOM_ID: installing-from-the-git-repository
168 - Why install from Git? ::
170 - No need to wait for MELPA's hourly builds
171 - Easy to revert to previous versions
172 - Contribute to Ivy's development; send patches; pull requests
175 - Configuration steps ::
176 First clone the Swiper repository with:
179 cd ~/git && git clone https://github.com/abo-abo/swiper
180 cd swiper && make compile
183 Second, add these lines to the Emacs init file:
186 (add-to-list 'load-path "~/git/swiper/")
190 Then, update the code with:
199 :CUSTOM_ID: getting-started
201 First enable Ivy completion everywhere:
207 Note: =ivy-mode= can be toggled on and off with ~M-x~ =ivy-mode=.
208 ** Basic customization
210 :CUSTOM_ID: basic-customization
212 Here are some basic settings particularly useful for new Ivy users:
215 (setq ivy-use-virtual-buffers t)
217 (setq ivy-count-format "(%d/%d) ")
220 If you want, you can go without any customizations at all. The above
221 settings are the most bang for the buck in terms of customization. So
222 users that typically don't like customize a lot are advised to look at
223 these settings first.
225 For more advanced customizations, refer to =M-x describe-variable=
230 :CUSTOM_ID: key-bindings
232 ** Global key bindings
234 :CUSTOM_ID: global-key-bindings
236 The recommended key bindings are:
238 - Ivy-based interface to standard commands ::
241 (global-set-key (kbd "C-s") 'swiper)
242 (global-set-key (kbd "M-x") 'counsel-M-x)
243 (global-set-key (kbd "C-x C-f") 'counsel-find-file)
244 (global-set-key (kbd "<f1> f") 'counsel-describe-function)
245 (global-set-key (kbd "<f1> v") 'counsel-describe-variable)
246 (global-set-key (kbd "<f1> l") 'counsel-load-library)
247 (global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
248 (global-set-key (kbd "<f2> u") 'counsel-unicode-char)
251 - Ivy-based interface to shell and system tools ::
254 (global-set-key (kbd "C-c g") 'counsel-git)
255 (global-set-key (kbd "C-c j") 'counsel-git-grep)
256 (global-set-key (kbd "C-c k") 'counsel-ag)
257 (global-set-key (kbd "C-x l") 'counsel-locate)
258 (global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
261 - Ivy-resume and other commands ::
263 =ivy-resume= resumes the last Ivy-based completion.
266 (global-set-key (kbd "C-c C-r") 'ivy-resume)
269 ** Minibuffer key bindings
271 :CUSTOM_ID: minibuffer-key-bindings
274 #+VINDEX: ivy-minibuffer-map
275 Ivy includes several minibuffer bindings, which are defined in the
276 =ivy-minibuffer-map= keymap variable. The most frequently used ones
279 =swiper= or =counsel-M-x= add more key bindings through the =keymap=
280 argument to =ivy-read=. These keys, also active in the minibuffer, are
281 described under their respective commands.
283 A key feature of =ivy-minibuffer-map= is its full editing capability
284 where the familiar ~C-a~, ~C-f~, ~M-d~, ~M-DEL~, ~M-b~, ~M-w~, ~C-k~,
285 ~C-y~ key bindings work the same as in =fundamental-mode=.
287 *** Key bindings for navigation
289 :CUSTOM_ID: key-bindings-for-navigation
292 - ~C-n~ (=ivy-next-line=) selects the next candidate
293 - ~C-p~ (=ivy-previous-line=) selects the previous candidate
294 - ~M-<~ (=ivy-beginning-of-buffer=) selects the first candidate
295 - ~M->~ (=ivy-end-of-buffer=) selects the last candidate
296 - ~C-v~ (=ivy-scroll-up-command=) scrolls up by =ivy-height= lines
297 - ~M-v~ (=ivy-scroll-down-command=) scrolls down by =ivy-height= lines
300 - User Option =ivy-wrap= ::
301 Specifies the wrap-around behavior for ~C-n~ and ~C-p~. When
302 =ivy-wrap= is set to =t=, =ivy-next-line= and =ivy-previous-line=
303 will cycle past the last and the first candidates respectively.
305 Warp-around behavior is off by default.
307 - User Option =ivy-height= ::
308 Use this option to adjust the minibuffer height, which also
309 affects scroll size when using ~C-v~ and ~M-v~ key bindings.
311 =ivy-height= is 10 lines by default.
313 *** Key bindings for single selection, action, then exit minibuffer
315 :CUSTOM_ID: key-bindings-for-single-selection-action-then-exit-minibuffer
318 Ivy can offer several actions from which to choose which action to
319 run. This "calling an action" operates on the selected candidate. For
320 example, when viewing a list of files, one action could open it for
321 editing, one to view it, another to invoke a special function, and so
322 on. Custom actions can be added to this interface. The precise action
323 to call on the selected candidate can be delayed until after the
324 narrowing is completed. No need to exit the interface if unsure which
325 action to run. This delayed flexibility and customization of actions
326 extends usability of lists in Emacs.
328 - ~C-m~ or ~RET~ (=ivy-done=) ::
329 Calls the default action and then exits the minibuffer.
331 - ~M-o~ (=ivy-dispatching-done=) ::
332 Presents valid actions from which to choose. When only one action
333 is available, there is no difference between ~M-o~ and ~C-m~.
335 - ~C-j~ (=ivy-alt-done=) ::
336 When completing file names, selects the current directory
337 candidate and starts a new completion session there. Otherwise,
338 it is the same as =ivy-done=.
340 - ~TAB~ (=ivy-partial-or-done=) ::
341 Attempts partial completion, extending current input as much as
342 possible. ~TAB TAB~ is the same as ~C-j~ (=ivy-alt-done=).
350 (ivy-read "Test: " '("can do" "can't, sorry" "other"))
356 - ~C-M-j~ (=ivy-immediate-done=) ::
357 Exits with /the current input/ instead of /the current candidate/
358 (like other commands).
360 This is useful e.g. when you call =find-file= to create a new
361 file, but the desired name matches an existing file. In that
362 case, using ~C-j~ would select that existing file, which isn't
363 what you want - use this command instead.
365 - ~C-'~ (=ivy-avy=) ::
366 Uses avy to select one of the candidates on the current candidate
367 page. This can often be faster than multiple ~C-n~ or ~C-p~
368 keystrokes followed by ~C-m~.
370 *** Key bindings for multiple selections and actions, keep minibuffer open
372 :CUSTOM_ID: key-bindings-for-multiple-selections-and-actions-keep-minibuffer-open
375 For repeatedly applying multiple actions or acting on multiple
376 candidates, Ivy does not close the minibuffer between commands. It
377 keeps the minibuffer open for applying subsequent actions.
379 Adding an extra meta key to the normal key chord invokes the special
380 version of the regular commands that enables applying multiple
383 - ~C-M-m~ (=ivy-call=) ::
384 Is the non-exiting version of ~C-m~ (=ivy-done=).
386 Instead of closing the minibuffer, ~C-M-m~ allows selecting
387 another candidate or another action. For example, ~C-M-m~ on
388 functions list invokes =describe-function=. When combined with
389 ~C-n~, function descriptions can be invoked quickly in
392 - ~C-M-o~ (=ivy-dispatching-call=) ::
393 Is the non-exiting version of ~M-o~ (=ivy-dispatching-done=).
395 For example, during the =counsel-rhythmbox= completion, press
396 ~C-M-o e~ to en-queue the selected candidate, followed by ~C-n
397 C-m~ to play the next candidate - the current action reverts to
398 the default one after ~C-M-o~.
400 - ~C-M-n~ (=ivy-next-line-and-call=) ::
401 Combines ~C-n~ and ~C-M-m~. Applies an action and moves to next
404 Comes in handy when opening multiple files from
405 =counsel-find-file=, =counsel-git-grep=, =counsel-ag=, or
406 =counsel-locate= lists. Just hold ~C-M-n~ for rapid-fire default
407 action on each successive element of the list.
409 - ~C-M-p~ (=ivy-previous-line-and-call=) ::
410 Combines ~C-p~ and ~C-M-m~.
412 Similar to the above except it moves through the list in the
416 Recalls the state of the completion session just before its last
419 Useful after an accidental ~C-m~ (=ivy-done=).
421 *** Key bindings that alter the minibuffer input
423 :CUSTOM_ID: key-bindings-that-alter-the-minibuffer-input
426 - ~M-n~ (=ivy-next-history-element=) ::
427 Cycles forward through the Ivy command history.
429 Ivy updates an internal history list after each action. When this
430 history list is empty, ~M-n~ inserts symbol (or URL) at point
433 - ~M-p~ (=ivy-previous-history-element=) ::
434 Cycles forward through the Ivy command history.
436 - ~M-i~ (=ivy-insert-current=) ::
437 Inserts the current candidate into the minibuffer.
439 Useful for copying and renaming files, for example: ~M-i~ to
440 insert the original file name string, edit it, and then ~C-m~ to
441 complete the renaming.
443 - ~M-j~ (=ivy-yank-word=) ::
444 Inserts the sub-word at point into the minibuffer.
446 This is similar to ~C-s C-w~ with =isearch=. Ivy reserves ~C-w~
449 - ~S-SPC~ (=ivy-restrict-to-matches=) ::
450 Deletes the current input, and resets the candidates list to the
451 currently restricted matches.
453 This is how Ivy provides narrowing in successive tiers.
455 - ~C-r~ (=ivy-reverse-i-search=) ::
456 Starts a recursive completion session through the command's
459 This works just like ~C-r~ at the bash command prompt, where the
460 completion candidates are the history items. Upon completion, the
461 selected candidate string is inserted into the minibuffer.
463 *** Other key bindings
465 :CUSTOM_ID: other-key-bindings
468 - ~M-w~ (=ivy-kill-ring-save=) ::
469 Copies selected candidates to the kill ring.
471 Copies the region if the region is active.
473 *** Hydra in the minibuffer
475 :CUSTOM_ID: hydra-in-the-minibuffer
478 - ~C-o~ (=hydra-ivy/body=) ::
479 Invokes the hydra menu with short key bindings.
481 When Hydra is active, minibuffer editing is disabled and menus
482 display short aliases:
484 | Short | Normal | Command name |
485 |-------+-----------+---------------------------|
486 | ~o~ | ~C-g~ | =keyboard-escape-quit= |
487 | ~j~ | ~C-n~ | =ivy-next-line= |
488 | ~k~ | ~C-p~ | =ivy-previous-line= |
489 | ~h~ | ~M-<~ | =ivy-beginning-of-buffer= |
490 | ~l~ | ~M->~ | =ivy-end-of-buffer= |
491 | ~d~ | ~C-m~ | =ivy-done= |
492 | ~f~ | ~C-j~ | =ivy-alt-done= |
493 | ~g~ | ~C-M-m~ | =ivy-call= |
494 | ~u~ | ~C-c C-o~ | =ivy-occur= |
496 Hydra reduces key strokes, for example: ~C-n C-n C-n C-n~ is ~C-o
499 Hydra menu offers these additioanl bindings:
501 - ~c~ (=ivy-toggle-calling=) ::
502 Toggle calling the action after each candidate change. It
503 modifies ~j~ to ~jg~, ~k~ to ~kg~ etc.
505 - ~m~ (=ivy-toggle-fuzzy=) ::
506 Toggle the current regexp matcher.
508 - ~>~ (=ivy-minibuffer-grow=) ::
509 Increase =ivy-height= for the current minibuffer.
511 - ~<~ (=ivy-minibuffer-shrink=) ::
512 Decrease =ivy-height= for the current minibuffer.
514 - ~w~ (=ivy-prev-action=) ::
515 Select the previous action.
517 - ~s~ (=ivy-next-action=) ::
518 Select the next action.
520 - ~a~ (=ivy-read-action=) ::
521 Use a menu to select an action.
523 - ~C~ (=ivy-toggle-case-fold=) ::
524 Toggle case folding (match both upper and lower case
525 characters for lower case input).
527 *** Saving the current completion session to a buffer
529 :CUSTOM_ID: saving-the-current-completion-session-to-a-buffer
532 - ~C-c C-o~ (=ivy-occur=) ::
533 Saves the current candidates to a new buffer and exits
536 The new buffer is read-only and has a few useful bindings defined.
538 - ~RET~ or ~j~ (=ivy-occur-press=) ::
539 Call the current action on the selected candidate.
541 - ~mouse-1~ (=ivy-occur-click=) ::
542 Call the current action on the selected candidate.
544 - ~j~ (=next-line=) ::
547 - ~k~ (=previous-line=) ::
548 Move to previous line.
550 - ~a~ (=ivy-occur-read-action=) ::
551 Read an action and make it current for this buffer.
553 - ~o~ (=ivy-occur-dispatch=) ::
554 Read an action and call it on the selected candidate.
556 - ~q~ (=quit-window=) ::
557 Bury the current buffer.
560 Ivy has no limit on the number of active buffers like these.
562 Ivy takes care of naming buffers uniquely by constructing descriptive
563 names. For example: =*ivy-occur counsel-describe-variable
568 :CUSTOM_ID: completion-styles
571 Ivy's completion functions rely on a regex builder - a function that
572 transforms a string input to a string regex. All current candidates
573 simply have to match this regex. Each collection can be assigned its
574 own regex builder by customizing =ivy-re-builders-alist=.
576 The keys of this alist are collection names, and the values are one of
580 - =ivy--regex-ignore-order=
584 A catch-all key, =t=, applies to all collections that don't have their
590 (setq ivy-re-builders-alist
591 '((t . ivy--regex-plus)))
594 This example shows a custom regex builder assigned to file name
598 (setq ivy-re-builders-alist
599 '((read-file-name-internal . ivy--regex-fuzzy)
600 (t . ivy--regex-plus)))
603 Here, =read-file-name-internal= is a function that is passed as the
604 second argument to =completing-read= for file name completion.
606 The regex builder resolves as follows (in order of priority):
607 1. =re-builder= argument passed to =ivy-read=.
608 2. =collection= argument passed to =ivy-read= is a function and has an
609 entry on =ivy-re-builders-alist=.
610 3. =caller= argument passed to =ivy-read= has an entry on
611 =ivy-re-builders-alist=.
612 4. =this-command= has an entry on =ivy-re-builders-alist=.
613 5. =t= has an entry on =ivy-re-builders-alist=.
618 :CUSTOM_ID: ivy--regex-plus
621 =ivy--regex-plus= is Ivy's default completion method.
623 =ivy--regex-plus= matches by splitting the input by spaces and
624 rebuilding it into a regex.
626 As the search string is typed in Ivy's minibuffer, it is transformed
627 into valid regex syntax. If the string is ="for example"=, it is
631 "\\(for\\).*\\(example\\)"
634 which in regex terminology matches ="for"= followed by a wild card and
635 then ="example"=. Note how Ivy uses the space character to build wild
636 cards. To match a literal white space, use an extra space. So to match
637 one space type two spaces, to match two spaces type three spaces, and
640 As Ivy transforms typed characters into regex strings, it provides an
641 intuitive feedback through font highlights.
643 Ivy supports regexp negation with ="!"=.
644 For example, ="define key ! ivy quit"= first selects everything
645 matching ="define.*key"=, then removes everything matching ="ivy"=,
646 and finally removes everything matching ="quit"=. What remains is the
647 final result set of the negation regexp.
649 Since Ivy treats minibuffer input as a regexp, the standard regexp
650 identifiers work: ="^"=, ="$"=, ="\b"= or ="[a-z]"=. The exceptions
651 are spaces, which translate to =".*"=, and ="!"= that signal the
652 beginning of a negation group.
654 ** ivy--regex-ignore-order
656 :CUSTOM_ID: ivy--regex-ignore-order
659 =ivy--regex-ignore-order= ignores the order of regexp tokens when
660 searching for matching candidates. For instance, the input
661 ="for example"= will match ="example test for"=.
665 :CUSTOM_ID: ivy--regex-fuzzy
668 =ivy--regex-fuzzy= splits each character with a wild card. Searching
669 for ="for"= returns all ="f.*o.*r"= matches, resulting in a large
670 number of hits. Yet some searches need these extra hits. Ivy sorts
671 such large lists using =flx= package's scoring mechanism, if it's
674 ~C-o m~ toggles the current regexp builder.
679 :CUSTOM_ID: customization
685 - =ivy-current-match= ::
686 Highlights the currently selected candidate.
687 - =ivy-minibuffer-match-face-1= ::
688 Highlights the background of the match.
689 - =ivy-minibuffer-match-face-2= ::
690 Highlights the first (modulo 3) matched group.
691 - =ivy-minibuffer-match-face-3= ::
692 Highlights the second (modulo 3) matched group.
693 - =ivy-minibuffer-match-face-4= ::
694 Highlights the third (modulo 3) matched group.
695 - =ivy-confirm-face= ::
696 Highlights the "(confirm)" part of the prompt.
698 When =confirm-nonexistent-file-or-buffer= set to =t=, then
699 confirming non-existent files in =ivy-mode= requires an
702 The confirmation prompt will use this face.
707 (setq confirm-nonexistent-file-or-buffer t)
710 Then call =find-file=, enter "eldorado" and press ~RET~ - the
711 prompt will be appended with "(confirm)". Press ~RET~ once more
712 to confirm, or any key to continue the completion.
713 - =ivy-match-required-face= ::
714 Highlights the "(match required)" part of the prompt.
716 When completions have to match available candidates and cannot
717 take random input, the "(match required)" prompt signals this
720 For example, call =describe-variable=, enter "waldo" and press
721 ~RET~ - "(match required)" is prompted.
722 Press any key for the prompt to disappear.
724 Highlights directories when completing file names.
726 Highlights remote files when completing file names.
728 Highlights virtual buffers when completing buffer names.
730 Virtual buffers correspond to bookmarks and recent files list,
733 Enable virtual buffers with:
736 (setq ivy-use-virtual-buffers t)
740 :CUSTOM_ID: defcustoms
742 - User Option =ivy-count-format= ::
743 A string that specifies display of number of candidates and
744 current candidate, if one exists.
746 The number of matching candidates by default is shown as a right-
747 padded integer value.
749 To disable showing the number of candidates:
752 (setq ivy-count-format "")
755 To also display the current candidate:
758 (setq ivy-count-format "(%d/%d) ")
761 The =format=-style switches this variable uses are described
762 in the =format= documentation.
764 - User Option =ivy-display-style= ::
765 Specifies highlighting candidates in the minibuffer.
767 The default setting is ='fancy= and valid only in Emacs versions
770 Set =ivy-display-style= to =nil= for a plain minibuffer.
772 - User Option =ivy-on-del-error-function= ::
773 Specify what when ~DEL~ (=ivy-backward-delete-char=) throws.
775 The default behavior is to quit the completion after ~DEL~ -- a
776 handy key to invoke after mistakenly triggering a completion.
782 *** What are actions?
784 :CUSTOM_ID: what-are-actions
786 An action is a function that is called after you select a candidate
787 during completion. This function takes a single string argument, which
788 is the selected candidate.
790 - Window context when calling an action ::
791 Currently, the action is executed in the minibuffer window
792 context. This means e.g. that if you call =insert= the text will
793 be inserted into the minibuffer.
795 If you want to execute the action in the initial window from
796 which the completion started, use the =with-ivy-window= wrapper
800 (defun ivy-insert-action (x)
805 *** How can different actions be called?
807 :CUSTOM_ID: how-can-different-actions-be-called
809 - ~C-m~ (=ivy-done=) calls the current action.
810 - ~M-o~ (=ivy-dispatching-done=) presents available actions for
811 selection, calls it after selection, and then exits.
812 - ~C-M-o~ (=ivy-dispatching-call=) presents available actions for
813 selection, calls it after selection, and then does not exit.
815 *** How to modify the actions list?
817 :CUSTOM_ID: how-to-modify-the-actions-list
819 Currently, you can append any amount of your own actions to the
820 default list of actions. This can be done either for a specific
821 command, or for all commands at once.
823 Usually, the command has only one default action. The convention is to
824 use single letters when selecting a command, and the letter ~o~ is
825 designated for the default command. This way, ~M-o o~ should be always
828 *** Example - add two actions to each command
830 :CUSTOM_ID: example---add-two-actions-to-each-command
832 The first action inserts the current candidate into the Ivy window -
833 the window from which =ivy-read= was called.
835 The second action copies the current candidate to the kill ring.
838 (defun ivy-yank-action (x)
841 (defun ivy-copy-to-buffer-action (x)
847 '(("i" ivy-copy-to-buffer-action "insert")
848 ("y" ivy-yank-action "yank")))
851 Then in any completion session, ~M-o y~ invokes =ivy-yank-action=, and
852 ~M-o i~ invokes =ivy-copy-to-buffer-action=.
854 **** How to undo adding the two actions
856 :CUSTOM_ID: how-to-undo-adding-the-two-actions
858 Since =ivy-set-actions= modifies the internal dictionary with new
859 data, set the extra actions list to =nil= by assigning =nil= value to
860 the =t= key as follows:
863 (ivy-set-actions t nil)
866 **** How to add actions to a specific command
868 :CUSTOM_ID: how-to-add-actions-to-a-specific-command
870 Use the command name as the key:
875 '(("i" ivy-copy-to-buffer-action "insert")
876 ("y" ivy-yank-action "yank")))
879 *** Example - define a new command with several actions
881 :CUSTOM_ID: example---define-a-new-command-with-several-actions
884 (defun my-action-1 (x)
885 (message "action-1: %s" x))
887 (defun my-action-2 (x)
888 (message "action-2: %s" x))
890 (defun my-action-3 (x)
891 (message "action-3: %s" x))
893 (defun my-command-with-3-actions ()
895 (ivy-read "test: " '("foo" "bar" "baz")
897 ("o" my-action-1 "action 1")
898 ("j" my-action-2 "action 2")
899 ("k" my-action-3 "action 3"))))
902 The number 1 above is the index of the default action. Each
903 action has its own string description for easy selection.
905 **** Test the above function with =ivy-occur=
907 :CUSTOM_ID: test-the-above-function-with-ivy-occur
909 To examine each action with each candidate in a key-efficient way, try:
911 - Call =my-command-with-3-actions=
912 - Press ~C-c C-o~ to close the completion window and move to an
914 - Press ~kkk~ to move to the first candidate, since the point is most
915 likely at the end of the buffer
916 - Press ~oo~ to call the first action
917 - Press ~oj~ and ~ok~ to call the second and the third actions
918 - Press ~j~ to move to the next candidate
919 - Press ~oo~, ~oj~, ~ok~
920 - Press ~j~ to move to the next candidate
928 =org-mode= versions 8.3.3 or later obey
929 =completing-read-function= (which =ivy-mode= sets). Try refiling
930 headings with similar names to appreciate =ivy-mode=.
932 Magit requries this setting for ivy completion:
935 (setq magit-completing-read-function 'ivy-completing-read)
937 - =find-file-in-project= ::
938 It uses ivy by default if Ivy is installed.
940 Projectile requires this seeting for ivy completion:
943 (setq projectile-completion-system 'ivy)
946 Helm-make requires this seeting for ivy completion.
949 (setq helm-make-completion-method 'ivy)
956 ** File Name Completion
958 :CUSTOM_ID: file-name-completion
960 Since file name completion is ubiquitious, Ivy provides extra
961 bindings that work here:
964 - ~C-j~ (=ivy-alt-done=) ::
965 On a directory, restarts completion from that directory.
967 On a file or =./=, exit completion with the selected candidate.
968 - ~DEL~ (=ivy-backward-delete-char=) ::
969 Restart the completion in the parent directory if current input
971 - ~//~ (=self-insert-command=) ::
972 Switch to the root directory.
973 - ~~~ (=self-insert-command=) ::
974 Switch to the home directory.
975 - ~/~ (=self-insert-command=) ::
976 If the current input matches an existing directory name exactly,
977 switch the completion to that directory.
978 - ~M-q~ (=ivy-toggle-regexp-quote=) ::
979 Toggle between input as regexp or not.
981 Switch to matching literally since file names include =.=, which
982 is for matching any char in regexp mode.
984 - User Option =ivy-extra-directories= ::
985 Decide if you want to see =../= and =./= during file name
988 Reason to remove: =../= is the same as ~DEL~.
990 Reason not to remove: navigate anywhere with only ~C-n~, ~C-p~
993 Likewise, =./= can be removed.
996 From any directory, with the empty input, inputting =/ssh:= and
997 pressing ~C-j~ (or ~RET~, which is the same thing) completes for
1000 For =/ssh:user@= input, completes the domain name.
1002 ~C-i~ works in a similar way to the default completion.
1005 File history works the same with ~M-p~, ~M-n~, and ~C-r~, but
1006 uses a custom code for file name completion that cycles through
1007 files previously opened. It also works with TRAMP files.
1009 ** Buffer Name Completion
1011 :CUSTOM_ID: buffer-name-completion
1013 - User Option =ivy-use-virtual-buffers= ::
1014 When non-nil, add =recentf-mode= and bookmarks to
1015 =ivy-switch-buffer= completion candidates.
1017 Adding this to Emacs init file:
1020 (setq ivy-use-virtual-buffers t)
1022 will add additional virual buffers to the buffers list for recent
1023 files. Selecting such virtual buffers, which are highlighted with
1024 =ivy-virtual= face, will open the corresponding file.
1028 :CUSTOM_ID: counsel-commands
1030 The main advantages of =counsel-= functions over their basic
1031 equivalents in =ivy-mode= are:
1033 1. Multi-actions and non-exiting actions work.
1034 2. =ivy-resume= can resume the last completion session.
1035 3. Customize =ivy-set-actions=, =ivy-re-builders-alist=.
1036 4. Customize individual keymaps, such as =counsel-describe-map=,
1037 =counsel-git-grep-map=, or =counsel-find-file-map=, instead of
1038 customizing =ivy-minibuffer-map= that applies to all completion
1044 The main (and only) entry point is the =ivy-read= function. It takes
1045 two required arguments and many optional arguments that can be passed
1046 by a key. The optional =:action= argument is highly recommended for
1047 features such as multi-actions, non-exiting actions, =ivy-occur= and
1050 ** Required arguments for =ivy-read=
1052 :CUSTOM_ID: required-arguments-for-ivy-read
1055 A format string normally ending in a colon and a space.
1057 =%d= anywhere in the string is replaced by the current number of
1058 matching candidates. To use a literal =%= character, escape it as
1059 =%%=. See also =ivy-count-format=.
1062 Either a list of strings, a function, an alist or a hash table.
1064 If a function, then it has to be compatible with
1067 ** Optional arguments for =ivy-read=
1069 :CUSTOM_ID: optional-arguments-for-ivy-read
1072 Is a function to filter the initial collection. It has to be
1073 compatible with =all-completions=. Tip: most of the time, it's
1074 simpler to just apply this filter to the =collection= argument
1075 itself, e.g. =(cl-remove-if-not predicate collection)=.
1076 - =require-match= ::
1077 When set to a non-nil value, input must match one of the
1078 candidates. Custom input is not accepted.
1079 - =initial-input= ::
1080 This string argument is included for compatibility with
1081 =completing-read=, which inserts it into the minibuffer.
1083 It's recommended to use the =preselect= argument instead of this.
1085 Name of the symbol to store history. See =completing-read=.
1087 When set to a string value, select the first candidate matching
1090 When set to an integer value, select the candidate with that
1093 Every time the input becomes empty, the item corresponding to to
1094 =preselect= is selected.
1096 A keymap to be composed with =ivy-minibuffer-map=. This keymap
1097 has priority over =ivy-minibuffer-map= and can be modified at any
1100 Is the function called each time the current candidate changes.
1101 This function takes no arguments and is called in the
1102 minibuffer's =post-command-hook=. See =swiper= for an example
1105 When non-nil, use =ivy-sort-functions-alist= to sort the
1106 collection as long as the collection is not larger than
1107 =ivy-sort-max-size=.
1109 Is the function to call after selection. It takes a string
1112 Is the function to call before exiting completion. It takes no
1113 arguments. This function is called even if the completion is
1114 interrupted with ~C-g~. See =swiper= for an example usage.
1116 Is a function that takes a string and returns a valid regex. See
1117 =Completion Styles= for details.
1119 Is a function that takes a regex string and a list of strings and
1120 returns a list of strings matching the regex. Any ordinary Emacs
1121 matching function will suffice, yet finely tuned mathing
1122 functions can be used. See =counsel-find-file= for an example
1124 - =dynamic-collection= ::
1125 When non-nil, =collection= will be used to dynamically generate
1126 the candidates each time the input changes, instead of being used
1127 once statically with =all-completions= to generate a list of
1128 strings. See =counsel-locate= for an example usage.
1130 Is a symbol that uniquely identifies the function that called
1131 =ivy-read=, which may be useful for further customizations.
1132 ** Example - =counsel-describe-function=
1134 :CUSTOM_ID: example---counsel-describe-function
1136 This is a typical example of a function with a non-async collection,
1137 which is a collection where all the strings in the collection are
1138 known prior to any input from the user.
1140 Only the first two arguments (along with =action=) are essential - the
1141 rest of the arguments are for fine-tuning, and could be omitted.
1143 The =action= argument could also be omitted - but then =ivy-read=
1144 would do nothing except returning the string result, which you could
1145 later use yourself. However, it's recommended that you use the
1149 (defun counsel-describe-function ()
1150 "Forward to `describe-function'."
1152 (ivy-read "Describe function: "
1157 (push (symbol-name x) cands))))
1159 :keymap counsel-describe-map
1160 :preselect (counsel-symbol-at-point)
1161 :history 'counsel-describe-symbol-history
1167 :caller 'counsel-describe-function))
1170 Here are the interesting features of the above function, in the order that they appear:
1172 - The =prompt= argument is a simple string ending in ": ".
1173 - The =collection= argument evaluates to a (large) list of strings.
1174 - The =keymap= argument is for a custom keymap to supplement =ivy-minibuffer-map=.
1175 - The =preselect= is provided by =counsel-symbol-at-point=, which
1176 returns a symbol near the point. Ivy then selects the first
1177 candidate from the collection that matches this symbol. To select
1178 this pre-selected candidate, a ~RET~ will suffice. No further user
1180 - The =history= argument is for keeping the history of this command
1181 separate from the common history in =ivy-history=.
1182 - The =require-match= is set to =t= since it doesn't make sense to
1183 call =describe-function= on an un-interned symbol.
1184 - The =sort= argument is set to =t= so choosing between similar
1185 candidates becomes easier. Sometimes, the collection size will
1186 exceed =ivy-sort-max-size=, which is 30000 by default. In that case
1187 the sorting will not happen to avoid delays.
1189 Adjust this variable to choose between sorting time and completion
1191 - The =action= argument calls =describe-function= on the interned
1193 - The =caller= argument identifies this completion session. This is
1194 important, since with the collection being a list of strings and not
1195 a function name, the only other way for =ivy-read= to identify
1196 "who's calling" and to apply the appropriate customizations is to
1197 examine =this-command=. But =this-command= would be modified if
1198 another command called =counsel-describe-function=.
1199 ** Example - =counsel-locate=
1201 :CUSTOM_ID: example---counsel-locate
1203 This is a typical example of a function with an async collection.
1204 Since the collection function cannot pre-compute all the locatable
1205 files in memory within reasonable limits (time or memory), it relies
1206 on user input to filter the universe of possible candidates to a
1207 manageable size while also continuing to search asynchronously for
1208 possible candidates. Both the filtering and searching continues with
1209 each character change of the input with rapid updates to the
1210 collection presented without idle waiting times. This live update will
1211 continue as long as there are likely candidates. Eventually updates to
1212 the minibuffer will stop after user input, filtering, and searching
1213 have exhausted looking for possible candidates.
1215 Async collections suit long-running shell commands, such as =locate=.
1216 With each new input, a new process starts while the old process is
1217 killed. The collection is refreshed anew with each new process.
1218 Meanwhile the user can provide more input characters (for further
1219 narrowing) or select a candidate from the visible collection.
1222 (defun counsel-locate-function (str)
1223 (if (< (length str) 3)
1224 (counsel-more-chars 3)
1225 (counsel--async-command
1226 (format "locate %s '%s'"
1227 (mapconcat #'identity counsel-locate-options " ")
1228 (counsel-unquote-regex-parens
1230 '("" "working...")))
1233 (defun counsel-locate (&optional initial-input)
1234 "Call the \"locate\" shell command.
1235 INITIAL-INPUT can be given as the initial minibuffer input."
1237 (ivy-read "Locate: " #'counsel-locate-function
1238 :initial-input initial-input
1239 :dynamic-collection t
1240 :history 'counsel-locate-history
1241 :action (lambda (file)
1245 :unwind #'counsel-delete-process
1246 :caller 'counsel-locate))
1249 Here are the interesting features of the above functions, in the order
1252 - =counsel-locate-function= takes a string argument and returns a list
1253 of strings. Note that it's not compatible with =all-completions=,
1254 but since we're not using that here, might as well use one argument
1256 - =counsel-more-chars= is a simple function that returns e.g.
1257 ='("2 chars more")= asking the user for more input.
1258 - =counsel--async-command= is a very easy API simplification that
1259 takes a single string argument suitable for
1260 =shell-command-to-string=. So you could prototype your function as
1261 non-async using =shell-command-to-string= and =split-string= to
1262 produce a collection, then decide that you want async and simply swap in
1263 =counsel--async-command=.
1264 - =counsel-locate= is an interactive function with an optional =initial-input=.
1265 - =#'counsel-locate-function= is passed as the =collection= argument.
1266 - =dynamic-collection= is set to t, since this is an async collection.
1267 - =action= argument uses =with-ivy-window= wrapper, since we want to open the
1268 selected file in the same window from which =counsel-locate= was
1270 - =unwind= argument is set to =#'counsel-delete-process=: when we press ~C-g~
1271 we want to kill the running process created by
1272 =counsel--async-command=.
1273 - =caller= argument identifies this command for easier customization.
1278 :CUSTOM_ID: variable-index
1283 :CUSTOM_ID: key-index