Not all windows. See #117.
swiper-avy should use only the current window
See fix wrap-around for #118.
swiper-avy should do nothing for empty input
ivy-alt-done should require TRAMP if necessary
swiper-query-replace shouldn’t miss the first occurrence
swiper should not deactivate mark
ivy-mode should not switch to TRAMP for certain input
“/ssh:foo” should not be cut off
counsel-find-file should work better with TRAMP
counsel-find-file supports Windows drive letters
counsel-file-file should work better with files that contain “~”
counsel-M-x should respect
counsel-git-grep should position better on exit
ivy-mode should re-scale text to minibuffer height
counsel-unicode-char should use action-style call
ivy-read should allow % in prompt string
ivy-call should execute in proper window
Open an Info file on the file system
g and select either “(./)” or “(../)” to
switch to file name completion. That file will be opened with Info.
If you have
minibuffer-depth-indication-mode on, the minibuffer
prompt will indicate the current depth.
Add fuzzy matching function
To enable fuzzy matching, set your
(setq ivy-re-builders-alist '((t . ivy--regex-fuzzy)))
See also #142 for toggling fuzzy matching with
Bind case-fold-search to t when the input is all lower-case:
- input “the” matches both “the” and “The”.
- input “The” matches only “The”.
Allow to see the candidate index a la
To have this feature, use something like this:
(setq ivy-count-format "(%d/%d) ")
You can also set this to “”, if you don’t want any count, see #188.
Allow to add additional exit points for any command
(ivy-set-actions 'ivy-switch-buffer '(("k" (lambda (x) (kill-buffer x) (ivy--reset-state ivy-last)) "kill") ("j" ivy--switch-buffer-other-window-action "other")))
M-o kto kill a buffer
M-o jto switch to a buffer in other window
You can always use
M-o o to access the default action. When there is
only one action,
M-o does the same as
Add a binding to look up the symbol in info
Press ~C-,~ to look up the symbol in info, instead of the default describe action. See #121.
Handle symbol-at-point better in non-Elisp buffers
Deal better with invisible buffers
Add custom keymap
You can customize
Add extra actions
kill-buffer action, and
Make it fully async: the process
git grep will be killed and
restarted on new input. This results in almost no keyboard delay.
Own history variable
Own history variable
Having own history variable allows to get more use of
Switch to action-style call
This allows to make use of
Add extra actions
In addition to the default action of opening a file add:
C-o to access these actions.
Add own history
A matcher is a function that accepts a regexp and a list of candidates and returns the filtered list of candidates.
The default matcher is basically
If you’d like to customize this, pass your own matcher.
counsel-git-grep-matcher for an example.
Allow to customize the initial input for all commands
ivy-initial-inputs-alist for this.
ivy-sort-functions-alist should also examine
:dynamic-collection is now a boolean
Pass the collection function as the second var instead.
Execute the current action for the current candidate without exiting
the minibuffer. Bound to
find-filewith Ivy completion.
ivy-next-line-and-call as well as
ivy-resume should work for this command.
counsel-find-file-ignore-regexp allows to ignore
certain files, like dot files. Input a leading dot to see all files.
counsel-find-file-at-point allows to automatically use
ffap. You also can do it manually with
M-n when the point is on a file name.
counsel-find-file-map allows to customize the
minibuffer key bindings for this command.
(global-set-key (kbd "C-x C-f") 'counsel-find-file)
You can peek at files with
See #152 about
M-i switching directories when necessary.
Find a file on
Note that if your set
merged into candidates list for
ivy-switch-buffer. But if you want
it separately, you can use this command.
Add word at point to minibuffer input.
This is similar to what
C-w does for
isearch. However it’s bound
M-j instead of
C-w is bound to
kill-region - a
execute-extended-commandwith Ivy completion. The candidate list will also display the key binding for each bound command.
This command will piggyback on
smex for sorting, if
smex is installed.
counsel-M-x-initial-input to customize the initial input for
this command. By default, it’s “^” - the regex character that
indicates beginning of string. This results in much faster matching,
since you usually type the command name from the start.
C-oto toggle the Hydra for Ivy. It gives access to shorter bindings and many customizable options.
C-o > to grow the minibuffer.
C-o < to shrink the minibuffer.
Toggle executing the current action each time a new candidate is selected.
This command is bound to
To explain how this is useful:
C-M-m C-M-f C-M-f C-M-f is equivalent to
Inserts the current candidate into the minibuffer.
M-i if you want something close to the current candidate. You
can follow up with an edit and select.
I find this very useful when creating new files with a similar name to
the existing file:
C-x C-f M-i + a bit of editing is very fast.
load-themewith Ivy completion. Allows to rapidly try themes (e.g. with
Allow to recursively match history with
I like this command from bash shell. The usual way to search through
history is with
open a recursive completion session with the current history as the
Control Rhythmbox from Emacs.
Select an action for the current candidate and execute it. Bound to
Some commands that support
org-set-tagswith Ivy completion.
Selecting any tag each time will toggle it on/off. The current list of selected tags will be displayed in the prompt.
org-agenda-set-tagswith Ivy completion. See #177.
agusing Ivy completion.
recollwith Ivy completion. See Using Recoll desktop search database with Emacs.
Install recoll with
sudo apt-get install recoll.
swiperfrom the current
Use this command to exit the minibuffer choosing not the current
candidate, but the current text. Bound to
Fix :dynamic-collection not being sorted
See When :initial-input contains a plus, escape it#195.
See Set line-spacing to 0 in the minibuffer#198.
See Enlarge the minibuffer window if the candidate list doesn’t fit#198 and #161 and #220.
See Fix minibuffer collapsing to one line#237, #229 and #77.
Allows Use minibuffer-allow-text-properties
ivy-readto return a propertized string.
C-g out of a long-running async process
See Don’t regexp-quote :preselect#245.
See Fix ivy-partial for fuzzy completion#266.
See ivy-resume should pass :caller#245.
See Fix the regression in perfect match logic#270.
Fix pasting file paths on Windows
C-j should no stop completion for a pasted file path
When completing file names, expand the file name properly.
C-M-j should use
See Use a specific blend method for dark themes#278.
Fix one-off bug in
So now it’s possible to e.g.
M-o shouldn’t set the action permanently
See Fix swiper preselect issue with similar or identical lines#290.
See Make ivy-completing-read handle history as cons#295.
The syntax for whitespace, separators etc. is different for modes. See Perform string-match in the original buffer#298.
Make line numbers into display properties
Each candidate is now a single space plus the original string. The display property of the single space holds the line number. This means that it’s no longer possible to match line numbers in queries, which is a good thing if you’re searching for numbers.
Add support for
Make compatible with
swiper will split the lines when
visual-line-mode is on. This is
convenient for small buffers. For large buffers, it can be very slow,
visual-line-mode is slow.
At each start of
swiper, the face at point will be stored.
Use this command to toggle matching only the candidates with that face.
push-mark only if exited the minibuffer
C-M-p will no longer push mark and annoy with messages.
ivy-resume should restore the buffer for
swiper buffer-1, you can switch out of the minibuffer into
buffer-2 and call
swiper again. Exiting the second minibuffer will
restore the first minibuffer.
To use this, you need to enable recursive minibuffers.
(setq enable-recursive-minibuffers t)
It’s also useful to indicate the current depth:
field text property is now removed before inserting text into
the minibuffer. This fixes the
swiper problems with
twittering-mode. See #310.
In the current state, the manual covers the most basic topics, like the minibuffer key bindings and the regexp builders.
Make <left> and <right> behave as in fundamental-mode
Truncate minibuffer prompts longer than window-width
C-M-n should not leave the minibuffer
Make sure that the minibuffer window remains selected as long as the
completion hasn’t finished. For example,
<f1> f to call
counsel-describe-function, input “forward” and spam
C-M-n to read
the doc for each function that starts with “forward”. The
window popup would move the window focus, but this change moves it
back to the minibuffer.
Since flx is costly, move the caching to an earlier point. This means
immediate return for when the input hasn’t changed, i.e. for
flx is installed, and
(eq ivy--regex-function 'ivy--regex-fuzzy)
for current function (through
ivy-re-builders-alist), then sort the final candidates with
In the worst case, when some error pops up, return the same list. In
the best case sort the
cands that all match
name by closeness to
How to use:
(require 'flx)should succeed.
ivy-re-builders-alistappropriately to use
(setq ivy-re-builders-alist '((t . ivy--regex-fuzzy)))
Support hash tables
all-completions also works for hash tables, no reason not to support them.
Improve documentation of
Now possible to set it with Customize.
Customize this to decide how the index, i.e. the currently selected candidate, is updated with new input. For example, one strategy is not reset it to 0 after each change.
Another strategy, used for
swiper, is to try to select the first
appropriate candidate after (inclusive) the first previously selected
candidate. This way, if you’re typing something that matches what is
currently selected, the selection won’t change.
The mode of abbreviation for virtual buffer names.
Used to override
case-fold-search. See #259.
Add feedback for long-running async processes
Each time 0.5s pass after the last input, if the external process
hasn’t finished yet, update minibuffer with the amount of candidates
collected so far. This is useful to see that long running commands
counsel-ag (when in a very large directory)
ivy-extra-directories to defcustom
ivy-sort-function-alist to defcustom
M-n should prefer url at point to symbol at point
C-x C-f M-n calls
ffap-url-fetcher when at URL
Highlight modified file buffers with
This new face is blank by default, but you can use e.g.:
(custom-set-faces '(ivy-modified-buffer ((t (:background "#ff7777")))))
Store the old
ivy-last in case
ivy-read is called while inside the
minibuffer. Restore it after
Allow user-specified matched candidate sorting
By default, Ivy doesn’t sort the matched candidates, they remain in the same order as in the original collection. This option is the default, since it’s fast and simple.
A small problem with this approach is that we usually want prefix matches to be displayed first. One solution to this is to input “^” to see only the prefix matches.
Now, another solution is to can set:
(setq ivy-sort-matches-functions-alist '((t . ivy--prefix-sort)))
Here’s another example of using this defcustom:
(add-to-list 'ivy-sort-matches-functions-alist '(read-file-name-internal . ivy--sort-files-by-date))
After this, during file name completion, most recently changed files will be ahead.
M-o r rename the buffer instead of switching.
Allow customizing locate options
The current setting is:
(setq counsel-locate-options '("-i" "--regex"))
open instead of
OSX, since there
locate doesn’t support
Use single quotes for the regex
Add initial-input argument
Now works in agenda
Add own history
Add “definition” action
M-o d to jump to definition.
current-prefix-arg in the prompt
Input ‘/sudo::’ goes to current directory instead of root’s home
Fix directory validity check
Improve TRAMP support
Selecting items after
// now works properly.
Use prefix arg to specify the shell command.
Remember to use
M-i to insert the current candidate into the
C-c C-o (
ivy-occur) while in
counsel-git-grep will produce
ivy-occur gives full candidates
This means that the =” | head -n 200”= speed-up isn’t used and full candidates are returned.
Allow to jump back with pop-tag-mark
will change the current buffer. The buffer and point can be restored
I also recommend this binding:
(global-set-key (kbd "M-,") 'pop-tag-mark)
Resolve the name clash better
When the symbol is both bound and fbound, prefer the fbound one,
Support alternative initial directory which helps other packages call this function with their unique starting directory.
Fix on Windows
Using the “–vimgrep” argument improves things.
C-c C-o. Store the current completion session to its own buffer. You can have an unlimited amount of these buffers.
Bound to ~C-‘~.
Speeds up selecting a candidate that’s currently visible in the minibuffer.
When the region is active, call
kill-ring-save. Otherwise, store
all selected candidates to the kill ring.
This is a non-exiting version of
C-M-a. Select the current action. Don’t call it yet.
swiperin multiple buffers. See #182.
Basic usage tips for selecting multiple buffers:
ivy-call) to add or remove one more buffer without exiting.
ivy-done) to add one last buffer.
- Or use
ivy-immediate-done) to finish without adding more buffers.
ivy-next-line-and-call) to add a lot of buffers at once.
Open multiple cursors at all selected candidates.
New command to launch
swiperfor all open file buffers. Note that this can be excruciatingly slow if you don’t clean up your buffer list often.
This is essentially
swiperfor huge files. It’s not as smooth as
swiperfor small files, but has a faster startup and faster matching for files that measure in megabytes.
query-replaceon all matches in all buffers.
Complete Python symbols using Jedi.
Complete Common Lisp symbols using SLIME.
Give completion for inserting from the kill ring.
counsel-yank-pop-truncatedefcustom and #218.
Due to popular demand, Package rename
swiper-0.7.0is succeeded by
ivy-0.8.0in GNU ELPA. The contents of the package don’t change, only the name. Make sure to remove the
~/.emacs.d/elpa/swiper-0.7.0directory if you have it and
HTML documentation is available at Documentationhttp://oremacs.com/swiper/.
Texinfo documentation is in doc/ivy.texi.
The HTML file shouldn’t be in this repository to avoid bloat, instead it’s in the gh-pages branch at https://github.com/abo-abo/swiper/tree/gh-pages.
Fix recursive minibuffer exit with
Make it so e.g.
C-h f C-h v C-g goes back to the
Ensure the return result
In some cases,
read-from-minibuffer will return the whole minibuffer
contents (i.e. all available candidates). Return
Properly support matching ignoring order
Insert intermediate candidates during async completions
ivy-last to empty state
Fix extra actions for
Support a list of symbols as collection
defvar-local unless defined
With this commit, Ivy works on emacs-24.2. See #415.
M-o not modify the action
Make sure user keybindings are respected
read-file-name with a specified dir
Don’t highlight the match in the file part
Add a few tests for alists
next-error etc will work properly.
Fix for small delta
completing-read-default for tmm
Recognize ! at the beginning of the str
Prettify a bit
\\(?...\) a group
Always return a valid window
state is invalid.
Fix due to recursive update
This is specifically for =’read-file-name-internal= collection. The
input needs to be set to nil for e.g.
rgrep, which supplies the
absolute path as
initial-input, resulting in a mess.
For now, don’t set input to nil if
:action was passed to
Don’t deactivate region
Optimize for 1 candidate
When there’s only one candidate, call the action immediately.
Add feedback for 1 candidate
When the sole completion is the same as the input, notify the user. See #350.
It’s convenient to have it the same value as
Give enough minibuffer space
Allow to customize the action hint formatter
Fix for nil value
Don’t fall back to
No “\_<” for dynamic-collection
“\_<” regex is Emacs-specific and should only be done if
:dynamic-collection is nil. It is nil for
repositories < 20000 lines, but non-nil for larger ones.
Pulse no longer
Repeated pulses within a short time span resulted in horrible window flickering.
Add a guard against null
C-g cancel gracefully
Allow to exit with no candidates.
Improve for multiple occurrences on one line
Fix “backward” search
When none of the previous candidates after the point match the current input, instead of returning 0, return the index of the last matching candidate. This is a good choice, because that candidate is the closest to the point of the initial search start.
Always remove ‘(field) text property
Allows to search better in modes for shell interaction.
Add bongo-library-mode, bongo-playlist-mode, sauron-mode.
Don’t fail when font-lock is off
Add check for
Fix issue with
Re-display when no cands
Recognize error codes other than 1
Fix window selection.
with-ivy-window, so that each new file chosen with e.g.
selected in the same window.
See compilation warnings#324.
flx for highlighting fuzzy matches
Simplify the signature for
:dynamic-collection, assume the collection function only
needs one argument - the string input.
M-n prediction when region is active
When the region is active and
M-n is called, insert the region
contents into the minibuffer and deactivate the region. The region
deactivation is done for
swiper, to make it easier to search for
multiple words or a subword.
Allow to compose collections
Example 1: async collection
recentf on top of
(defun small-test () (cl-subseq recentf-list 0 10)) (ivy-set-sources 'counsel-locate '((small-test) (original-source)))
Here, (original-source) represents the async candidates of
counsel-locate. All extra sources are static - each function is called
once to generate a list of strings, which will be filtered later.
The order matters, so you can have e.g.:
(ivy-set-sources 'counsel-locate '((original-source) (small-test)))
Example 2: sync collection
(defun my-extra-source () (append (when (eq 'Git (vc-backend (buffer-file-name))) (list "git1" "git2" "git3")) (when (file-exists-p "doc/Changelog.org") (list (propertize "doc/Changelog.org" 'face '(:background "red")))))) (defun my-find-file () (interactive) (ivy-read "Find file: " 'read-file-name-internal :action (lambda (x) (with-ivy-window (find-file (expand-file-name x ivy--directory)))) :require-match 'confirm-after-completion :history 'file-name-history :caller 'my-find-file)) (ivy-set-sources 'my-find-file '((my-extra-source) (original-source)))
my-find-file knows nothing about the extra source, it’s
only purpose is to introduce a
:caller to attach things to, as to not
to mess up e.g.
my-extra-source gets called once in
ivy--reset-state. It takes no args and returns a list of strings,
Improve documentation UI
C-h m to
ivy-help-file is a new defvar pointing to the ivy-help.org file.
hydra-ivy to go to hydra’s definition.
Add ignore pattern toggling
C-c C-a is bound to
ivy-toggle-ignore - a new command to toggle ignore
patterns (user-configured filtering). If the ignore patterns are
enabled and there are zero candidates after ignoring, display the ones
that match the current text. This feature currently works for
M-n for =’read-file-name-internal=
Allows to customize
Add custom occur for
New commands on
(ivy-occur-toggle-calling): New command bound to
(ivy-occur-next-line): New command bound to
(ivy-occur-previous-line): New command bound to
ivy-occur much more convenient, instead of
cjjj. Especially good for commands that change the contents of the
other window, like
C-o ualso works.
Does what e.g.
revert-buffer does for Help buffers.
Has special handling for
counsel-grep: will run the shell command once more and reflect the
updates in files.
Improve the feedback for
The overlays will be more responsive now.
this-command to be a key
(defun asdf () (interactive) (completing-read "prompt: " '("abc" "abcd" "def"))) (global-set-key (kbd "C-c t") 'asdf) (setq ivy-re-builders-alist '( (asdf . ivy--regex-fuzzy) (t . ivy--regex-plus)))
This is useful for commands that you didn’t write. For new commands
that you write, consider using
t to affect all commands
(ivy-set-actions t '(("i" insert "insert")))
Now an “insert” action will be available for all
New defcustom group.
New variable. Configure when
flxis used. See #207.
New variable. See #363.
New defcustom. See #367.
When non nil, fix the height of the minibuffer during ivy completion
ivy-height. This effectively sets the minimum height at this level
and tries to ensure that it does not change depending on the number of
New API function.
Now used by
New defcustom similar to
Add virtual views
ivy-views variable stores pre-defined views. Allows to set a window
configuration with many buffers from
How to use: just set
ivy-views appropriately. An example value is
provided (but nulled, so that it’s empty initially).
To replace a symbol with a similar symbol,
swiperand select the symbol at point as input.
M-nto yank the symbol to replace.
- Edit the replacement and
Here step-3 was modified to yank e.g. “symbol” instead of “\_<symbol\_>” previously.
New variable for major modes that misbehave with
font-lock-ensure. See #346.
New auto-updates position
A minor-mode that remaps built-in functions that have counsel
Allow use of describe-prefix-bindings
Change tramp prompt from “Find File: ” to “user@host: ”
New function that moves up to the parent directory and at the same time preselects the current directory. This is useful for moving up and down a file tree quickly.
This feature allows to quickly visit Github issues from either
magit-commit-mode or from a version-controlled file. The point has to
be at the “#” char in e.g. ”#123”, that represents an issue.
It’s possible to customize
ivy-ffap-url-functions to do a similar
thing for places other than Github.
C-x C-f M-n key binding will work better with
find-file it will open a
dired buffer in addition to opening
Can un-ignore dotfiles with a leading dot input
ivy-text starts with a dot, don’t use
counsel-find-file-ignore-regexp. The generic way to do this is with
C-c C-a (
ivy-toggle-ignore), but this is faster and more convenient.
M-o f to
Correctly expand file name at point
Add display transformer
Add magic slash that changes the directory
Update to the behavior: the slash (“/”) will enter a directory even if its name isn’t completely typed out if either:
- It’s the only candidate.
- The candidate index isn’t 0, i.e. “C-n” has been typed at least once.
- The input isn’t “/”.
The above rules still allow to keep the old behavior with “//” moving to root and “/ssh:” opening tramp.
This is an experimental feature, please report if it breaks someone’s workflow.
C-c C-m to
The initial command always runs on all files.
To run only on *.el files,
C-c C-m followed by
To run on *.c and *.h files,
C-c C-m followed by
-- *.c *.h.
To switch to all files again,
C-c C-m and select the appropriate
New defcustom that replaces
New function. See #390.
New function. See #426.
Truncate during display
During the completion, only the context around the match will be shown.
By default, the context is +2 lines above and +2 lines below the match.
It can be adjusted with
ivy-height is temporarily bound to 5 during completion.
This way, the maximum minibuffer height should be 1+4*5=21 lines.
Display hex codes in left column.
Preselect the current song
Allows the command run by
counsel-ag-function to be customized. There
are several reasons to allow this: The vimgrep option is a recent
addition; on windows it’s more convenient to use pt; and the user
might want to customize ignored files.
(setq counsel-ag-base-command "ag --nocolor --nogroup %s -- .")
Add dir prompt for
Add optional exit-code table
This argument can be used to associate exit codes with the underlying reason. Used in counsel-ag-function to signal that an exit code of 1 means that no matches were found.
Should pick candidates closest to point
Fixes the algorithm selecting the first matching candidate in case there are 0 matching candidates following point. Now the last matching candidate will be selected, resulting in less scrolling.
Speed up x40 times
The default shell command will not use
--ignore-case switch for
grep. It’s a bit less convenient, but results in a huge speed-up.
Add help action
M-o h by default.
Completion for the menu bar items. For example:
Set Default Font....
Thanks to completion, the latter stages of the chain would look like:
Jump to a buffer position indexed by imenu.
Show a list of all defined keys, and their definitions. Describe the
Offer completion for
The default action deletes the selected process. An extra action allows to switch to the process buffer.
Search through all available git stashes.
git log --grepshell command and search through the output.
Grep for a string in the current directory using pt.
Launch a Linux desktop application, similar to Alt-<F2>.
Ivy completion for
Browse Eshell history.
Browse shell history.
New command: automatically use
swiperfor smaller buffers and
counsel-grepfor larger buffers.
(setq counsel-grep-swiper-limit 300000)
By default, the splitting predicate is 300K bytes in a file.