1 #+TITLE: Ivy User Manual
3 #+EMAIL: ohwoeowho@gmail.com
7 #+TEXINFO_DIR_CATEGORY: Emacs
8 #+TEXINFO_DIR_TITLE: Ivy: (ivy).
9 #+TEXINFO_DIR_DESC: Using Ivy for completion.
10 #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css"/>
12 #+OPTIONS: H:6 num:6 toc:4
15 #+MACRO: defopt #+TEXINFO: @defopt $1
16 #+MACRO: endopt #+TEXINFO: @end defopt
24 Ivy manual, version 0.7.0
26 Ivy is an interactive interface for completion in Emacs. Emacs uses
27 completion mechanism in a variety of contexts: code, menus, commands,
28 variables, functions, etc. Completion entails listing, sorting,
29 filtering, previewing, and applying actions on selected items. When
30 active, @code{ivy-mode} completes the selection process by narrowing
31 available choices while previewing in the minibuffer. Selecting the
32 final candidate is either through simple keyboard character inputs or
33 through powerful regular expressions. @end ifnottex
35 Copyright @copyright{} 2015 Free Software Foundation, Inc.
38 Permission is granted to copy, distribute and/or modify this document
39 under the terms of the GNU Free Documentation License, Version 1.3 or
40 any later version published by the Free Software Foundation; with no
41 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
42 and with the Back-Cover Texts as in (a) below. A copy of the license
43 is included in the section entitled ``GNU Free Documentation License.''
45 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
46 modify this GNU manual.''
51 Ivy is for quick and easy selection from a list. When Emacs prompts
52 for a string from a list of several possible choices, Ivy springs into
53 action to assist in narrowing and picking the right string from a vast
56 Ivy strives for minimalism, simplicity, customizability and
60 @subsubheading Minimalism
62 Uncluttered minibuffer is minimalism. Ivy shows the completion
63 defaults, the number of matches, and 10 candidate matches below the
64 input line. Customize =ivy-length= to adjust the number of candidate
65 matches displayed in the minibuffer.
68 @subsubheading Simplicity
70 Simplicity is about Ivy's behavior in the minibuffer. It is also about
71 the code interface to extend Ivy's functionality. The minibuffer area
72 behaves as close to =fundamental-mode= as possible. ~SPC~ inserts a
73 space, for example, instead of being bound to the more complex
74 =minibuffer-complete-word=. Ivy's code uses easy-to-examine global
75 variables; avoids needless complications with branch-introducing
79 @subsubheading Customizability
81 Customizability is about being able to use different methods and
82 interfaces of completion to tailor the selection process. For example,
83 adding a custom display function that points to a selected candidate
84 with =->=, instead of highlighting the selected candidate with the
85 =ivy-current-match= face. Or take the customization of actions, say
86 after the candidate function is selected. ~RET~ uses
87 =counsel-describe-function= to describe the function, whereas ~M-o d~
88 jumps to that function's definition in the code. The ~M-o~ prefix can
89 be uniformly used with characters like ~d~ to group similar actions.
92 @subsubheading Discoverability
94 Ivy displays easily discoverable commands through the hydra facility.
95 ~C-o~ in the minibuffer displays a hydra menu. It opens up within an
96 expanded minibuffer area. Each menu item comes with short
97 documentation strings and highlighted one-key completions. So
98 discovering even seldom used keys is simply a matter of ~C-o~ in the
99 minibuffer while in the midst of the Ivy interaction. This
100 discoverability minimizes exiting Ivy interface for documentation
105 Install Ivy automatically through Emacs's package manager, or manually
106 from Ivy's development repository.
108 ** Installing from Emacs Package Manager
110 ~M-x~ =package-install= ~RET~ =swiper= ~RET~
112 Ivy is installed as part of =swiper= package. =swiper= is available
113 from two different package archives, GNU ELPA and MELPA. For the
114 latest stable version, use the GNU ELPA archives using the above M-x
117 For current hourly builds, use the MELPA archives. See the code below
118 for adding MELPA to the list of package archives:
122 (add-to-list 'package-archives
123 '("melpa" . "http://melpa.org/packages/"))
126 After this do ~M-x~ =package-refresh-contents= ~RET~, followed by
127 ~M-x~ =package-install= ~RET~ =swiper= ~RET~.
129 For package manager details, see [[info:emacs#Packages]].
131 ** Installing from the Git repository
133 Why install from Git?
135 - No need to wait for MELPA's hourly builds
136 - Easy to revert to previous versions
137 - Contribute to Ivy's development; send patches; pull requests
139 *Configuration steps*
141 First clone the Swiper repository:
143 cd ~/git && git clone https://github.com/abo-abo/swiper
144 cd swiper && make compile
147 Then add this to Emacs init:
149 (add-to-list 'load-path "~/git/swiper/")
161 First enable Ivy completion everywhere:
167 Note: =ivy-mode= can be toggled on and off with ~M-x~ =ivy-mode=.
168 ** Basic customization
169 Here are some basic settings particularly useful for new Ivy
172 (setq ivy-use-virtual-buffers t)
174 (setq ivy-display-style 'fancy)
175 (setq ivy-count-format "(%d/%d) ")
178 For additional customizations, refer to =M-x describe-variable=
182 ** Global key bindings
184 Recommended key bindings are:
186 @subsubheading Ivy-based interface to standard commands
189 (global-set-key (kbd "C-s") 'swiper)
190 (global-set-key (kbd "M-x") 'counsel-M-x)
191 (global-set-key (kbd "C-x C-f") 'counsel-find-file)
192 (global-set-key (kbd "<f1> f") 'counsel-describe-function)
193 (global-set-key (kbd "<f1> v") 'counsel-describe-variable)
194 (global-set-key (kbd "<f1> l") 'counsel-load-library)
195 (global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
196 (global-set-key (kbd "<f2> u") 'counsel-unicode-char)
199 @subsubheading Ivy-based interface to shell and system tools
202 (global-set-key (kbd "C-c g") 'counsel-git)
203 (global-set-key (kbd "C-c j") 'counsel-git-grep)
204 (global-set-key (kbd "C-c k") 'counsel-ag)
205 (global-set-key (kbd "C-x l") 'counsel-locate)
206 (global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
209 @subsubheading Ivy-resume and other commands
211 =ivy-resume= resumes the last Ivy-based completion.
213 (global-set-key (kbd "C-c C-r") 'ivy-resume)
216 ** Minibuffer key bindings
218 Ivy includes several minibuffer bindings, which are defined in the
219 =ivy-minibuffer-map= keymap variable. The most frequently used ones
222 =swiper= or =counsel-M-x= add more through the =keymap= argument to
223 =ivy-read=. These keys, also active in the minibuffer, are described
224 under their respective commands.
226 *** Key bindings for navigation
228 - ~C-n~ (=ivy-next-line=) selects the next candidate
229 - ~C-p~ (=ivy-previous-line=) selects the previous candidate
230 - ~M-<~ (=ivy-beginning-of-buffer=) selects the first candidate
231 - ~M->~ (=ivy-end-of-buffer=) selects the last candidate
232 - ~C-v~ (=ivy-scroll-up-command=) scrolls up by =ivy-height= lines
233 - ~M-v~ (=ivy-scroll-down-command=) scrolls down by =ivy-height= lines
235 {{{defopt(ivy-wrap)}}}
236 This user option allows to get the wrap-around behavior for ~C-n~ and
237 ~C-p~. When set to =t=, =ivy-next-line= and =ivy-previous-line= will
238 cycle past the last and the first candidates respectively.
240 This behavior is off by default.
243 {{{defopt(ivy-height)}}}
244 Use this variable to adjust the minibuffer height, and therefore the
245 scroll size for ~C-v~ and ~M-v~.
248 *** Key bindings for single selection, action, then exit minibuffer
250 Ivy can offer several actions from which to choose which action to
251 run. This "calling an action" operates on the selected candidate. For
252 example, when viewing a list of files, one action could open it for
253 editing, one to view it, another to invoke a special function, and so
254 on. Custom actions can be added to this interface. The precise action
255 to call on the selected candidate can be delayed until after the
256 narrowing is completed. No need to exit the interface if unsure which
257 action to run. This delayed flexibility and customization of actions
258 extends usability of lists in Emacs.
260 ~C-m~ or ~RET~ (=ivy-done=) calls the default action and exits the
263 ~M-o~ (=ivy-dispatching-done=) presents all available valid actions
264 from which to choose. When there is only one action available, there
265 is no difference between ~M-o~ and ~C-m~.
267 ~C-j~ (=ivy-alt-done=) calls the alternate action, such as completing
268 a directory name in a file list whereas ~C-m~ will select that directory
269 and exit the minibuffer.
271 Exiting the minibuffer also closes the Ivy window (as specified by
272 =ivy-height=). This closing and exiting sequence is conveniently off
273 when applying multiple actions. Multiple actions and multiple
274 selections as covered in the next section of this manual.
276 ~TAB~ (=ivy-partial-or-done=) attempts partial completion, extending
277 current input as much as possible.
279 ~TAB TAB~ is the same as ~C-j~.
281 ~C-M-j~ (=ivy-immediate-done=) is useful when there is no match for
282 the given input. Or there is an incorrect partial match. ~C-M-j~ with
283 =find-file= lists ignores the partial match and instead takes the
284 current input to create a new directory with =dired-create-directory=.
286 =ivy-immediate-done= illustrates how Ivy distinguishes between calling
287 an action on the /currently selected/ candidate and calling an action
288 on the /current input/.
291 Invoking avy completion with @kbd{C-'} (@code{ivy-avy}).
293 ~C-`~ uses avy's visible jump mechanism, which can further reduce
294 Ivy's line-by-line scrolling that requires multiple ~C-n~ or ~C-p~
297 *** Key bindings for multiple selections and actions, keep minibuffer open
299 For repeatedly applying multiple actions or acting on multiple
300 candidates, Ivy does not close the minibuffer between commands. It
301 keeps the minibuffer open for applying subsequent actions.
303 Adding an extra meta key to the normal key chord invokes the special
304 version of the regular commands that enables applying multiple
307 ~C-M-m~ (=ivy-call=) is the non-exiting version of the default action,
308 ~C-m~ (=ivy-done=). Instead of closing the minibuffer, ~C-M-m~ allows
309 selecting another candidate or another action. For example, ~C-M-m~ on
310 functions list invokes =describe-function=. When combined with ~C-n~,
311 function descriptions can be invoked quickly in succession.
313 ~RET~ exits the minibuffer.
315 =ivy-resume= recalls the state of the completion session just before
316 its last exit. Useful after an accidental ~C-m~ (=ivy-done=).
318 ~C-M-o~ (=ivy-dispatching-call=) is a non-exiting version of ~M-o~
319 (=ivy-dispatching-done=) that can accumulate candidates into a queue.
320 For example, for playback in =counsel-rhythmbox=, ~C-M-o e~ en-queues
321 the selected candidate, and ~C-n C-m~ plays the next one in the queue.
323 ~C-M-n~ (=ivy-next-line-and-call=) combines ~C-n~ and ~C-M-m~. Applies
324 an action and moves to next line. Comes in handy when opening multiple
325 files from =counsel-find-file=, =counsel-git-grep=, =counsel-ag=, or
326 =counsel-locate= lists. Just hold ~C-M-n~ for rapid-fire default
327 action on each successive element of the list.
329 ~C-M-p~ (=ivy-previous-line-and-call=) combines ~C-p~ and ~C-M-m~. Is
330 the same as above except that it moves through the list in the other
333 *** Key bindings that alter minibuffer input
335 ~M-n~ (=ivy-next-history-element=) and ~M-p~
336 (=ivy-previous-history-element=) cycle through the Ivy command
337 history. Ivy updates an internal history list after each action. When
338 this history list is empty, ~M-n~ inserts symbol (or URL) at point
341 ~M-i~ (=ivy-insert-current=) inserts the current candidate into the
342 minibuffer. Useful for copying and renaming files, for example: ~M-i~
343 to insert the original file name string, edit it, and then ~C-m~ to
344 complete the renaming.
346 ~M-j~ (=ivy-yank-word=) inserts sub-word at point into minibuffer. This
347 is similar to ~C-s C-w~ with =isearch=. Ivy reserves ~C-w~ for
350 ~S-SPC~ (=ivy-restrict-to-matches=) deletes the current input, and
351 resets the candidates list to the currently restricted matches. This
352 is how Ivy provides narrowing in successive tiers.
354 ~C-r~ (=ivy-reverse-i-search=) works just like ~C-r~ at bash command
355 prompt, where the completion candidates are the history items. Upon
356 completion, the selected candidate string is inserted into the
359 *** Other key bindings
361 ~M-w~ (=ivy-kill-ring-save=) copies selected candidates to the kill
362 ring; when the region is active, copies active region.
364 *** Hydra in the minibuffer
366 ~C-o~ (=hydra-ivy/body=) invokes Hydra menus with key shortcuts.
368 ~C-o~ or ~i~ resumes editing.
370 Hydra reduces key strokes, for example: ~C-n C-n C-n C-n~ is ~C-o
371 jjjj~ in Hydra. Hydra has other benefits besides certain shorter key
373 - ~<~ and ~>~ to adjust height of minibuffer,
374 - describes the current completion state, such as case folding and the
377 Minibuffer editing is disabled when Hydra is active.
379 *** Saving the current completion session to a buffer
381 ~C-c C-o~ (=ivy-occur=) saves the current candidates to a new buffer;
382 the list is active in the new buffer.
384 ~RET~ or ~mouse-1~ in the new buffer calls the appropriate action on
385 the selected candidate.
387 Ivy has no limit on the number of active buffers like these.
389 Ivy takes care of making these buffer names unique. It applies
390 descriptive names, for example: =*ivy-occur counsel-describe-variable
395 Ivy's completion functions rely on the highly configurable regex
400 (setq ivy-re-builders-alist
401 '((t . ivy--regex-plus)))
404 The default =ivy--regex-plus= narrowing is always invoked unless
405 specified otherwise. For example, file name completion may have a
406 custom completion function:
408 (setq ivy-re-builders-alist
409 '((read-file-name-internal . ivy--regex-fuzzy)
410 (t . ivy--regex-plus)))
413 Ivy's flexibility extends to using different styles of completion
414 mechanics (regex-builders) for different types of lists. Despite this
415 flexibility, Ivy operates within a consistent and uniform interface.
416 The main regex-builders currently in Ivy are:
420 =ivy--regex-plus= is Ivy's default completion method.
422 =ivy--regex-plus= matches by splitting the input by spaces and
423 rebuilding it into a regex.
425 As the search string is typed in Ivy's minibuffer, it is transformed
426 into proper regex syntax. If the string is "for example", it is
430 "\\(for\\).*\\(example\\)"
433 which in regex terminology matches "for" followed by a wild card and
434 then "example". Note how Ivy uses the space character to build
435 wild cards. For literal white space matching in Ivy, use an extra space:
436 to match one space type two spaces, to match two spaces type three
439 As Ivy transforms typed characters into regex strings, it provides an
440 intuitive feedback through font highlights.
442 Ivy supports regexp negation with "!". For example, "define key ! ivy
443 quit" first selects everything matching "define.*key", then removes
444 everything matching "ivy", and finally removes everything matching
445 "quit". What remains is the final result set of the negation regexp.
448 Standard regexp identifiers work:
450 "^", "$", "\b" or "[a-z]"
453 Since Ivy treats minibuffer input as a regexp, standard regexp
454 identifiers work as usual. The exceptions are spaces, which
455 translate to ".*", and "!" that signal the beginning of a negation
458 ** ivy--regex-ignore-order
460 =ivy--regex-ignore-order= ignores the order of regexp tokens when
461 searching for matching candidates. For instance, the input "for
462 example" will match "example test for". Otherwise =ivy--regex-plus=
463 normal behavior is to honor the order of regexp tokens.
467 =ivy--regex-fuzzy= splits each character with a wild card. Searching
468 for "for" returns all "f.*o.*r" matches, resulting in a large number
469 of hits. Yet some searches need these extra hits. Ivy sorts such
470 large lists using =flx= package's scoring mechanism, if it's