Ivy User Manual
Writing this manual
To highlight a section without introducing a new subheading use
definition lists. The definition list “owns” the subsequent text if
the text is indented by 5 spaces. Use
C-q to indent the
paragraphs. Start new paragraphs with 5 spaces indented. To separate
definition lists from regular lists, use two newlines.
A typical definition list:
- ~C-M-j~ (=ivy-immediate-done=) ::
The code and kbd part is recognized and added as
Use definition lists to declare a
@defopt section for
defvar. For proper Texinfo export, use this form:
User Option =ivy-wrap= ::
CUSTOM_ID property to name each heading. For example,
C-u L. This will result in consistent HTML node names.
Keep one empty line before each source block for proper Texinfo exports.
Exporting to texinfo
ivy.texi is generated from ivy.org. To update the .texi file, eval
C-c C-e i t in the ivy.org bufer.
Ivy manual, version 0.8.0
Ivy is an interactive interface for completion in Emacs. Emacs uses
completion mechanism in a variety of contexts: code, menus, commands,
variables, functions, etc. Completion entails listing, sorting,
filtering, previewing, and applying actions on selected items. When
ivy-mode completes the selection process by narrowing
available choices while previewing in the minibuffer. Selecting the
final candidate is either through simple keyboard character inputs or
through powerful regular expressions.
Copyright (C) 2015 Free Software Foundation, Inc.
This manual source
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual.”
Ivy is for quick and easy selection from a list. When Emacs prompts for a string from a list of several possible choices, Ivy springs into action to assist in narrowing and picking the right string from a vast number of choices. Introduction
Ivy strives for minimalism, simplicity, customizability and discoverability.
Uncluttered minibuffer is minimalism. Ivy shows the completion
defaults, the number of matches, and 10 candidate matches below
the input line. Customize
ivy-heightto adjust the number of candidate matches displayed in the minibuffer.
Simplicity is about Ivy’s behavior in the minibuffer. It is also
about the code interface to extend Ivy’s functionality. The
minibuffer area behaves as close to
SPCinserts a space, for example, instead of being bound to the more complex
minibuffer-complete-word. Ivy’s code uses easy-to-examine global variables; avoids needless complications with branch-introducing custom macros.
Customizability is about being able to use different methods and
interfaces of completion to tailor the selection process. For
example, adding a custom display function that points to a
selected candidate with
>, instead of highlighting the selected candidate with the
ivy-format-function). Or take the customization of actions, say after the candidate function is selected.
counsel-describe-functionto describe the function, whereas
M-o djumps to that function’s definition in the code. The
M-oprefix can be uniformly used with characters like
dto group similar actions.
Ivy displays easily discoverable commands through the hydra
C-oin the minibuffer displays a hydra menu. It opens up within an expanded minibuffer area. Each menu item comes with short documentation strings and highlighted one-key completions. So discovering even seldom used keys is simply a matter of
C-oin the minibuffer while in the midst of the Ivy interaction. This discoverability minimizes exiting Ivy interface for documentation look-ups.
Install Ivy automatically through Emacs’s package manager, or manually from Ivy’s development repository.
Emacs 24.3.1 is the oldest version to run Ivy. Emacs 24.5.1 is the oldest version that runs Ivy with fancy faces display.
Installing from Emacs Package Manager
Ivy is installed as part of
ivy package, which is available from two
different package archives, GNU ELPA and MELPA. For the latest stable
version, use the GNU ELPA archives using the above M-x command.
For current hourly builds, use the MELPA archives. In MELPA, Ivy is
split into three packages:
counsel; you can simply
counsel which will bring in the other two as dependencies.
See the code below for adding MELPA to the list of package archives:
(require 'package) (add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/"))
After this do
RET, followed by
For package manager details, see info:emacs#Packages.
Installing from the Git repository
- Why install from Git?
- No need to wait for MELPA’s hourly builds
- Easy to revert to previous versions
- Contribute to Ivy’s development; send patches; pull requests
- Configuration steps
First clone the Swiper repository with:
cd ~/git && git clone https://github.com/abo-abo/swiper cd swiper && make compile
Second, add these lines to the Emacs init file:
(add-to-list 'load-path "~/git/swiper/") (require 'ivy)
Then, update the code with:
git pull make
First enable Ivy completion everywhere: Getting started
ivy-mode can be toggled on and off with
Here are some basic settings particularly useful for new Ivy users: Basic customization
(setq ivy-use-virtual-buffers t) (setq ivy-count-format "(%d/%d) ")
If you want, you can go without any customizations at all. The above settings are the most bang for the buck in terms of customization. So users that typically don’t like customize a lot are advised to look at these settings first.
For more advanced customizations, refer to
The recommended key bindings are: Global key bindings
- Ivy-based interface to standard commands
(global-set-key (kbd "C-s") 'swiper) (global-set-key (kbd "M-x") 'counsel-M-x) (global-set-key (kbd "C-x C-f") 'counsel-find-file) (global-set-key (kbd "<f1> f") 'counsel-describe-function) (global-set-key (kbd "<f1> v") 'counsel-describe-variable) (global-set-key (kbd "<f1> l") 'counsel-find-library) (global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol) (global-set-key (kbd "<f2> u") 'counsel-unicode-char)
- Ivy-based interface to shell and system tools
(global-set-key (kbd "C-c g") 'counsel-git) (global-set-key (kbd "C-c j") 'counsel-git-grep) (global-set-key (kbd "C-c k") 'counsel-ag) (global-set-key (kbd "C-x l") 'counsel-locate) (global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
- Ivy-resume and other commands
ivy-resumeresumes the last Ivy-based completion.
(global-set-key (kbd "C-c C-r") 'ivy-resume)
Minibuffer key bindings
Ivy includes several minibuffer bindings, which are defined in the
ivy-minibuffer-map keymap variable. The most frequently used ones
are described here.
counsel-M-x add more key bindings through the
ivy-read. These keys, also active in the minibuffer, are
described under their respective commands.
A key feature of
ivy-minibuffer-map is its full editing capability
where the familiar
C-y key bindings work the same as in
Key bindings for navigation
ivy-next-line) selects the next candidate
ivy-previous-line) selects the previous candidate
ivy-beginning-of-buffer) selects the first candidate
ivy-end-of-buffer) selects the last candidate
ivy-scroll-up-command) scrolls up by
ivy-scroll-down-command) scrolls down by
- User Option
Specifies the wrap-around behavior for
ivy-wrapis set to
ivy-previous-linewill cycle past the last and the first candidates respectively.
Warp-around behavior is off by default.
- User Option
Use this option to adjust the minibuffer height, which also
affects scroll size when using
ivy-heightis 10 lines by default.
Key bindings for single selection, action, then exit minibuffer
Ivy can offer several actions from which to choose which action to run. This “calling an action” operates on the selected candidate. For example, when viewing a list of files, one action could open it for editing, one to view it, another to invoke a special function, and so on. Custom actions can be added to this interface. The precise action to call on the selected candidate can be delayed until after the narrowing is completed. No need to exit the interface if unsure which action to run. This delayed flexibility and customization of actions extends usability of lists in Emacs.
- Calls the default action and then exits the minibuffer.
Presents valid actions from which to choose. When only one action
is available, there is no difference between
When completing file names, selects the current directory
candidate and starts a new completion session there. Otherwise,
it is the same as
Attempts partial completion, extending current input as much as
TAB TABis the same as
Example ERT test:
(should (equal (ivy-with '(progn (ivy-read "Test: " '("can do" "can't, sorry" "other")) ivy-text) "c <tab>") "can"))
Exits with the current input instead of the current candidate
(like other commands).
This is useful e.g. when you call
find-fileto create a new file, but the desired name matches an existing file. In that case, using
C-jwould select that existing file, which isn’t what you want - use this command instead.
- ~C-‘~ (
Uses avy to select one of the candidates on the current candidate
page. This can often be faster than multiple
C-pkeystrokes followed by
Key bindings for multiple selections and actions, keep minibuffer open
For repeatedly applying multiple actions or acting on multiple candidates, Ivy does not close the minibuffer between commands. It keeps the minibuffer open for applying subsequent actions.
Adding an extra meta key to the normal key chord invokes the special version of the regular commands that enables applying multiple actions.
Is the non-exiting version of
Instead of closing the minibuffer,
C-M-mallows selecting another candidate or another action. For example,
C-M-mon functions list invokes
describe-function. When combined with
C-n, function descriptions can be invoked quickly in succession.
Is the non-exiting version of
For example, during the
C-M-o eto en-queue the selected candidate, followed by
C-n C-mto play the next candidate - the current action reverts to the default one after
C-M-m. Applies an action and moves to next line.
Comes in handy when opening multiple files from
counsel-locatelists. Just hold
C-M-nfor rapid-fire default action on each successive element of the list.
Similar to the above except it moves through the list in the other direction.
Recalls the state of the completion session just before its last
Useful after an accidental
Key bindings that alter the minibuffer input
Cycles forward through the Ivy command history.
Ivy updates an internal history list after each action. When this history list is empty,
M-ninserts symbol (or URL) at point into the minibuffer.
- Cycles forward through the Ivy command history.
Inserts the current candidate into the minibuffer.
Useful for copying and renaming files, for example:
M-ito insert the original file name string, edit it, and then
C-mto complete the renaming.
Inserts the sub-word at point into the minibuffer.
This is similar to
isearch. Ivy reserves
Deletes the current input, and resets the candidates list to the
currently restricted matches.
This is how Ivy provides narrowing in successive tiers.
Starts a recursive completion session through the command’s
This works just like
C-rat the bash command prompt, where the completion candidates are the history items. Upon completion, the selected candidate string is inserted into the minibuffer.
Other key bindings
Copies selected candidates to the kill ring.
Copies the region if the region is active.
Hydra in the minibuffer
- Invokes the hydra menu with short key bindings.
When Hydra is active, minibuffer editing is disabled and menus display short aliases:
Hydra reduces key strokes, for example:
C-n C-n C-n C-n is
jjjj in Hydra.
Hydra menu offers these additioanl bindings:
Toggle calling the action after each candidate change. It
- Toggle the current regexp matcher.
ivy-heightfor the current minibuffer.
ivy-heightfor the current minibuffer.
- Select the previous action.
- Select the next action.
- Use a menu to select an action.
- Toggle case folding (match both upper and lower case characters for lower case input).
Saving the current completion session to a buffer
- Saves the current candidates to a new buffer and exits completion.
The new buffer is read-only and has a few useful bindings defined.
- Call the current action on the selected candidate.
- Call the current action on the selected candidate.
- Move to next line.
- Move to previous line.
- Read an action and make it current for this buffer.
- Read an action and call it on the selected candidate.
- Bury the current buffer.
Ivy has no limit on the number of active buffers like these.
Ivy takes care of naming buffers uniquely by constructing descriptive
names. For example:
Ivy’s completion functions rely on a regex builder - a function that
transforms a string input to a string regex. All current candidates
simply have to match this regex. Each collection can be assigned its
own regex builder by customizing
The keys of this alist are collection names, and the values are one of the following:
A catch-all key,
t, applies to all collections that don’t have their
The default is:
(setq ivy-re-builders-alist '((t . ivy--regex-plus)))
This example shows a custom regex builder assigned to file name completion:
(setq ivy-re-builders-alist '((read-file-name-internal . ivy--regex-fuzzy) (t . ivy--regex-plus)))
read-file-name-internal is a function that is passed as the
second argument to
completing-read for file name completion.
The regex builder resolves as follows (in order of priority):
re-builderargument passed to
collectionargument passed to
ivy-readis a function and has an entry on
callerargument passed to
ivy-readhas an entry on
this-commandhas an entry on
thas an entry on
ivy--regex-plus is Ivy’s default completion method.
ivy--regex-plus matches by splitting the input by spaces and
rebuilding it into a regex.
As the search string is typed in Ivy’s minibuffer, it is transformed into valid regex syntax. If the string is =”for example”=, it is transformed into
which in regex terminology matches =”for”= followed by a wild card and then =”example”=. Note how Ivy uses the space character to build wild cards. To match a literal white space, use an extra space. So to match one space type two spaces, to match two spaces type three spaces, and so on.
As Ivy transforms typed characters into regex strings, it provides an intuitive feedback through font highlights.
Ivy supports regexp negation with =”!”=. For example, =”define key ! ivy quit”= first selects everything matching =”define.*key”=, then removes everything matching =”ivy”=, and finally removes everything matching =”quit”=. What remains is the final result set of the negation regexp.
Since Ivy treats minibuffer input as a regexp, the standard regexp identifiers work: =”^”=, =”$”=, =”\b”= or =”[a-z]”=. The exceptions are spaces, which translate to =”.*”=, and =”!”= that signal the beginning of a negation group.
ivy--regex-ignore-order ignores the order of regexp tokens when
searching for matching candidates. For instance, the input
=”for example”= will match =”example test for”=.
ivy--regex-fuzzy splits each character with a wild card. Searching
for =”for”= returns all =”f.*o.*r”= matches, resulting in a large
number of hits. Yet some searches need these extra hits. Ivy sorts
such large lists using
flx package’s scoring mechanism, if it’s
C-o m toggles the current regexp builder.
- Highlights the currently selected candidate.
- Highlights the background of the match.
- Highlights the first (modulo 3) matched group.
- Highlights the second (modulo 3) matched group.
- Highlights the third (modulo 3) matched group.
Highlights the “(confirm)” part of the prompt.
t, then confirming non-existent files in
ivy-moderequires an additional
The confirmation prompt will use this face.
(setq confirm-nonexistent-file-or-buffer t)
find-file, enter “eldorado” and press
RET- the prompt will be appended with “(confirm)”. Press
RETonce more to confirm, or any key to continue the completion.
Highlights the “(match required)” part of the prompt.
When completions have to match available candidates and cannot take random input, the “(match required)” prompt signals this constraint.
For example, call
describe-variable, enter “waldo” and press
RET- “(match required)” is prompted. Press any key for the prompt to disappear.
- Highlights directories when completing file names.
- Highlights remote files when completing file names.
Highlights virtual buffers when completing buffer names.
Virtual buffers correspond to bookmarks and recent files list,
Enable virtual buffers with:
(setq ivy-use-virtual-buffers t)
- User Option
A string that specifies display of number of candidates and
current candidate, if one exists.
The number of matching candidates by default is shown as a right- padded integer value.
To disable showing the number of candidates:
(setq ivy-count-format "")
To also display the current candidate:
(setq ivy-count-format "(%d/%d) ")
format-style switches this variable uses are described in the
- User Option
Specifies highlighting candidates in the minibuffer.
The default setting is =’fancy= and valid only in Emacs versions 24.5 or newer.
nilfor a plain minibuffer.
- User Option
Specify what when
The default behavior is to quit the completion after
DEL– a handy key to invoke after mistakenly triggering a completion.
An action is a function that is called after you select a candidate during completion. This function takes a single string argument, which is the selected candidate. What are actions?
- Window context when calling an action
Currently, the action is executed in the minibuffer window
context. This means e.g. that if you call
insertthe text will be inserted into the minibuffer.
If you want to execute the action in the initial window from which the completion started, use the
(defun ivy-insert-action (x) (with-ivy-window (insert x)))
How can different actions be called?
ivy-done) calls the current action.
ivy-dispatching-done) presents available actions for selection, calls it after selection, and then exits.
ivy-dispatching-call) presents available actions for selection, calls it after selection, and then does not exit.
Currently, you can append any amount of your own actions to the default list of actions. This can be done either for a specific command, or for all commands at once. How to modify the actions list?
Usually, the command has only one default action. The convention is to
use single letters when selecting a command, and the letter
designated for the default command. This way,
M-o o should be always
The first action inserts the current candidate into the Ivy window - the window from which Example - add two actions to each command
The second action copies the current candidate to the kill ring.
(defun ivy-yank-action (x) (kill-new x)) (defun ivy-copy-to-buffer-action (x) (with-ivy-window (insert x))) (ivy-set-actions t '(("i" ivy-copy-to-buffer-action "insert") ("y" ivy-yank-action "yank")))
Then in any completion session,
M-o y invokes
M-o i invokes
Since How to undo adding the two actions
ivy-set-actionsmodifies the internal dictionary with new data, set the extra actions list to
nilvalue to the
tkey as follows:
(ivy-set-actions t nil)
Use the command name as the key: How to add actions to a specific command
(ivy-set-actions 'swiper '(("i" ivy-copy-to-buffer-action "insert") ("y" ivy-yank-action "yank")))
Example - define a new command with several actions
(defun my-action-1 (x) (message "action-1: %s" x)) (defun my-action-2 (x) (message "action-2: %s" x)) (defun my-action-3 (x) (message "action-3: %s" x)) (defun my-command-with-3-actions () (interactive) (ivy-read "test: " '("foo" "bar" "baz") :action '(1 ("o" my-action-1 "action 1") ("j" my-action-2 "action 2") ("k" my-action-3 "action 3"))))
The number 1 above is the index of the default action. Each action has its own string description for easy selection.
To examine each action with each candidate in a key-efficient way, try:
Test the above function with
C-c C-oto close the completion window and move to an ivy-occur buffer
kkkto move to the first candidate, since the point is most likely at the end of the buffer
ooto call the first action
okto call the second and the third actions
jto move to the next candidate
jto move to the next candidate
- and so on…
org-modeversions 8.3.3 or later obey
ivy-modesets). Try refiling headings with similar names to appreciate
Magit requires this setting for ivy completion:
(setq magit-completing-read-function 'ivy-completing-read)
- It uses ivy by default if Ivy is installed.
Projectile requires this setting for ivy completion:
(setq projectile-completion-system 'ivy)
Helm-make requires this setting for ivy completion.
(setq helm-make-completion-method 'ivy)
Since file name completion is ubiquitous, Ivy provides extra bindings that work here: File Name Completion
On a directory, restarts completion from that directory.
On a file or
./, exit completion with the selected candidate.
- Restart the completion in the parent directory if current input is empty.
- Switch to the root directory.
- ~~~ (
- Switch to the home directory.
- If the current input matches an existing directory name exactly, switch the completion to that directory.
Toggle between input as regexp or not.
Switch to matching literally since file names include
., which is for matching any char in regexp mode.
- User Option
Decide if you want to see
./during file name completion.
Reason to remove:
../is the same as
Reason not to remove: navigate anywhere with only
./can be removed.
- Using TRAMP
From any directory, with the empty input, inputting
RET, which is the same thing) completes for host and user names.
/ssh:user@input, completes the domain name.
C-iworks in a similar way to the default completion.
You can also get sudo access for the current directory by inputting
/sudo:(i.e. single colon instead of double) will result in a completion session for the desired user.
File history works the same with
C-r, but uses a custom code for file name completion that cycles through files previously opened. It also works with TRAMP files.
Buffer Name Completion
- User Option
When non-nil, add
recentf-modeand bookmarks to
Adding this to Emacs init file:
(setq ivy-use-virtual-buffers t)
will add additional virtual buffers to the buffers list for recent files. Selecting such virtual buffers, which are highlighted with
ivy-virtualface, will open the corresponding file.
The main advantages of Counsel commands
counsel-functions over their basic equivalents in
- Multi-actions and non-exiting actions work.
ivy-resumecan resume the last completion session.
- Customize individual keymaps, such as
counsel-find-file-map, instead of customizing
ivy-minibuffer-mapthat applies to all completion sessions.
The main (and only) entry point is the API
ivy-readfunction. It takes two required arguments and many optional arguments that can be passed by a key. The optional
:actionargument is highly recommended for features such as multi-actions, non-exiting actions,
Required arguments for
A format string normally ending in a colon and a space.
%danywhere in the string is replaced by the current number of matching candidates. To use a literal
%character, escape it as
%%. See also
Either a list of strings, a function, an alist or a hash table.
If a function, then it has to be compatible with
Optional arguments for
Is a function to filter the initial collection. It has to be
all-completions. Tip: most of the time, it’s simpler to just apply this filter to the
collectionargument itself, e.g.
(cl-remove-if-not predicate collection).
- When set to a non-nil value, input must match one of the candidates. Custom input is not accepted.
This string argument is included for compatibility with
completing-read, which inserts it into the minibuffer.
It’s recommended to use the
preselectargument instead of this.
Name of the symbol to store history. See
When set to a string value, select the first candidate matching
When set to an integer value, select the candidate with that index value.
Every time the input becomes empty, the item corresponding to to
A keymap to be composed with
ivy-minibuffer-map. This keymap has priority over
ivy-minibuffer-mapand can be modified at any later stage.
Is the function called each time the current candidate changes.
This function takes no arguments and is called in the
swiperfor an example usage.
When non-nil, use
ivy-sort-functions-alistto sort the collection as long as the collection is not larger than
- Is the function to call after selection. It takes a string argument.
Is the function to call before exiting completion. It takes no
arguments. This function is called even if the completion is
swiperfor an example usage.
Is a function that takes a string and returns a valid regex. See
Completion Stylesfor details.
Is a function that takes a regex string and a list of strings and
returns a list of strings matching the regex. Any ordinary Emacs
matching function will suffice, yet finely tuned matching
functions can be used. See
counsel-find-filefor an example usage.
collectionwill be used to dynamically generate the candidates each time the input changes, instead of being used once statically with
all-completionsto generate a list of strings. See
counsel-locatefor an example usage.
Is a symbol that uniquely identifies the function that called
ivy-read, which may be useful for further customizations.
This is a typical example of a function with a non-async collection,
which is a collection where all the strings in the collection are
known prior to any input from the user.
Only the first two arguments (along with
action) are essential - the
rest of the arguments are for fine-tuning, and could be omitted.
action argument could also be omitted - but then
would do nothing except returning the string result, which you could
later use yourself. However, it’s recommended that you use the
(defun counsel-describe-function () "Forward to `describe-function'." (interactive) (ivy-read "Describe function: " (let (cands) (mapatoms (lambda (x) (when (fboundp x) (push (symbol-name x) cands)))) cands) :keymap counsel-describe-map :preselect (counsel-symbol-at-point) :history 'counsel-describe-symbol-history :require-match t :sort t :action (lambda (x) (describe-function (intern x))) :caller 'counsel-describe-function))
Here are the interesting features of the above function, in the order that they appear:
promptargument is a simple string ending in “: “.
collectionargument evaluates to a (large) list of strings.
keymapargument is for a custom keymap to supplement
preselectis provided by
counsel-symbol-at-point, which returns a symbol near the point. Ivy then selects the first candidate from the collection that matches this symbol. To select this pre-selected candidate, a
RETwill suffice. No further user input is necessary.
historyargument is for keeping the history of this command separate from the common history in
require-matchis set to
tsince it doesn’t make sense to call
describe-functionon an un-interned symbol.
sortargument is set to
tso choosing between similar candidates becomes easier. Sometimes, the collection size will exceed
ivy-sort-max-size, which is 30000 by default. In that case the sorting will not happen to avoid delays.
Adjust this variable to choose between sorting time and completion start-up time.
describe-functionon the interned selected candidate.
callerargument identifies this completion session. This is important, since with the collection being a list of strings and not a function name, the only other way for
ivy-readto identify “who’s calling” and to apply the appropriate customizations is to examine
this-commandwould be modified if another command called
This is a typical example of a function with an async collection.
Since the collection function cannot pre-compute all the locatable
files in memory within reasonable limits (time or memory), it relies
on user input to filter the universe of possible candidates to a
manageable size while also continuing to search asynchronously for
possible candidates. Both the filtering and searching continues with
each character change of the input with rapid updates to the
collection presented without idle waiting times. This live update will
continue as long as there are likely candidates. Eventually updates to
the minibuffer will stop after user input, filtering, and searching
have exhausted looking for possible candidates.
Async collections suit long-running shell commands, such as
With each new input, a new process starts while the old process is
killed. The collection is refreshed anew with each new process.
Meanwhile the user can provide more input characters (for further
narrowing) or select a candidate from the visible collection.
(defun counsel-locate-function (str) (if (< (length str) 3) (counsel-more-chars 3) (counsel--async-command (format "locate %s '%s'" (mapconcat #'identity counsel-locate-options " ") (counsel-unquote-regex-parens (ivy--regex str)))) '("" "working..."))) ;;;###autoload (defun counsel-locate (&optional initial-input) "Call the \"locate\" shell command. INITIAL-INPUT can be given as the initial minibuffer input." (interactive) (ivy-read "Locate: " #'counsel-locate-function :initial-input initial-input :dynamic-collection t :history 'counsel-locate-history :action (lambda (file) (with-ivy-window (when file (find-file file)))) :unwind #'counsel-delete-process :caller 'counsel-locate))
Here are the interesting features of the above functions, in the order that they appear:
counsel-locate-functiontakes a string argument and returns a list of strings. Note that it’s not compatible with
all-completions, but since we’re not using that here, might as well use one argument instead of three.
counsel-more-charsis a simple function that returns e.g. =’(“2 chars more”)= asking the user for more input.
counsel--async-commandis a very easy API simplification that takes a single string argument suitable for
shell-command-to-string. So you could prototype your function as non-async using
split-stringto produce a collection, then decide that you want async and simply swap in
counsel-locateis an interactive function with an optional
#'counsel-locate-functionis passed as the
dynamic-collectionis set to t, since this is an async collection.
with-ivy-windowwrapper, since we want to open the selected file in the same window from which
unwindargument is set to
#'counsel-delete-process: when we press
C-gwe want to kill the running process created by
callerargument identifies this command for easier customization.
This is another example to show how to associate additional values to each
(defun find-candidates-function (str pred _) (let ((props '(1 2)) (strs '("foo" "foo2"))) (cl-mapcar (lambda (s p) (propertize s 'property p)) strs props))) (defun find-candidates () (interactive) (ivy-read "Find symbols: " #'find-candidates-function :action (lambda (x) (message "Value: %s" (get-text-property 0 'property x) ))))
Here are the interesting features of the above function:
find-candidates-functionbuilds up a list of strings and associates “foo” with the value 1 and “foo2” with 2.
find-candidatesis an interactive function.
#'find-candidatesis passed as the
actiongets passed the selected string with the associated value. It then retrieves that value and displays it.