Next: Introduction [Contents][Index]
Next: Installation, Previous: Ivy User Manual, Up: Ivy User Manual [Contents][Index]
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.
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-height
to 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
fundamental-mode
as possible. SPC inserts a space, for example, instead of being bound to the more complexminibuffer-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 theivy-current-match
face (seeivy-format-functions-alist
). Or take the customization of actions, say after the candidate function is selected. RET usescounsel-describe-function
to describe the function, whereas M-o d jumps to that function’s definition in the code. The M-o prefix can be uniformly used with characters like d to group similar actions.
Ivy displays easily discoverable commands through the hydra facility. C-o in 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-o in the minibuffer while in the midst of the Ivy interaction. This discoverability minimizes exiting Ivy interface for documentation look-ups.
Next: Getting started, Previous: Introduction, Up: Ivy User Manual [Contents][Index]
Install Ivy automatically through Emacs’s package manager, or manually from Ivy’s development repository.
Emacs 24.5 is the oldest version to run Ivy.
Next: Installing from the Git repository, Up: Installation [Contents][Index]
M-x package-install
RET counsel
RET
Ivy is installed alongside the counsel
package, which is available
from two different package archives, GNU ELPA and MELPA. For the
latest stable version, use the GNU ELPA archive. For the latest
development snaphshot, use the GNU-devel ELPA archive.
Ivy is split into three packages: ivy
, swiper
and counsel
; by
installing counsel
, the other two are brought in as dependencies.
If you are not interested in the extra functionality provided by
swiper
and counsel
, you can install only ivy
.
See the code below for adding GNU-devel ELPA to your list of package archives:
(require 'package) (add-to-list 'package-archives '("gnu-devel" . "https://elpa.gnu.org/devel/"))
After this do M-x package-refresh-contents
RET, followed by M-x
package-install
RET counsel
RET.
For package manager details, see (emacs)Packages.
Previous: Installing from Emacs Package Manager, Up: Installation [Contents][Index]
- No need to wait for GNU ELPA / MELPA builds
- Easy to revert to previous versions
- Contribute to Ivy’s development; send patches; pull requests
First clone the Swiper repository with:
cd ~/git && git clone https://github.com/abo-abo/swiper cd swiper && make compileSecond, 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
Next: Key bindings, Previous: Installation, Up: Ivy User Manual [Contents][Index]
First enable Ivy completion everywhere:
(ivy-mode 1)
Note: ivy-mode
can be toggled on and off with M-x ivy-mode
.
Up: Getting started [Contents][Index]
Here are some basic settings particularly useful for new Ivy users:
(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 M-x describe-variable
documentation.
Next: Completion Styles, Previous: Getting started, Up: Ivy User Manual [Contents][Index]
Next: Minibuffer key bindings, Up: Key bindings [Contents][Index]
Here is a list of commands that are useful to be bound globally, along with some sample bindings:
(global-set-key (kbd "C-s") 'swiper-isearch) (global-set-key (kbd "M-x") 'counsel-M-x) (global-set-key (kbd "C-x C-f") 'counsel-find-file) (global-set-key (kbd "M-y") 'counsel-yank-pop) (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) (global-set-key (kbd "<f2> j") 'counsel-set-variable) (global-set-key (kbd "C-x b") 'ivy-switch-buffer) (global-set-key (kbd "C-c v") 'ivy-push-view) (global-set-key (kbd "C-c V") 'ivy-pop-view)
(global-set-key (kbd "C-c c") 'counsel-compile) (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 L") 'counsel-git-log) (global-set-key (kbd "C-c k") 'counsel-rg) (global-set-key (kbd "C-c m") 'counsel-linux-app) (global-set-key (kbd "C-c n") 'counsel-fzf) (global-set-key (kbd "C-x l") 'counsel-locate) (global-set-key (kbd "C-c J") 'counsel-file-jump) (global-set-key (kbd "C-S-o") 'counsel-rhythmbox) (global-set-key (kbd "C-c w") 'counsel-wmctrl)
ivy-resume
resumes the last Ivy-based completion.(global-set-key (kbd "C-c C-r") 'ivy-resume) (global-set-key (kbd "C-c b") 'counsel-bookmark) (global-set-key (kbd "C-c d") 'counsel-descbinds) (global-set-key (kbd "C-c g") 'counsel-git) (global-set-key (kbd "C-c o") 'counsel-outline) (global-set-key (kbd "C-c t") 'counsel-load-theme) (global-set-key (kbd "C-c F") 'counsel-org-file)
You can also enable counsel-mode
to make some global key binding remapping for you.
Previous: Global key bindings, Up: Key bindings [Contents][Index]
Ivy includes several minibuffer bindings, which are defined in the
ivy-minibuffer-map
keymap variable. The most frequently used ones
are described here.
swiper
or counsel-M-x
add more key bindings through the keymap
argument to 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-a, C-f, M-d, M-DEL, M-b, M-w, C-k,
C-y key bindings work the same as in fundamental-mode
.
Next: Key bindings for multiple selections and actions, keep minibuffer open, Previous: Key bindings for navigation, Up: Minibuffer key bindings [Contents][Index]
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.
ivy-done
)Calls the default action and then exits the minibuffer.
ivy-dispatching-done
)Presents valid actions from which to choose. When only one action is available, there is no difference between M-o and C-m.
ivy-alt-done
)When completing file names, selects the current directory candidate and starts a new completion session there. Otherwise, it is the same as
ivy-done
.
ivy-partial-or-done
)Attempts partial completion, extending current input as much as possible. TAB TAB is the same as C-j (
ivy-alt-done
).Example ERT test:
(should (equal (ivy-with '(progn (ivy-read "Test: " '("can do" "can't, sorry" "other")) ivy-text) "c <tab>") "can"))
ivy-immediate-done
)Exits with the current input instead of the current candidate (like other commands).
This is useful e.g. when you call
find-file
to create a new file, but the desired name matches an existing file. In that case, using C-j would select that existing file, which isn’t what you want - use this command instead.
ivy-avy
)Uses avy to select one of the candidates on the current candidate page. This can often be faster than multiple C-n or C-p keystrokes followed by C-m.
Next: Key bindings that alter the minibuffer input, Previous: Key bindings for single selection, action, then exit minibuffer, Up: Minibuffer key bindings [Contents][Index]
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.
Note that these operations are supported only by completion sessions
that use the ivy-read
API, rather than the built-in
completing-read
.
ivy-call
)Is the non-exiting version of C-m (
ivy-done
).Instead of closing the minibuffer, C-M-m allows selecting another candidate or another action. For example, C-M-m on functions list invokes
describe-function
. When combined with C-n, function descriptions can be invoked quickly in succession.
ivy-dispatching-call
)Is the non-exiting version of M-o (
ivy-dispatching-done
).For example, during the
counsel-rhythmbox
completion, press C-M-o e to en-queue the selected candidate, followed by C-n C-m to play the next candidate - the current action reverts to the default one after C-M-o.
ivy-next-line-and-call
)Combines C-n and C-M-m. Moves to next line and applies an action.
Comes in handy when opening multiple files from
counsel-find-file
,counsel-git-grep
,counsel-ag
,counsel-rg
, orcounsel-locate
lists. Just hold C-M-n for rapid-fire default action on each successive element of the list.
ivy-previous-line-and-call
)Combines C-p and C-M-m.
Similar to the above except it moves through the list in the other direction.
ivy-resume
Recalls the state of the completion session just before its last exit.
Useful after an accidental C-m (
ivy-done
). Use it withuniversal-argument
to resume any previous session.
Next: Other key bindings, Previous: Key bindings for multiple selections and actions, keep minibuffer open, Up: Minibuffer key bindings [Contents][Index]
ivy-next-history-element
)Cycles forward through the Ivy command history.
Ivy updates an internal history list after each action. When this history list is empty, M-n inserts symbol (or URL) at point into the minibuffer.
ivy-previous-history-element
)Cycles backwards through the Ivy command history.
ivy-insert-current
)Inserts the current candidate into the minibuffer.
Useful for copying and renaming files, for example: M-i to insert the original file name string, edit it, and then C-m to complete the renaming.
ivy-yank-word
)Inserts the sub-word at point into the minibuffer.
This is similar to C-s C-w with
isearch
. Ivy reserves C-w forkill-region
. See alsoivy-yank-symbol
andivy-yank-char
.
ivy-restrict-to-matches
)Deletes the current input, and resets the candidates list to the currently restricted matches.
This is how Ivy provides narrowing in successive tiers.
ivy-reverse-i-search
)Starts a recursive completion session through the command’s history.
This works just like C-r at the bash command prompt, where the completion candidates are the history items. Upon completion, the selected candidate string is inserted into the minibuffer.
Next: Hydra in the minibuffer, Previous: Key bindings that alter the minibuffer input, Up: Minibuffer key bindings [Contents][Index]
ivy-kill-ring-save
)Copies selected candidates to the kill ring.
Copies the region if the region is active.
Next: Saving the current completion session to a buffer, Previous: Other key bindings, Up: Minibuffer key bindings [Contents][Index]
hydra-ivy/body
)Invokes the hydra menu with short key bindings.
When Hydra is active, minibuffer editing is disabled and menus display short aliases:
Short | Normal | Command name |
---|---|---|
o | C-g | keyboard-escape-quit |
j | C-n | ivy-next-line |
k | C-p | ivy-previous-line |
h | M-< | ivy-beginning-of-buffer |
l | M-> | ivy-end-of-buffer |
d | C-m | ivy-done |
f | C-j | ivy-alt-done |
g | C-M-m | ivy-call |
u | C-c C-o | ivy-occur |
Hydra reduces key strokes, for example: C-n C-n C-n C-n is C-o jjjj in Hydra.
Hydra menu offers these additional bindings:
ivy-toggle-calling
)Toggle calling the action after each candidate change. It modifies j to jg, k to kg etc.
ivy-rotate-preferred-builders
)Rotate the current regexp matcher.
ivy-minibuffer-grow
)Increase
ivy-height
for the current minibuffer.
ivy-minibuffer-shrink
)Decrease
ivy-height
for the current minibuffer.
ivy-prev-action
)Select the previous action.
ivy-next-action
)Select the next action.
ivy-read-action
)Use a menu to select an action.
ivy-toggle-case-fold
)Toggle case folding (match both upper and lower case characters for lower case input).
Hydra menu also offers bindings for marking multiple candidates:
Key | Command name |
---|---|
m | ivy-mark |
u | ivy-unmark |
DEL | ivy-unmark-backward |
t | ivy-toggle-marks |
The action is called on each marked candidate one by one.
Previous: Hydra in the minibuffer, Up: Minibuffer key bindings [Contents][Index]
ivy-occur
)Saves the current candidates to a new buffer and exits completion.
The new buffer is read-only and has a few useful bindings defined.
ivy-occur-press
)Call the current action on the selected candidate.
ivy-occur-click
)Call the current action on the selected candidate.
next-line
)Move to next line.
previous-line
)Move to previous line.
ivy-occur-read-action
)Read an action and make it current for this buffer.
ivy-occur-dispatch
)Read an action and call it on the selected candidate.
quit-window
)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-occur counsel-describe-variable
"function$*
.
Next: Customization, Previous: Key bindings, Up: Ivy User Manual [Contents][Index]
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 ivy-re-builders-alist
.
The keys of this alist are collection names, and the values are one of the following:
ivy--regex
ivy--regex-plus
ivy--regex-ignore-order
ivy--regex-fuzzy
regexp-quote
A catch-all key, t
, applies to all collections that don’t have their
own key.
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)))
Here, 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-builder
argument passed to ivy-read
.
collection
argument passed to ivy-read
is a function and has an
entry on ivy-re-builders-alist
.
caller
argument passed to ivy-read
has an entry on
ivy-re-builders-alist
.
this-command
has an entry on ivy-re-builders-alist
.
t
has an entry on ivy-re-builders-alist
.
ivy--regex
.
Next: ivy–regex-ignore-order, Up: Completion Styles [Contents][Index]
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
"\\(for\\).*\\(example\\)"
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.
Next: ivy–regex-fuzzy, Previous: ivy–regex-plus, Up: Completion Styles [Contents][Index]
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"
.
Previous: ivy–regex-ignore-order, Up: Completion Styles [Contents][Index]
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
installed.
C-o m toggles the current regexp builder.
Next: Commands, Previous: Completion Styles, Up: Ivy User Manual [Contents][Index]
Next: Defcustoms, Up: Customization [Contents][Index]
ivy-current-match
Highlights the currently selected candidate.
ivy-minibuffer-match-face-1
Highlights the background of the match.
ivy-minibuffer-match-face-2
Highlights the first (modulo 3) matched group.
ivy-minibuffer-match-face-3
Highlights the second (modulo 3) matched group.
ivy-minibuffer-match-face-4
Highlights the third (modulo 3) matched group.
ivy-confirm-face
Highlights the "(confirm)" part of the prompt.
When
confirm-nonexistent-file-or-buffer
set tot
, then confirming non-existent files inivy-mode
requires an additional RET.The confirmation prompt will use this face.
For example:
(setq confirm-nonexistent-file-or-buffer t)Then call
find-file
, enter "eldorado" and press RET - the prompt will be appended with "(confirm)". Press RET once more to confirm, or any key to continue the completion.
ivy-match-required-face
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.
ivy-subdir
Highlights directories when completing file names.
ivy-remote
Highlights remote files when completing file names.
ivy-virtual
Highlights virtual buffers when completing buffer names.
Virtual buffers correspond to bookmarks and recent files list,
recentf
.Enable virtual buffers with:
(setq ivy-use-virtual-buffers t)
ivy-modified-buffer
Highlights modified buffers when switching buffer.
ivy-modified-outside-buffer
Highlights buffers modified outside Emacs when switching buffer.
This takes precedence over
ivy-modified-buffer
.
Next: Actions, Previous: Faces, Up: Customization [Contents][Index]
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) ")
The format
-style switches this variable uses are described
in the format
documentation.
Specifies highlighting candidates in the minibuffer.
The default setting is fancy
.
Set ivy-display-style
to nil
for a plain minibuffer.
Specifies what to do when DEL (ivy-backward-delete-char
) fails.
This is usually the case when there is no text left to delete, i.e., when DEL is typed at the beginning of the minibuffer.
The default behavior is to quit the completion after DEL – a handy key to invoke after mistakenly triggering a completion.
Another common option is ignore
, which does nothing.
Next: Packages, Previous: Defcustoms, Up: Customization [Contents][Index]
Next: How can different actions be called?, Up: Actions [Contents][Index]
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.
Currently, the action is executed in the minibuffer window context. This means e.g. that if you call
insert
the 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
with-ivy-window
wrapper macro.(defun ivy-insert-action (x) (with-ivy-window (insert x)))
Next: How to modify the actions list?, Previous: What are actions?, Up: Actions [Contents][Index]
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.
Next: Example - add two actions to each command, Previous: How can different actions be called?, Up: Actions [Contents][Index]
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.
Usually, the command has only one default action. The convention is to use single letters when selecting a command, and the letter o is designated for the default command. This way, M-o o should be always equivalent to C-m.
Next: Example - define a new command with several actions, Previous: How to modify the actions list?, Up: Actions [Contents][Index]
The first action inserts the current candidate into the Ivy window -
the window from which ivy-read
was called.
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 ivy-yank-action
, and
M-o i invokes ivy-copy-to-buffer-action
.
Next: How to add actions to a specific command, Up: Example - add two actions to each command [Contents][Index]
Since ivy-set-actions
modifies the internal dictionary with new
data, set the extra actions list to nil
by assigning nil
value to
the t
key as follows:
(ivy-set-actions t nil)
Previous: How to undo adding the two actions, Up: Example - add two actions to each command [Contents][Index]
Use the command name as the key:
(ivy-set-actions 'swiper '(("i" ivy-copy-to-buffer-action "insert") ("y" ivy-yank-action "yank")))
Previous: Example - add two actions to each command, Up: Actions [Contents][Index]
(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.
ivy-occur
To examine each action with each candidate in a key-efficient way, try:
my-command-with-3-actions
Previous: Actions, Up: Customization [Contents][Index]
org-mode
org-mode
versions 8.3.3 or later obeycompleting-read-function
(whichivy-mode
sets). Try refiling headings with similar names to appreciateivy-mode
.
magit
Uses ivy by default if Ivy is installed.
find-file-in-project
Uses ivy by default if Ivy is installed.
projectile
Projectile requires this setting for ivy completion:
(setq projectile-completion-system 'ivy)
helm-make
Helm-make requires this setting for ivy completion.
(setq helm-make-completion-method 'ivy)
Ivy re-uses the following packages if they are installed:
avy
,amx
orsmex
,flx
, andwgrep
.
Next: API, Previous: Customization, Up: Ivy User Manual [Contents][Index]
Next: Buffer Name Completion, Up: Commands [Contents][Index]
Since file name completion is ubiquitous, Ivy provides extra bindings that work here:
ivy-alt-done
)On a directory, restarts completion from that directory.
On a file or
./
, exit completion with the selected candidate.
ivy-backward-delete-char
)Restart the completion in the parent directory if current input is empty.
self-insert-command
)Switch to the root directory.
self-insert-command
)Switch to the home directory.
self-insert-command
)If the current input matches an existing directory name exactly, switch the completion to that directory.
ivy-insert-current-full
)Insert the current full path, in case you want to edit a part of it.
ivy-toggle-regexp-quote
)Toggle between input as regexp or not.
Switch to matching literally since file names include
.
, which is for matching any char in regexp mode.
Decide if you want to see ../
and ./
during file name
completion.
Reason to remove: ../
is the same as DEL.
Reason not to remove: navigate anywhere with only C-n, C-p and C-j.
Likewise, ./
can be removed.
File history works the same with M-p, M-n, and C-r, but uses a custom code for file name completion that cycles through files previously opened. It also works with TRAMP files.
Up: File Name Completion [Contents][Index]
Move to the home directory. Either the local or the remote one, depending on the current directory. The boolean option
ivy-magic-tilde
decides whether the binding to do this is ~ or ~/.
Move to the root directory. Either the local or the remote one, depending on the current directory. Here, you can also select a TRAMP connection method, such as
ssh
orscpx
.
Move the the local root directory.
Move to the local home directory.
From any directory, with the empty input, inputting /ssh:
and pressing
C-j (or RET, which is the same thing) completes for host and user
names.
For /ssh:user@
input, completes the domain name.
C-i works in a similar way to the default completion.
You can also get sudo access for the current directory by inputting
/sudo::
RET. Using /sudo:
(i.e. single colon instead of double) will
result in a completion session for the desired user.
Multi-hopping is possible, although a bit complex.
cloud
and open a file with sudo
there
- C-x C-f
/ssh:cloud|sudo:root:/
.
Next: Counsel commands, Previous: File Name Completion, Up: Commands [Contents][Index]
When non-nil, add recentf-mode
and bookmarks to
ivy-switch-buffer
completion candidates.
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-virtual
face, will open the corresponding file.
Previous: Buffer Name Completion, Up: Commands [Contents][Index]
The main advantages of counsel-
functions over their basic
equivalents in ivy-mode
are:
ivy-resume
can resume the last completion session.
ivy-set-actions
, ivy-re-builders-alist
.
counsel-describe-map
,
counsel-git-grep-map
, or counsel-find-file-map
, instead of
customizing ivy-minibuffer-map
that applies to all completion
sessions.
Next: Variable Index, Previous: Commands, Up: Ivy User Manual [Contents][Index]
The main (and only) entry point is the ivy-read
function. It takes
two required arguments and many optional arguments that can be passed
by a key. The optional :action
argument is highly recommended for
features such as multi-actions, non-exiting actions, ivy-occur
and
ivy-resume
.
ivy-read
ivy-read
counsel-describe-function
counsel-locate
ivy-read-with-extra-properties
Next: Optional arguments for ivy-read
, Up: API [Contents][Index]
ivy-read
prompt
A prompt string normally ending in a colon and a space.
ivy-count-format
is prepended to it during completion.
collection
Either a list of strings, a function, an alist or a hash table.
If a function, then it has to be compatible with
all-completions
.
Next: Example - counsel-describe-function
, Previous: Required arguments for ivy-read
, Up: API [Contents][Index]
ivy-read
predicate
Is a function to filter the initial collection. It has to be compatible with
all-completions
. Tip: most of the time, it’s simpler to just apply this filter to thecollection
argument itself, e.g.(cl-remove-if-not predicate collection)
.
require-match
When set to a non-nil value, input must match one of the candidates. Custom input is not accepted.
initial-input
This string argument is included for compatibility with
completing-read
, which inserts it into the minibuffer.It’s recommended to use the
preselect
argument instead of this.
history
Name of the symbol to store history. See
completing-read
.
preselect
Determines which one of the candidates to initially select.
When set to an integer value, select the candidate with that index value.
When set to any other non-nil value, select the first candidate matching this value. Comparison is first done with
equal
. If this fails, and when applicable, matchpreselect
as a regular expression.Every time the input becomes empty, the item corresponding to
preselect
is selected.
keymap
A keymap to be composed with
ivy-minibuffer-map
. This keymap has priority overivy-minibuffer-map
and can be modified at any later stage.
update-fn
Is the function called each time the current candidate changes. This function takes no arguments and is called in the minibuffer’s
post-command-hook
. Seeswiper
for an example usage.
sort
When non-nil, use
ivy-sort-functions-alist
to sort the collection as long as the collection is not larger thanivy-sort-max-size
.
action
Is the function to call after selection. It takes a string argument.
unwind
Is the function to call before exiting completion. It takes no arguments. This function is called even if the completion is interrupted with C-g. See
swiper
for an example usage.
re-builder
Is a function that takes a string and returns a valid regex. See
Completion Styles
for details.
matcher
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-file
for an example usage.
dynamic-collection
When non-nil,
collection
will be used to dynamically generate the candidates each time the input changes, instead of being used once statically withall-completions
to generate a list of strings. Seecounsel-locate
for an example usage.
caller
Is a symbol that uniquely identifies the function that called
ivy-read
, which may be useful for further customizations.
Next: Example - counsel-locate
, Previous: Optional arguments for ivy-read
, Up: API [Contents][Index]
counsel-describe-function
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.
The action
argument could also be omitted - but then ivy-read
would do nothing except returning the string result, which you could
later use yourself. However, it’s recommended that you use the
action
argument.
(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 (ivy-thing-at-point) :history 'counsel-describe-symbol-history :require-match 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:
prompt
argument is a simple string ending in ": ".
collection
argument evaluates to a (large) list of strings.
keymap
argument is for a custom keymap to supplement ivy-minibuffer-map
.
preselect
is provided by ivy-thing-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 RET will suffice. No further user
input is necessary.
history
argument is for keeping the history of this command
separate from the common history in ivy-history
.
require-match
is set to t
since it doesn’t make sense to
call describe-function
on an un-interned symbol.
action
argument calls describe-function
on the interned
selected candidate.
caller
argument 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-read
to identify
"who’s calling" and to apply the appropriate customizations is to
examine this-command
. But this-command
would be modified if
another command called counsel-describe-function
.
Next: Example - ivy-read-with-extra-properties
, Previous: Example - counsel-describe-function
, Up: API [Contents][Index]
counsel-locate
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 locate
.
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) (or (ivy-more-chars) (progn (counsel--async-command (format "locate %s '%s'" (mapconcat #'identity counsel-locate-options " ") (counsel--elisp-to-pcre (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-function
takes 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.
ivy-more-chars
is a simple function that returns e.g.
'("2 chars more")
asking the user for more input.
counsel--async-command
is 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 shell-command-to-string
and split-string
to
produce a collection, then decide that you want async and simply swap in
counsel--async-command
.
counsel-locate
is an interactive function with an optional initial-input
.
#'counsel-locate-function
is passed as the collection
argument.
dynamic-collection
is set to t, since this is an async collection.
action
argument uses with-ivy-window
wrapper, since we want to open the
selected file in the same window from which counsel-locate
was
called.
unwind
argument is set to #'counsel-delete-process
: when we press C-g
we want to kill the running process created by
counsel--async-command
.
caller
argument identifies this command for easier customization.
Previous: Example - counsel-locate
, Up: API [Contents][Index]
ivy-read-with-extra-properties
This is another example to show how to associate additional values to each displayed strings.
(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-function
builds up a list of strings and associates "foo" with
the value 1 and "foo2" with 2.
find-candidates
is an interactive function.
#'find-candidates
is passed as the collection
argument.
action
gets passed the selected string with the associated value. It
then retrieves that value and displays it.
Next: Keystroke Index, Previous: API, Up: Ivy User Manual [Contents][Index]
Jump to: | I |
---|
Jump to: | I |
---|
Previous: Variable Index, Up: Ivy User Manual [Contents][Index]
Jump to: | /
<
>
~
A C D F J K M O Q R S T W |
---|
Jump to: | /
<
>
~
A C D F J K M O Q R S T W |
---|