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. ~TAB TAB~ is the same as ~C-j~.
279 ~C-M-j~ (=ivy-immediate-done=) is useful when there is no match for
280 the given input. Or there is an incorrect partial match. ~C-M-j~ with
281 =find-file= lists ignores the partial match and instead takes the
282 current input to create a new directory with =dired-create-directory=.
284 =ivy-immediate-done= illustrates how Ivy distinguishes between calling
285 an action on the /currently selected/ candidate and calling an action
286 on the /current input/.
289 Invoking avy completion with @kbd{C-'} (@code{ivy-avy}).
291 ~C-'~ uses avy's visible jump mechanism, which can further reduce
292 Ivy's line-by-line scrolling that requires multiple ~C-n~ or ~C-p~
295 *** Key bindings for multiple selections and actions, keep minibuffer open
297 For repeatedly applying multiple actions or acting on multiple
298 candidates, Ivy does not close the minibuffer between commands. It
299 keeps the minibuffer open for applying subsequent actions.
301 Adding an extra meta key to the normal key chord invokes the special
302 version of the regular commands that enables applying multiple
305 ~C-M-m~ (=ivy-call=) is the non-exiting version of the default action,
306 ~C-m~ (=ivy-done=). Instead of closing the minibuffer, ~C-M-m~ allows
307 selecting another candidate or another action. For example, ~C-M-m~ on
308 functions list invokes =describe-function=. When combined with ~C-n~,
309 function descriptions can be invoked quickly in succession.
311 ~RET~ exits the minibuffer.
313 =ivy-resume= recalls the state of the completion session just before
314 its last exit. Useful after an accidental ~C-m~ (=ivy-done=).
316 ~C-M-o~ (=ivy-dispatching-call=) is a non-exiting version of ~M-o~
317 (=ivy-dispatching-done=) that can accumulate candidates into a queue.
318 For example, for playback in =counsel-rhythmbox=, ~C-M-o e~ en-queues
319 the selected candidate, and ~C-n C-m~ plays the next one in the queue.
321 ~C-M-n~ (=ivy-next-line-and-call=) combines ~C-n~ and ~C-M-m~. Applies
322 an action and moves to next line. Comes in handy when opening multiple
323 files from =counsel-find-file=, =counsel-git-grep=, =counsel-ag=, or
324 =counsel-locate= lists. Just hold ~C-M-n~ for rapid-fire default
325 action on each successive element of the list.
327 ~C-M-p~ (=ivy-previous-line-and-call=) combines ~C-p~ and ~C-M-m~. Is
328 the same as above except that it moves through the list in the other
331 *** Key bindings that alter the minibuffer input
333 ~M-n~ (=ivy-next-history-element=) and ~M-p~
334 (=ivy-previous-history-element=) cycle through the Ivy command
335 history. Ivy updates an internal history list after each action. When
336 this history list is empty, ~M-n~ inserts symbol (or URL) at point
339 ~M-i~ (=ivy-insert-current=) inserts the current candidate into the
340 minibuffer. Useful for copying and renaming files, for example: ~M-i~
341 to insert the original file name string, edit it, and then ~C-m~ to
342 complete the renaming.
344 ~M-j~ (=ivy-yank-word=) inserts the sub-word at point into the
345 minibuffer. This is similar to ~C-s C-w~ with =isearch=. Ivy reserves
346 ~C-w~ for =kill-region=.
348 ~S-SPC~ (=ivy-restrict-to-matches=) deletes the current input, and
349 resets the candidates list to the currently restricted matches. This
350 is how Ivy provides narrowing in successive tiers.
352 ~C-r~ (=ivy-reverse-i-search=) works just like ~C-r~ at bash command
353 prompt, where the completion candidates are the history items. Upon
354 completion, the selected candidate string is inserted into the
357 *** Other key bindings
359 ~M-w~ (=ivy-kill-ring-save=) copies selected candidates to the kill
360 ring; when the region is active, copies active region.
362 *** Hydra in the minibuffer
364 ~C-o~ (=hydra-ivy/body=) invokes Hydra menus with key shortcuts.
366 ~C-o~ or ~i~ resumes editing.
368 Hydra reduces key strokes, for example: ~C-n C-n C-n C-n~ is ~C-o
369 jjjj~ in Hydra. Hydra has other benefits besides certain shorter key
371 - ~<~ and ~>~ to adjust height of minibuffer,
372 - describes the current completion state, such as case folding and the
375 Minibuffer editing is disabled when Hydra is active.
377 *** Saving the current completion session to a buffer
379 ~C-c C-o~ (=ivy-occur=) saves the current candidates to a new buffer;
380 the list is active in the new buffer.
382 ~RET~ or ~mouse-1~ in the new buffer calls the appropriate action on
383 the selected candidate.
385 Ivy has no limit on the number of active buffers like these.
387 Ivy takes care of making these buffer names unique. It applies
388 descriptive names, for example: =*ivy-occur counsel-describe-variable
393 Ivy's completion functions rely on the highly configurable regex
398 (setq ivy-re-builders-alist
399 '((t . ivy--regex-plus)))
402 The default =ivy--regex-plus= narrowing is always invoked unless
403 specified otherwise. For example, file name completion may have a
404 custom completion function:
406 (setq ivy-re-builders-alist
407 '((read-file-name-internal . ivy--regex-fuzzy)
408 (t . ivy--regex-plus)))
411 Ivy's flexibility extends to using different styles of completion
412 mechanics (regex-builders) for different types of lists. Despite this
413 flexibility, Ivy operates within a consistent and uniform interface.
414 The main regex-builders currently in Ivy are:
418 =ivy--regex-plus= is Ivy's default completion method.
420 =ivy--regex-plus= matches by splitting the input by spaces and
421 rebuilding it into a regex.
423 As the search string is typed in Ivy's minibuffer, it is transformed
424 into proper regex syntax. If the string is "for example", it is
428 "\\(for\\).*\\(example\\)"
431 which in regex terminology matches "for" followed by a wild card and
432 then "example". Note how Ivy uses the space character to build
433 wild cards. For literal white space matching in Ivy, use an extra space:
434 to match one space type two spaces, to match two spaces type three
437 As Ivy transforms typed characters into regex strings, it provides an
438 intuitive feedback through font highlights.
440 Ivy supports regexp negation with "!". For example, "define key ! ivy
441 quit" first selects everything matching "define.*key", then removes
442 everything matching "ivy", and finally removes everything matching
443 "quit". What remains is the final result set of the negation regexp.
446 Standard regexp identifiers work:
448 "^", "$", "\b" or "[a-z]"
451 Since Ivy treats minibuffer input as a regexp, standard regexp
452 identifiers work as usual. The exceptions are spaces, which
453 translate to ".*", and "!" that signal the beginning of a negation
456 ** ivy--regex-ignore-order
458 =ivy--regex-ignore-order= ignores the order of regexp tokens when
459 searching for matching candidates. For instance, the input "for
460 example" will match "example test for". Otherwise =ivy--regex-plus=
461 normal behavior is to honor the order of regexp tokens.
465 =ivy--regex-fuzzy= splits each character with a wild card. Searching
466 for "for" returns all "f.*o.*r" matches, resulting in a large number
467 of hits. Yet some searches need these extra hits. Ivy sorts such
468 large lists using =flx= package's scoring mechanism, if it's