You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
938 lines
28 KiB
938 lines
28 KiB
This is /Users/leviolson/.emacs.d/straight/build/ivy/ivy.info, produced
|
|
by makeinfo version 4.8 from
|
|
/Users/leviolson/.emacs.d/straight/repos/swiper/doc/ivy.texi.
|
|
|
|
Ivy manual, version 0.13.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
|
|
active, `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-2019 Free Software Foundation, Inc.
|
|
|
|
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, no Front-Cover Texts, and
|
|
no Back-Cover Texts. A copy of the license is included in the
|
|
section entitled "GNU Free Documentation License".
|
|
|
|
INFO-DIR-SECTION Emacs
|
|
START-INFO-DIR-ENTRY
|
|
* Ivy: (ivy). Using Ivy for completion.
|
|
END-INFO-DIR-ENTRY
|
|
|
|
|
|
File: ivy.info, Node: Top, Next: Introduction, Up: (dir)
|
|
|
|
Ivy User Manual
|
|
***************
|
|
|
|
* Menu:
|
|
|
|
* Introduction::
|
|
* Installation::
|
|
* Getting started::
|
|
* Key bindings::
|
|
* Completion Styles::
|
|
* Customization::
|
|
* Commands::
|
|
* API::
|
|
* Variable Index::
|
|
* Keystroke Index::
|
|
|
|
--- The Detailed Node Listing ---
|
|
|
|
Installation
|
|
|
|
* Installing from Emacs Package Manager::
|
|
* Installing from the Git repository::
|
|
|
|
Getting started
|
|
|
|
* Basic customization::
|
|
|
|
Key bindings
|
|
|
|
* Global key bindings::
|
|
* Minibuffer key bindings::
|
|
|
|
Minibuffer key bindings
|
|
|
|
* Key bindings for navigation::
|
|
* Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
|
|
* Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
|
|
* Key bindings that alter the minibuffer input::
|
|
* Other key bindings::
|
|
* Hydra in the minibuffer::
|
|
* Saving the current completion session to a buffer::
|
|
|
|
Completion Styles
|
|
|
|
* ivy--regex-plus::
|
|
* ivy--regex-ignore-order::
|
|
* ivy--regex-fuzzy::
|
|
|
|
Customization
|
|
|
|
* Faces::
|
|
* Defcustoms::
|
|
* Actions::
|
|
* Packages::
|
|
|
|
Actions
|
|
|
|
* What are actions?::
|
|
* How can different actions be called?::
|
|
* How to modify the actions list?::
|
|
* Example - add two actions to each command::
|
|
* Example - define a new command with several actions::
|
|
|
|
Example - add two actions to each command
|
|
|
|
* How to undo adding the two actions::
|
|
* How to add actions to a specific command::
|
|
|
|
Example - define a new command with several actions
|
|
|
|
* Test the above function with `ivy-occur'::
|
|
|
|
Commands
|
|
|
|
* File Name Completion::
|
|
* Buffer Name Completion::
|
|
* Counsel commands::
|
|
|
|
File Name Completion
|
|
|
|
* Using TRAMP::
|
|
|
|
API
|
|
|
|
* Required arguments for `ivy-read'::
|
|
* Optional arguments for `ivy-read'::
|
|
* Example - `counsel-describe-function'::
|
|
* Example - `counsel-locate'::
|
|
* Example - `ivy-read-with-extra-properties'::
|
|
|
|
|
|
File: ivy.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top
|
|
|
|
1 Introduction
|
|
**************
|
|
|
|
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.
|
|
|
|
Minimalism
|
|
..........
|
|
|
|
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
|
|
..........
|
|
|
|
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 complex
|
|
`minibuffer-complete-word'. Ivy's code uses easy-to-examine global
|
|
variables; avoids needless complications with branch-introducing custom
|
|
macros.
|
|
|
|
Customizability
|
|
...............
|
|
|
|
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-current-match' face (see `ivy-format-functions-alist'). Or take
|
|
the customization of actions, say after the candidate function is
|
|
selected. `RET' uses `counsel-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.
|
|
|
|
Discoverability
|
|
...............
|
|
|
|
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.
|
|
|
|
|
|
File: ivy.info, Node: Installation, Next: Getting started, Prev: Introduction, Up: Top
|
|
|
|
2 Installation
|
|
**************
|
|
|
|
Install Ivy automatically through Emacs's package manager, or manually
|
|
from Ivy's development repository.
|
|
|
|
Emacs 24.3 is the oldest version to run Ivy. Emacs 24.4 is the oldest
|
|
version that runs Ivy with fancy faces display.
|
|
|
|
* Menu:
|
|
|
|
* Installing from Emacs Package Manager::
|
|
* Installing from the Git repository::
|
|
|
|
|
|
File: ivy.info, Node: Installing from Emacs Package Manager, Next: Installing from the Git repository, Up: Installation
|
|
|
|
2.1 Installing from Emacs Package Manager
|
|
=========================================
|
|
|
|
`M-x' `package-install' `RET' `ivy' `RET'
|
|
|
|
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: `ivy', `swiper' and `counsel'; you can simply
|
|
install `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" . "https://melpa.org/packages/"))
|
|
|
|
After this do `M-x' `package-refresh-contents' `RET', followed by
|
|
`M-x' `package-install' `RET' `counsel' `RET'.
|
|
|
|
For package manager details, see *Note Packages: (emacs)Packages.
|
|
|
|
|
|
File: ivy.info, Node: Installing from the Git repository, Prev: Installing from Emacs Package Manager, Up: Installation
|
|
|
|
2.2 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
|
|
|
|
|
|
File: ivy.info, Node: Getting started, Next: Key bindings, Prev: Installation, Up: Top
|
|
|
|
3 Getting started
|
|
*****************
|
|
|
|
First enable Ivy completion everywhere:
|
|
|
|
(ivy-mode 1)
|
|
|
|
Note: `ivy-mode' can be toggled on and off with `M-x' `ivy-mode'.
|
|
|
|
* Menu:
|
|
|
|
* Basic customization::
|
|
|
|
|
|
File: ivy.info, Node: Basic customization, Up: Getting started
|
|
|
|
3.1 Basic customization
|
|
=======================
|
|
|
|
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.
|
|
|
|
|
|
File: ivy.info, Node: Key bindings, Next: Completion Styles, Prev: Getting started, Up: Top
|
|
|
|
4 Key bindings
|
|
**************
|
|
|
|
* Menu:
|
|
|
|
* Global key bindings::
|
|
* Minibuffer key bindings::
|
|
|
|
|
|
File: ivy.info, Node: Global key bindings, Next: Minibuffer key bindings, Up: Key bindings
|
|
|
|
4.1 Global key bindings
|
|
=======================
|
|
|
|
Here is a list of commands that are useful to be bound globally, along
|
|
with some sample bindings:
|
|
|
|
Ivy-based interface to standard commands
|
|
........................................
|
|
|
|
(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)
|
|
|
|
Ivy-based interface to shell and system tools
|
|
.............................................
|
|
|
|
(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 and other commands
|
|
.............................
|
|
|
|
`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.
|
|
|
|
|
|
File: ivy.info, Node: Minibuffer key bindings, Prev: Global key bindings, Up: Key bindings
|
|
|
|
4.2 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.
|
|
|
|
`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'.
|
|
|
|
* Menu:
|
|
|
|
* Key bindings for navigation::
|
|
* Key bindings for single selection, action, then exit minibuffer: Key bindings for single selection action then exit minibuffer.
|
|
* Key bindings for multiple selections and actions, keep minibuffer open: Key bindings for multiple selections and actions keep minibuffer open.
|
|
* Key bindings that alter the minibuffer input::
|
|
* Other key bindings::
|
|
* Hydra in the minibuffer::
|
|
* Saving the current completion session to a buffer::
|
|
|
|
|
|
File: ivy.info, Node: Key bindings for navigation, Next: Key bindings for single selection action then exit minibuffer, Up: Minibuffer key bindings
|
|
|
|
4.2.1 Key bindings for navigation
|
|
---------------------------------
|
|
|
|
* `C-n' (`ivy-next-line') selects the next candidate
|
|
|
|
* `C-p' (`ivy-previous-line') selects the previous candidate
|
|
|
|
* `M-<' (`ivy-beginning-of-buffer') selects the first candidate
|
|
|
|
* `M->' (`ivy-end-of-buffer') selects the last candidate
|
|
|
|
* `C-v' (`ivy-scroll-up-command') scrolls up by `ivy-height' lines
|
|
|
|
* `M-v' (`ivy-scroll-down-command') scrolls down by `ivy-height'
|
|
lines
|
|
|
|
-- User Option: ivy-wrap
|
|
Specifies the wrap-around behavior for `C-n' and `C-p'. When
|
|
`ivy-wrap' is set to `t', `ivy-next-line' and `ivy-previous-line'
|
|
will cycle past the last and the first candidates respectively.
|
|
|
|
Wrap-around behavior is off by default.
|
|
|
|
-- User Option: ivy-height
|
|
Use this option to adjust the minibuffer height, which also
|
|
affects scroll size when using `C-v' and `M-v' key bindings.
|
|
|
|
`ivy-height' is 10 lines by default.
|
|
|
|
|
|
File: ivy.info, Node: Key bindings for single selection action then exit minibuffer, Next: Key bindings for multiple selections and actions keep minibuffer open, Prev: Key bindings for navigation, Up: Minibuffer key bindings
|
|
|
|
4.2.2 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.
|
|
|
|
`C-m' or `RET' (`ivy-done')
|
|
...........................
|
|
|
|
Calls the default action and then exits the minibuffer.
|
|
|
|
`M-o' (`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'.
|
|
|
|
`C-j' (`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'.
|
|
|
|
`TAB' (`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"))
|
|
|
|
`C-M-j' (`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.
|
|
|
|
`C-'' (`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'.
|
|
|
|
|
|
File: ivy.info, Node: Key bindings for multiple selections and actions keep minibuffer open, Next: Key bindings that alter the minibuffer input, Prev: Key bindings for single selection action then exit minibuffer, Up: Minibuffer key bindings
|
|
|
|
4.2.3 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.
|
|
|
|
`C-M-m' (`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.
|
|
|
|
`C-M-o' (`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'.
|
|
|
|
`C-M-n' (`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', or `counsel-locate'
|
|
lists. Just hold `C-M-n' for rapid-fire default action on each
|
|
successive element of the list.
|
|
|
|
`C-M-p' (`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').
|
|
|
|
|
|
File: ivy.info, Node: Key bindings that alter the minibuffer input, Next: Other key bindings, Prev: Key bindings for multiple selections and actions keep minibuffer open, Up: Minibuffer key bindings
|
|
|
|
4.2.4 Key bindings that alter the minibuffer input
|
|
--------------------------------------------------
|
|
|
|
`M-n' (`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.
|
|
|
|
`M-p' (`ivy-previous-history-element')
|
|
......................................
|
|
|
|
Cycles forward through the Ivy command history.
|
|
|
|
`M-i' (`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.
|
|
|
|
`M-j' (`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' for
|
|
`kill-region'. See also `ivy-yank-symbol' and `ivy-yank-char'.
|
|
|
|
`S-SPC' (`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.
|
|
|
|
`C-r' (`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.
|
|
|
|
|
|
File: ivy.info, Node: Other key bindings, Next: Hydra in the minibuffer, Prev: Key bindings that alter the minibuffer input, Up: Minibuffer key bindings
|
|
|
|
4.2.5 Other key bindings
|
|
------------------------
|
|
|
|
`M-w' (`ivy-kill-ring-save')
|
|
............................
|
|
|
|
Copies selected candidates to the kill ring.
|
|
|
|
Copies the region if the region is active.
|
|
|
|
|
|
File: ivy.info, Node: Hydra in the minibuffer, Next: Saving the current completion session to a buffer, Prev: Other key bindings, Up: Minibuffer key bindings
|
|
|
|
4.2.6 Hydra in the minibuffer
|
|
-----------------------------
|
|
|
|
`C-o' (`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:
|
|
|
|
`c' (`ivy-toggle-calling')
|
|
..........................
|
|
|
|
Toggle calling the action after each candidate change. It modifies `j'
|
|
to `jg', `k' to `kg' etc.
|
|
|
|
`m' (`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.
|
|
|
|
`w' (`ivy-prev-action')
|
|
.......................
|
|
|
|
Select the previous action.
|
|
|
|
`s' (`ivy-next-action')
|
|
.......................
|
|
|
|
Select the next action.
|
|
|
|
`a' (`ivy-read-action')
|
|
.......................
|
|
|
|
Use a menu to select an action.
|
|
|
|
`C' (`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.
|
|
|
|
|
|
File: ivy.info, Node: Saving the current completion session to a buffer, Prev: Hydra in the minibuffer, Up: Minibuffer key bindings
|
|
|
|
4.2.7 Saving the current completion session to a buffer
|
|
-------------------------------------------------------
|
|
|
|
`C-c C-o' (`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.
|
|
|
|
`RET' or `f' (`ivy-occur-press')
|
|
................................
|
|
|
|
Call the current action on the selected candidate.
|
|
|
|
`mouse-1' (`ivy-occur-click')
|
|
.............................
|
|
|
|
Call the current action on the selected candidate.
|
|
|
|
`j' (`next-line')
|
|
.................
|
|
|
|
Move to next line.
|
|
|
|
`k' (`previous-line')
|
|
.....................
|
|
|
|
Move to previous line.
|
|
|
|
`a' (`ivy-occur-read-action')
|
|
.............................
|
|
|
|
Read an action and make it current for this buffer.
|
|
|
|
`o' (`ivy-occur-dispatch')
|
|
..........................
|
|
|
|
Read an action and call it on the selected candidate.
|
|
|
|
`q' (`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$*'.
|
|
|
|
|
|
File: ivy.info, Node: Completion Styles, Next: Customization, Prev: Key bindings, Up: Top
|
|
|
|
5 Completion Styles
|
|
*******************
|
|
|
|
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):
|
|
1. `re-builder' argument passed to `ivy-read'.
|
|
|
|
2. `collection' argument passed to `ivy-read' is a function and has an
|
|
entry on `ivy-re-builders-alist'.
|
|
|
|
3. `caller' argument passed to `ivy-read' has an entry on
|
|
`ivy-re-builders-alist'.
|
|
|
|
4. `this-command' has an entry on `ivy-re-builders-alist'.
|
|
|
|
5. `t' has an entry on `ivy-re-builders-alist'.
|
|
|
|
6. `ivy--regex'.
|
|
|
|
* Menu:
|
|
|
|
* ivy--regex-plus::
|
|
* ivy--regex-ignore-order::
|
|
* ivy--regex-fuzzy::
|
|
|
|
|
|
File: ivy.info, Node: ivy--regex-plus, Next: ivy--regex-ignore-order, Up: Completion Styles
|
|
|
|
5.1 ivy-regex-plus
|
|
==================
|
|
|
|
`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.
|
|
|
|
|
|
File: ivy.info, Node: ivy--regex-ignore-order, Next: ivy--regex-fuzzy, Prev: ivy--regex-plus, Up: Completion Styles
|
|
|
|
5.2 ivy-regex-ignore-order
|
|
==========================
|
|
|
|
`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"'.
|
|
|
|
|
|
File: ivy.info, Node: ivy--regex-fuzzy, Prev: ivy--regex-ignore-order, Up: Completion Styles
|
|
|
|
5.3 ivy-regex-fuzzy
|
|
===================
|
|
|
|
`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.
|
|
|
|
|
|
File: ivy.info, Node: Customization, Next: Commands, Prev: Completion Styles, Up: Top
|
|
|
|
6 Customization
|
|
***************
|
|
|
|
* Menu:
|
|
|
|
* Faces::
|
|
* Defcustoms::
|
|
* Actions::
|
|
* Packages::
|
|
|
|
|
|
File: ivy.info, Node: Faces, Next: Defcustoms, Up: Customization
|
|
|
|
6.1 Faces
|
|
=========
|
|
|
|
`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 to `t', then
|
|
confirming non-existent files in `ivy-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'
|
|
.........................
|
|
|