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 #+EXPORT_FILE_NAME: index.html
13 #+OPTIONS: H:6 num:6 toc:4
16 #+BEGIN_SRC elisp :exports results :results silent
17 (add-to-list 'load-path default-directory)
20 * Writing this manual :noexport:
21 For highlighting a section without introducing a new subheading use
22 definition lists. The definition list "owns" the following text if the
23 text is indented by 5 spaces. Use ~C-q~ to indent these
24 paragraphs. New paragraphs can also be started, as long as they have
26 Definition lists need to be separated from regular lists with two newlines.
28 For declaring a =@defopt= section for =defcustom= or =defvar=, also
29 use definition lists. They need to have the following form in order to
30 be recognized in the texinfo export:
33 User Option =ivy-wrap= ::
36 To name each heading, set its =CUSTOM_ID= property. This can be done
37 easily with =worf='s ~C-u L~.
39 Texinfo export likes to have one empty line before each source block.
46 Ivy manual, version 0.7.0
48 Ivy is an interactive interface for completion in Emacs. Emacs uses
49 completion mechanism in a variety of contexts: code, menus, commands,
50 variables, functions, etc. Completion entails listing, sorting,
51 filtering, previewing, and applying actions on selected items. When
52 active, =ivy-mode= completes the selection process by narrowing
53 available choices while previewing in the minibuffer. Selecting the
54 final candidate is either through simple keyboard character inputs or
55 through powerful regular expressions.
56 #+TEXINFO: @end ifnottex
58 Copyright (C) 2015 Free Software Foundation, Inc.
61 Permission is granted to copy, distribute and/or modify this document
62 under the terms of the GNU Free Documentation License, Version 1.3 or
63 any later version published by the Free Software Foundation; with no
64 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
65 and with the Back-Cover Texts as in (a) below. A copy of the license
66 is included in the section entitled ``GNU Free Documentation License.''
68 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
69 modify this GNU manual.''
72 #+HTML: <a href="https://github.com/abo-abo/swiper/blob/master/doc/ivy.org">This manual source</a>
75 :CUSTOM_ID: introduction
77 Ivy is for quick and easy selection from a list. When Emacs prompts
78 for a string from a list of several possible choices, Ivy springs into
79 action to assist in narrowing and picking the right string from a vast
82 Ivy strives for minimalism, simplicity, customizability and
86 Uncluttered minibuffer is minimalism. Ivy shows the completion
87 defaults, the number of matches, and 10 candidate matches below
88 the input line. Customize =ivy-length= to adjust the number of
89 candidate matches displayed in the minibuffer.
92 Simplicity is about Ivy's behavior in the minibuffer. It is also
93 about the code interface to extend Ivy's functionality. The
94 minibuffer area behaves as close to =fundamental-mode= as
95 possible. ~SPC~ inserts a space, for example, instead of being
96 bound to the more complex =minibuffer-complete-word=. Ivy's code
97 uses easy-to-examine global variables; avoids needless
98 complications with branch-introducing custom macros.
101 Customizability is about being able to use different methods and
102 interfaces of completion to tailor the selection process. For
103 example, adding a custom display function that points to a
104 selected candidate with =->=, instead of highlighting the
105 selected candidate with the =ivy-current-match= face. Or take the
106 customization of actions, say after the candidate function is
107 selected. ~RET~ uses =counsel-describe-function= to describe the
108 function, whereas ~M-o d~ jumps to that function's definition in
109 the code. The ~M-o~ prefix can be uniformly used with characters
110 like ~d~ to group similar actions.
113 Ivy displays easily discoverable commands through the hydra
114 facility. ~C-o~ in the minibuffer displays a hydra menu. It
115 opens up within an expanded minibuffer area. Each menu item comes
116 with short documentation strings and highlighted one-key
117 completions. So discovering even seldom used keys is simply a
118 matter of ~C-o~ in the minibuffer while in the midst of the Ivy
119 interaction. This discoverability minimizes exiting Ivy interface
120 for documentation look-ups.
124 :CUSTOM_ID: installation
127 Install Ivy automatically through Emacs's package manager, or manually
128 from Ivy's development repository.
130 Ivy should run fine on a typical Emacs bundled in your OS's package
131 manager, the oldest of which is Emacs 24.3.1. However, the faces
132 display will work much better for Emacs 24.5.1, which is the latest
135 ** Installing from Emacs Package Manager
137 :CUSTOM_ID: installing-from-emacs-package-manager
140 ~M-x~ =package-install= ~RET~ =swiper= ~RET~
142 Ivy is installed as part of =swiper= package. =swiper= is available
143 from two different package archives, GNU ELPA and MELPA. For the
144 latest stable version, use the GNU ELPA archives using the above M-x
147 For current hourly builds, use the MELPA archives. See the code below
148 for adding MELPA to the list of package archives:
152 (add-to-list 'package-archives
153 '("melpa" . "http://melpa.org/packages/"))
156 After this do ~M-x~ =package-refresh-contents= ~RET~, followed by
157 ~M-x~ =package-install= ~RET~ =swiper= ~RET~.
159 For package manager details, see [[info:emacs#Packages]].
161 ** Installing from the Git repository
163 :CUSTOM_ID: installing-from-the-git-repository
166 - Why install from Git? ::
168 - No need to wait for MELPA's hourly builds
169 - Easy to revert to previous versions
170 - Contribute to Ivy's development; send patches; pull requests
173 - Configuration steps ::
174 First clone the Swiper repository:
177 cd ~/git && git clone https://github.com/abo-abo/swiper
178 cd swiper && make compile
181 Then add this to Emacs init:
184 (add-to-list 'load-path "~/git/swiper/")
197 :CUSTOM_ID: getting-started
199 First, enable Ivy completion everywhere:
205 Note: =ivy-mode= can be toggled on and off with ~M-x~ =ivy-mode=.
206 ** Basic customization
208 :CUSTOM_ID: basic-customization
210 Here are some basic settings particularly useful for new Ivy users:
213 (setq ivy-use-virtual-buffers t)
215 (setq ivy-display-style 'fancy)
216 (setq ivy-count-format "(%d/%d) ")
219 For additional customizations, refer to =M-x describe-variable=
224 :CUSTOM_ID: key-bindings
226 ** Global key bindings
228 :CUSTOM_ID: global-key-bindings
230 The recommended key bindings are:
232 - Ivy-based interface to standard commands ::
235 (global-set-key (kbd "C-s") 'swiper)
236 (global-set-key (kbd "M-x") 'counsel-M-x)
237 (global-set-key (kbd "C-x C-f") 'counsel-find-file)
238 (global-set-key (kbd "<f1> f") 'counsel-describe-function)
239 (global-set-key (kbd "<f1> v") 'counsel-describe-variable)
240 (global-set-key (kbd "<f1> l") 'counsel-load-library)
241 (global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
242 (global-set-key (kbd "<f2> u") 'counsel-unicode-char)
245 - Ivy-based interface to shell and system tools ::
248 (global-set-key (kbd "C-c g") 'counsel-git)
249 (global-set-key (kbd "C-c j") 'counsel-git-grep)
250 (global-set-key (kbd "C-c k") 'counsel-ag)
251 (global-set-key (kbd "C-x l") 'counsel-locate)
252 (global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
255 - Ivy-resume and other commands ::
257 =ivy-resume= resumes the last Ivy-based completion.
260 (global-set-key (kbd "C-c C-r") 'ivy-resume)
263 ** Minibuffer key bindings
265 :CUSTOM_ID: minibuffer-key-bindings
268 Ivy includes several minibuffer bindings, which are defined in the
269 =ivy-minibuffer-map= keymap variable. The most frequently used ones
272 =swiper= or =counsel-M-x= add more through the =keymap= argument to
273 =ivy-read=. These keys, also active in the minibuffer, are described
274 under their respective commands.
276 An important idea behind =ivy-minibuffer-map=, unlike
277 e.g. =isearch-mode-map= or Ido keymap is that the minibuffer is a
278 fully capable editing area: bindings like ~C-a~, ~C-f~, ~M-d~,
279 ~M-DEL~, ~M-b~, ~M-w~, ~C-k~, ~C-y~ all work as if you were in a
280 =fundamental-mode= buffer.
282 *** Key bindings for navigation
284 :CUSTOM_ID: key-bindings-for-navigation
287 - ~C-n~ (=ivy-next-line=) selects the next candidate
288 - ~C-p~ (=ivy-previous-line=) selects the previous candidate
289 - ~M-<~ (=ivy-beginning-of-buffer=) selects the first candidate
290 - ~M->~ (=ivy-end-of-buffer=) selects the last candidate
291 - ~C-v~ (=ivy-scroll-up-command=) scrolls up by =ivy-height= lines
292 - ~M-v~ (=ivy-scroll-down-command=) scrolls down by =ivy-height= lines
295 - User Option =ivy-wrap= ::
296 This user option allows to get the wrap-around behavior for ~C-n~
297 and ~C-p~. When set to =t=, =ivy-next-line= and
298 =ivy-previous-line= will cycle past the last and the first
299 candidates respectively.
301 This behavior is off by default.
303 - User Option =ivy-height= ::
304 Use this variable to adjust the minibuffer height, and therefore
305 the scroll size for ~C-v~ and ~M-v~.
307 *** Key bindings for single selection, action, then exit minibuffer
309 :CUSTOM_ID: key-bindings-for-single-selection-action-then-exit-minibuffer
312 Ivy can offer several actions from which to choose which action to
313 run. This "calling an action" operates on the selected candidate. For
314 example, when viewing a list of files, one action could open it for
315 editing, one to view it, another to invoke a special function, and so
316 on. Custom actions can be added to this interface. The precise action
317 to call on the selected candidate can be delayed until after the
318 narrowing is completed. No need to exit the interface if unsure which
319 action to run. This delayed flexibility and customization of actions
320 extends usability of lists in Emacs.
322 - ~C-m~ or ~RET~ (=ivy-done=) ::
323 Calls the default action and exits the minibuffer.
325 - ~M-o~ (=ivy-dispatching-done=) ::
326 Presents all available valid actions from which to choose. When
327 there is only one action available, there is no difference
328 between ~M-o~ and ~C-m~.
330 - ~C-j~ (=ivy-alt-done=) ::
331 When completing file names, selects the current directory
332 candidate and starts a new completion session there. Otherwise,
333 it's the same as =ivy-done=.
335 - ~TAB~ (=ivy-partial-or-done=) ::
336 Attempts partial completion, extending current input as much as
337 possible. ~TAB TAB~ is the same as ~C-j~.
345 (ivy-read "Test: " '("can do" "can't, sorry" "other"))
351 - ~C-M-j~ (=ivy-immediate-done=) ::
352 Exits with /the current input/ instead of /the current candidate/
353 (like other commands).
355 This is useful e.g. when you call =find-file= to create a new
356 file, but the desired name matches an existing file. In that
357 case, using ~C-j~ would select that existing file, which isn't
358 what you want - use this command instead.
360 - ~C-'~ (=ivy-avy=) ::
361 Uses avy to select one of the candidates on the current candidate
362 page. This can often be faster than multiple ~C-n~ or ~C-p~
363 keystrokes followed by ~C-m~.
365 *** Key bindings for multiple selections and actions, keep minibuffer open
367 :CUSTOM_ID: key-bindings-for-multiple-selections-and-actions-keep-minibuffer-open
370 For repeatedly applying multiple actions or acting on multiple
371 candidates, Ivy does not close the minibuffer between commands. It
372 keeps the minibuffer open for applying subsequent actions.
374 Adding an extra meta key to the normal key chord invokes the special
375 version of the regular commands that enables applying multiple
378 - ~C-M-m~ (=ivy-call=) ::
379 Is the non-exiting version of ~C-m~ (=ivy-done=).
381 Instead of closing the minibuffer, ~C-M-m~ allows selecting
382 another candidate or another action. For example, ~C-M-m~ on
383 functions list invokes =describe-function=. When combined with
384 ~C-n~, function descriptions can be invoked quickly in
387 - ~C-M-o~ (=ivy-dispatching-call=) ::
388 Is the non-exiting version of ~M-o~ (=ivy-dispatching-done=).
390 For example, during the =counsel-rhythmbox= completion, press
391 ~C-M-o e~ to en-queue the selected candidate, followed by ~C-n
392 C-m~ to play the next candidate - the current action reverts to
393 the default one after ~C-M-o~.
395 - ~C-M-n~ (=ivy-next-line-and-call=) ::
396 Combines ~C-n~ and ~C-M-m~. Applies an action and moves to next
399 Comes in handy when opening multiple files from
400 =counsel-find-file=, =counsel-git-grep=, =counsel-ag=, or
401 =counsel-locate= lists. Just hold ~C-M-n~ for rapid-fire default
402 action on each successive element of the list.
404 - ~C-M-p~ (=ivy-previous-line-and-call=) ::
405 Combines ~C-p~ and ~C-M-m~.
407 Similar to the above except it moves through the list in the
411 Recalls the state of the completion session just before its last exit.
413 Useful after an accidental ~C-m~ (=ivy-done=).
415 *** Key bindings that alter the minibuffer input
417 :CUSTOM_ID: key-bindings-that-alter-the-minibuffer-input
420 - ~M-n~ (=ivy-next-history-element=) ::
421 Cycles forward through the Ivy command history.
423 Ivy updates an internal history list after each action. When this
424 history list is empty, ~M-n~ inserts symbol (or URL) at point
427 - ~M-p~ (=ivy-previous-history-element=) ::
428 Cycles forward through the Ivy command history.
430 - ~M-i~ (=ivy-insert-current=) ::
431 Inserts the current candidate into the minibuffer.
433 Useful for copying and renaming files, for example: ~M-i~ to
434 insert the original file name string, edit it, and then ~C-m~ to
435 complete the renaming.
437 - ~M-j~ (=ivy-yank-word=) ::
438 Inserts the sub-word at point into the minibuffer.
440 This is similar to ~C-s C-w~ with =isearch=. Ivy reserves ~C-w~
443 - ~S-SPC~ (=ivy-restrict-to-matches=) ::
444 Deletes the current input, and resets the candidates list to the
445 currently restricted matches.
447 This is how Ivy provides narrowing in successive tiers.
449 - ~C-r~ (=ivy-reverse-i-search=) ::
450 Starts a recursive completion session through the command's
453 This works just like ~C-r~ at the bash command prompt, where the
454 completion candidates are the history items. Upon completion, the
455 selected candidate string is inserted into the minibuffer.
457 *** Other key bindings
459 :CUSTOM_ID: other-key-bindings
462 - ~M-w~ (=ivy-kill-ring-save=) ::
463 Copies selected candidates to the kill ring.
465 When the region is active, copies active region instead.
467 *** Hydra in the minibuffer
469 :CUSTOM_ID: hydra-in-the-minibuffer
472 - ~C-o~ (=hydra-ivy/body=) ::
473 Invokes the hydra menu with short key bindings.
475 Minibuffer editing is disabled when Hydra is active. Instead, you get
476 short aliases for the common commands:
478 | Short | Normal | Command name |
479 |-------+-----------+---------------------------|
480 | ~o~ | ~C-g~ | =keyboard-escape-quit= |
481 | ~j~ | ~C-n~ | =ivy-next-line= |
482 | ~k~ | ~C-p~ | =ivy-previous-line= |
483 | ~h~ | ~M-<~ | =ivy-beginning-of-buffer= |
484 | ~l~ | ~M->~ | =ivy-end-of-buffer= |
485 | ~d~ | ~C-m~ | =ivy-done= |
486 | ~f~ | ~C-j~ | =ivy-alt-done= |
487 | ~g~ | ~C-M-m~ | =ivy-call= |
488 | ~u~ | ~C-c C-o~ | =ivy-occur= |
490 Hydra reduces key strokes, for example: ~C-n C-n C-n C-n~ is ~C-o
493 Additionally, you get access to the folowing commands that are
496 - ~c~ (=ivy-toggle-calling=) ::
497 Toggle calling the action after each candidate change. This
498 effectively modifies ~j~ to ~jg~, ~k~ to ~kg~ etc.
500 - ~m~ (=ivy-toggle-fuzzy=) ::
501 Toggle the current regexp matcher.
503 - ~>~ (=ivy-minibuffer-grow=) ::
504 Increase =ivy-height= for the current minibuffer.
506 - ~<~ (=ivy-minibuffer-shrink=) ::
507 Decrease =ivy-height= for the current minibuffer.
509 - ~w~ (=ivy-prev-action=) ::
510 Select the previous action.
512 - ~s~ (=ivy-next-action=) ::
513 Select the next action.
515 - ~a~ (=ivy-read-action=) ::
516 Use a menu to select an action.
518 - ~C~ (=ivy-toggle-case-fold=) ::
519 Toggle case folding (matching both upper and lower case
520 characters with lower case input).
522 *** Saving the current completion session to a buffer
524 :CUSTOM_ID: saving-the-current-completion-session-to-a-buffer
527 - ~C-c C-o~ (=ivy-occur=) ::
528 Saves the current candidates to a new buffer and exits
531 The new buffer is read-only and has a few useful bindings defined.
533 - ~RET~ or ~j~ (=ivy-occur-press=) ::
534 Call the current action on the selected candidate.
536 - ~mouse-1~ (=ivy-occur-click=) ::
537 Call the current action on the selected candidate.
539 - ~j~ (=next-line=) ::
542 - ~k~ (=previous-line=) ::
543 Move to previous line.
545 - ~a~ (=ivy-occur-read-action=) ::
546 Read an action and make it current for this buffer.
548 - ~o~ (=ivy-occur-dispatch=) ::
549 Read an action and call it on the selected candidate.
551 - ~q~ (=quit-window=) ::
552 Bury the current buffer.
555 Ivy has no limit on the number of active buffers like these.
557 Ivy takes care of making these buffer names unique. It applies
558 descriptive names, for example: =*ivy-occur counsel-describe-variable
563 :CUSTOM_ID: completion-styles
566 Ivy's completion functions rely on a regex builder - a function that
567 transforms a string input to a string regex. All current candidates
568 simply have to match this regex. Each collection can be assigned its
569 own regex builder by customizing =ivy-re-builders-alist=.
571 The keys of this alist are collection names, and the values are one of:
574 - =ivy--regex-ignore-order=
578 There's also a catch-all key =t= that applies to all collections that
579 don't have their own key.
584 (setq ivy-re-builders-alist
585 '((t . ivy--regex-plus)))
588 For example, here is how to assign a custom regex builder to file name
592 (setq ivy-re-builders-alist
593 '((read-file-name-internal . ivy--regex-fuzzy)
594 (t . ivy--regex-plus)))
597 Here, =read-file-name-internal= is a function passed as the second
598 argument to =completing-read= when completing file names.
600 The regex builder resolution is a follows, in order of priority:
601 1. =re-builder= argument passed to =ivy-read=.
602 2. =collection= argument passed to =ivy-read= is a function and has an
603 entry on =ivy-re-builders-alist=.
604 3. =caller= argument passed to =ivy-read= has an entry on
605 =ivy-re-builders-alist=.
606 4. =this-command= has an entry on =ivy-re-builders-alist=.
607 5. =t= has an entry on =ivy-re-builders-alist=.
612 :CUSTOM_ID: ivy--regex-plus
615 =ivy--regex-plus= is Ivy's default completion method.
617 =ivy--regex-plus= matches by splitting the input by spaces and
618 rebuilding it into a regex.
620 As the search string is typed in Ivy's minibuffer, it is transformed
621 into proper regex syntax. If the string is ="for example"=, it is
625 "\\(for\\).*\\(example\\)"
628 which in regex terminology matches ="for"= followed by a wild card and
629 then ="example"=. Note how Ivy uses the space character to build wild
630 cards. For literal white space matching in Ivy, use an extra space: to
631 match one space type two spaces, to match two spaces type three
634 As Ivy transforms typed characters into regex strings, it provides an
635 intuitive feedback through font highlights.
637 Ivy supports regexp negation with ="!"=.
638 For example, ="define key ! ivy quit"= first selects everything
639 matching ="define.*key"=, then removes everything matching ="ivy"=,
640 and finally removes everything matching ="quit"=. What remains is the
641 final result set of the negation regexp.
643 Since Ivy treats minibuffer input as a regexp, the standard regexp
644 identifiers work: ="^"=, ="$"=, ="\b"= or ="[a-z]"=. The exceptions
645 are spaces, which translate to =".*"=, and ="!"= that signal the
646 beginning of a negation group.
648 ** ivy--regex-ignore-order
650 :CUSTOM_ID: ivy--regex-ignore-order
653 =ivy--regex-ignore-order= ignores the order of regexp tokens when
654 searching for matching candidates. For instance, the input
655 ="for example"= will match ="example test for"=.
659 :CUSTOM_ID: ivy--regex-fuzzy
662 =ivy--regex-fuzzy= splits each character with a wild card. Searching
663 for ="for"= returns all ="f.*o.*r"= matches, resulting in a large
664 number of hits. Yet some searches need these extra hits. Ivy sorts
665 such large lists using =flx= package's scoring mechanism, if it's
668 In case =ivy--regex-fuzzy= isn't your current regexp builder, you
669 toggle it during completion with ~C-o m~.
673 - =ivy-current-match= ::
674 Highlights the currently selected candidate.
675 - =ivy-minibuffer-match-face-1= ::
676 Highlights the background of the match.
677 - =ivy-minibuffer-match-face-2= ::
678 Highlights the first (modulo 3) matched group.
679 - =ivy-minibuffer-match-face-3= ::
680 Highlights the second (modulo 3) matched group.
681 - =ivy-minibuffer-match-face-4= ::
682 Highlights the third (modulo 3) matched group.
683 - =ivy-confirm-face= ::
684 Highlights the "(confirm)" part of the prompt.
686 Used in conjunction with the built-in
687 =confirm-nonexistent-file-or-buffer= defcustom. When you set
688 this variable to =t=, you'll have to confirm non-existent files
689 and buffer with another ~RET~ in =ivy-mode=.
691 This face will be used to highlight the confirmation prompt.
693 For example, use this setting:
696 (setq confirm-nonexistent-file-or-buffer t)
699 Then call =find-file=, enter "eldorado" and press ~RET~ - the
700 prompt will be appended with "(confirm)". Press ~RET~ once more
701 to confirm, or any key to continue the completion.
702 - =ivy-match-required-face= ::
703 Highlights the "(match required)" part of the prompt.
705 Sometimes, the Emacs functions that call completion specify to it
706 that a match is required, i.e. you can't just type in some random
707 stuff - you have to select one of the candidates given to you.
708 In that case, =ivy-mode= will appropriately change the prompt.
710 For example, call =describe-variable=, enter "waldo" and press
711 ~RET~ - the prompt will be appended with "(match required)".
712 Press any key and the prompt warning will disappear.
714 Highlights directories when completing file names.
716 Highlights remote files when completing file names.
718 Highlights virtual buffers when completing buffer names.
720 Virtual buffers correspond to your bookmarks and the =recentf=
723 Enable the virtual buffers like this:
726 (setq ivy-use-virtual-buffers t)
729 - User Option =ivy-count-format= ::
730 A string that describes how to show the number of candidates and
731 possibly the current candidate in the prompt.
733 By default, the number of matching candidates will be shown as an
734 integer with padding on the right.
736 To disable showing the number of candidates:
739 (setq ivy-count-format "")
742 To show the current candidate, in addition to the number of candidates:
745 (setq ivy-count-format "(%d/%d) ")
748 This variable uses =format=-style switches, see the documentation
749 of =format= for more info.
751 - User Option =ivy-display-style= ::
752 Decides how to highlight the candidates in the minibuffer.
754 The default setting is ='fancy= and it's available only for Emacs
755 versions 24.5 or newer.
757 Set this to =nil= to get a more plain minibuffer.
759 - User Option =ivy-on-del-error-function= ::
760 Decides what to do when ~DEL~ (=ivy-backward-delete-char=)
763 The default behavior is to quit the completion - this is handy if
764 you invoke the completion by mistake.
767 *** What are actions?
768 An action is a function of a single argument that gets called after
769 you select a candidate during completion. The selected candidate is
770 passed to this function as a string argument.
772 - Window context when calling an action ::
773 Currently, the action is executed in the minibuffer window
774 context. This means e.g. that if you call =insert= the text will
775 be inserted into the minibuffer.
777 If you want to execute the action in the initial window from
778 which the completion started, use the =with-ivy-window= wrapper
782 (defun ivy-insert-action (x)
787 *** How can different actions be called?
788 - ~C-m~ (=ivy-done=) calls the current/default action.
789 - ~M-o~ (=ivy-dispatching-done=) selects among all actions, calls it
791 - ~C-M-o~ (=ivy-dispatching-call=) selects among all actions, calls it
794 *** How can the action list be modified?
795 Currently, you can append any amount of your own actions to the
796 default list of actions. This can be done either for a specific
797 command, or for all commands at once.
799 Usually, the command has only one default action. The convention is to
800 use single letters when selecting a command, and the letter ~o~ is
801 designated for the default command. This way, ~M-o o~ should be always
804 *** Example - add two actions to each command
805 The first action inserts the current candidate into the Ivy window -
806 the window from which =ivy-read= was called.
808 The second action copies the current candidate to the kill ring.
811 (defun ivy-yank-action (x)
814 (defun ivy-copy-to-buffer-action (x)
820 '(("i" ivy-copy-to-buffer-action "insert")
821 ("y" ivy-yank-action "yank")))
824 Now in any completion session you can access =ivy-yank-action= with
825 ~M-o y~ and =ivy-copy-to-buffer-action= with ~M-o i~.
827 **** How to undo adding the two actions
828 =ivy-set-actions= simply modifies the internal dict with new data, so
829 you can set the extra actions list to =nil= by assigning =nil= value
833 (ivy-set-actions t nil)
836 **** How to add actions to a specific command
837 Use the command name as the key:
842 '(("i" ivy-copy-to-buffer-action "insert")
843 ("y" ivy-yank-action "yank")))
846 *** Example - define a new command with several actions
848 (defun my-action-1 (x)
849 (message "action-1: %s" x))
851 (defun my-action-2 (x)
852 (message "action-2: %s" x))
854 (defun my-action-3 (x)
855 (message "action-3: %s" x))
857 (defun my-command-with-3-actions ()
859 (ivy-read "test: " '("foo" "bar" "baz")
861 ("o" my-action-1 "action 1")
862 ("j" my-action-2 "action 2")
863 ("k" my-action-3 "action 3"))))
866 Here, the number determines the index of the default action. For each
867 action, the strings are used to describe it during the selection.
869 **** Testing out the above function with =ivy-occur=
870 To examine each action with each candidate in a key-efficient way, try:
872 - Call =my-command-with-3-actions=.
873 - Press ~C-c C-o~ to close the completion and move to an ivy-occur buffer.
874 - Press ~kkk~ to move to the first candidate, since you're likely at the end of the buffer.
875 - Press ~oo~ to call the first action.
876 - Press ~oj~ and ~ok~ to call the second and the third actions.
877 - Press ~j~ to move to the next candidate
881 With the most recent version, =org-mode= will obey
882 =completing-read-function= (which =ivy-mode= sets), so it should
883 work by default. If you try it for refiling to headings with
884 similar names, you'll really notice how much better =ivy-mode= is
887 This setting is needed to use ivy completion:
890 (setq magit-completing-read-function 'ivy-completing-read)
892 - =find-file-in-project= ::
893 Will use ivy by default if it's available.
895 This setting is needed to use ivy completion:
898 (setq projectile-completion-system 'ivy)
901 This setting is needed to use ivy completion:
904 (setq helm-make-completion-method 'ivy)
908 ** File Name Completion
909 Since file name completion is so essential, ivy has a few extra
910 bindings that work here.
912 - ~C-j~ (=ivy-alt-done=) ::
913 Use on a directory to restart the completion from that
914 directory. Use it on a file or =./= to exit the completion with
915 the selected candidate.
916 - ~DEL~ (=ivy-backward-delete-char=) ::
917 When completing file names, and the current input is empty,
918 restart the completion in the parent directory.
919 - ~//~ (=self-insert-command=) ::
920 Switch to the root directory.
921 - ~~~ (=self-insert-command=) ::
922 Switch to the home directory.
923 - ~/~ (=self-insert-command=) ::
924 If the current input is precisely an existing directory, switch
925 the completion to that directory.
926 - ~M-q~ (=ivy-toggle-regexp-quote=) ::
927 Toggle between your input being a regexp and not.
929 Since file names tend to include =.=, which matches any char in
930 regexp mode, you might want to switch to matching literally.
932 - User Option =ivy-extra-directories= ::
933 Decide if you want to see =../= and =./= during file name
936 You might want to remove =../=, since selecting it is the same as
937 ~DEL~. On the other hand, having it around makes it possible to
938 navigate anywhere with only ~C-n~, ~C-p~ and ~C-j~.
940 Similarly, =./= can be removed as well.
943 Completion for TRAMP is supported in a peculiar way. From any
944 directory, with the empty input, inputting =/ssh:= and pressing
945 ~C-j~ (or ~RET~ which is the same thing) will give you a
946 completion for host and user names.
948 You can also input =/ssh:user@= to get domain completion with
949 user name already selected.
951 Described above is a recommended and simple method of
952 interaction. If you find it lacking, you can still use ~C-i~,
953 which does largely the same as the default completion does.
956 The history works with ~M-p~, ~M-n~, and ~C-r~, as in all other
957 completion sessions. A custom history code was implemented for
958 file name completion. This code will cycle you through all
959 previous files that you opened, including the input with which
960 the file was opened. It also works well with TRAMP.
962 ** Buffer Name Completion
963 - User Option =ivy-use-virtual-buffers= ::
964 When non-nil, add =recentf-mode= and bookmarks to =ivy-switch-buffer=.
966 If you add this to your setup:
969 (setq ivy-use-virtual-buffers t)
971 when using =ivy-switch-buffer= additional buffers will be
972 appended to your live buffer list. These buffers will be
973 highlighted with the =ivy-virtual= face, and selecting them will
974 open the corresponding file.
976 The main advantage of using =counsel-= functions over their basic
977 equivalents with =ivy-mode= enabled are the following:
979 1. You can use everything related to multi-actions and non-exiting actions.
980 2. You can use =ivy-resume= to resume your last completion session.
981 3. You can customize them further with =ivy-set-actions=, =ivy-re-builders-alist=.
982 4. You can customize their individual keymaps, like
983 =counsel-describe-map=, =counsel-git-grep-map=, or
984 =counsel-find-file-map=, instead of just customizing
985 =ivy-minibuffer-map= that applies to all completion sessions.
987 The main (and only) entry point is =ivy-read= function. It has only
988 two required arguments and many optional arguments that you can pass
989 by key. Although the =:action= argument is optional, it's very
990 recommended that you use it, otherwise the extra features (as compared
991 to the default completion) like multi-actions, non-exiting actions,
992 =ivy-occur= and =ivy-resume= will not be possible.
994 ** Required arguments for =ivy-read=
996 A format string normally ending in a colon and a space.
998 =%d= anywhere in the string is replaced by the current number of
999 matching candidates. To use a literal =%= character, escape it as
1000 =%%=. See also =ivy-count-format=.
1003 Either a list of strings, a function, an alist or a hash table.
1005 In case it's a function, it has to be compatible with
1008 ** Optional arguments for =ivy-read=
1010 A function to filter the initial collection with, compatible with =all-completions=.
1011 - =require-match= ::
1012 When non-nil, don't let the user exit with a custom input - it
1013 must match one of the candidates.
1014 - =initial-input= ::
1015 A string to be initially inserted into the minibuffer. This
1016 argument is included for compatibility with
1017 =completing-read=. Consider using the =preselect= argument
1018 instead - it's often superior.
1020 A symbol name to store the history. See =completing-read=.
1022 When it's a string, make the first candidate matching this string
1025 When it's an integer, make the candidate with that index
1028 Every time the input becomes empty, the item corresponding to to
1029 =preselect= is selected.
1031 A keymap to be composed with =ivy-minibuffer-map=. This keymap
1032 has priority over =ivy-minibuffer-map= and can be modified at any
1035 A function to call each time the current candidate is changed.
1036 This function takes no arguments and is called in the
1037 minibuffer's =post-command-hook=. See =swiper= for an example
1040 When non-nil, use =ivy-sort-functions-alist= to sort the given
1041 collection. The collection will not be sorted when it's larger
1042 than =ivy-sort-max-size=.
1044 A function to call after a result is selected. Takes a single
1047 A function with no arguments to call before exiting
1048 completion. This function is called even if the completion is
1049 interrupted with e.g. ~C-g~. See =swiper= for an example usage.
1051 A function that takes a string and returns a corresponding regex.
1052 See the section on completion styles.
1054 A function that takes a regex and a list of strings and returns a
1055 list of strings that "match" the regex. Normally a
1056 straightforward function is used. Use this argument to really
1057 fine-tune the matching process. See =counsel-find-file= for an
1059 - =dynamic-collection= ::
1060 When non-nil, =collection= will be used to dynamically generate
1061 the candidates each time the input changes, instead of being used
1062 once statically with =all-completions= to generate a list of
1063 strings. See =counsel-locate= for an example usage.
1065 A symbol to uniquely identify the function that called
1066 =ivy-read=. This is useful in all kinds of customization
1068 ** Example - =counsel-describe-function=
1069 This is a typical example of a function with a non-async collection:
1070 all the strings in the collection are known before the user does any
1073 Note that only the first two arguments (and the =action=) are really
1074 important - the rest is just fine-tuning and could be omitted.
1076 The =action= argument could also be omitted - but then =ivy-read=
1077 would no nothing except returning the string result, which you could
1078 later use yourself. However, it's recommended that you use the
1082 (defun counsel-describe-function ()
1083 "Forward to `describe-function'."
1085 (ivy-read "Describe function: "
1090 (push (symbol-name x) cands))))
1092 :keymap counsel-describe-map
1093 :preselect (counsel-symbol-at-point)
1094 :history 'counsel-describe-symbol-history
1100 :caller 'counsel-describe-function))
1103 Here are the interesting features of the above function, in the order that they appear:
1105 - The =prompt= argument is a simple string ending in ": ".
1106 - The =collection= argument evaluates to a (large) list of strings.
1107 - The =keymap= argument allows for a custom keymap to supplement =ivy-minibuffer-map=.
1108 - The =history= argument ensures that the command has its own history,
1109 and doesn't need to share the common history =ivy-history= that all
1110 commands without their own history share.
1111 - The =require-match= is set to =t=, since it doesn't make sense to
1112 call =describe-function= on an un-interned symbol.
1113 - The =sort= argument is set to =t=, since it's usually useful to have
1114 functions with similar names be close to each other in the candidate
1115 list. However, after loading many packages the collection often
1116 exceeds the default value of =ivy-sort-max-size= (30000). The user
1117 can customize this variable to decide which is more important: the
1118 sorting or the completion start-up time.
1119 - The =action= argument calls =describe-function= on the interned
1121 - The =caller= argument identifies this completion session. This is
1122 important, since with the collection being a list of strings and not
1123 a function name, the only other way for =ivy-read= to identify
1124 "who's calling" and to apply the appropriate customizations is to
1125 examine =this-command=. But =this-command= would be modified if
1126 another command called =counsel-describe-function=.
1127 ** Example - =counsel-locate=
1128 This is a typical example of a function with an async collection.
1129 Since we can't pre-compute all the collection items valid for an empty
1130 input and store them in the memory, the collection function is called
1131 each time the user updates the input. However, while the returned
1132 list of strings is used immediately (usually it's something like
1133 ='("please wait...")=), it's expected of the collection function to
1134 make a call to =start-process= and update the minibuffer text at some
1135 point when the process is finished.
1137 Async collections are a good fit for long-running shell commands, like
1138 =locate=. As soon as there is enough input, a new process is started
1139 and the old process is killed (since the old input is no longer
1140 relevant). The user can either type more or wait for the already
1141 running process to finish and update the minibuffer.
1144 (defun counsel-locate-function (str)
1145 (if (< (length str) 3)
1146 (counsel-more-chars 3)
1147 (counsel--async-command
1148 (format "locate %s '%s'"
1149 (mapconcat #'identity counsel-locate-options " ")
1150 (counsel-unquote-regex-parens
1152 '("" "working...")))
1155 (defun counsel-locate (&optional initial-input)
1156 "Call the \"locate\" shell command.
1157 INITIAL-INPUT can be given as the initial minibuffer input."
1159 (ivy-read "Locate: " #'counsel-locate-function
1160 :initial-input initial-input
1161 :dynamic-collection t
1162 :history 'counsel-locate-history
1163 :action (lambda (file)
1167 :unwind #'counsel-delete-process
1168 :caller 'counsel-locate))
1171 Here are the interesting features of the above functions, in the order
1174 - =counsel-locate-function= takes a string argument and returns a list
1175 of strings. Note that it's not compatible with =all-completions=,
1176 but since we're not using that here, might as well use one argument
1178 - =counsel-more-chars= is a simple function that returns e.g.
1179 ='("2 chars more")= asking the user for more input.
1180 - =counsel--async-command= is a very easy API simplification that
1181 takes a single string argument suitable for
1182 =shell-command-to-string=. So you could prototype your function as
1183 non-async using =shell-command-to-string= and =split-string= to
1184 produce a collection, then decide that you want async and simply swap in
1185 =counsel--async-command=.
1186 - =counsel-locate= is an interactive function with optional =initial-input=.
1187 - =#'counsel-locate-function= is passed as the =collection= argument.
1188 - =dynamic-collection= argument is set to t, since we have an async collection.
1189 - =action= argument uses =with-ivy-window= wrapper, since we want to open the
1190 selected file in the same window from which =counsel-locate= was
1192 - =unwind= argument is set to =#'counsel-delete-process=: when we press ~C-g~
1193 we want to kill the running process created by
1194 =counsel--async-command=.
1195 - =caller= argument identifies this command for easier customization.
1200 :CUSTOM_ID: variable-index