doc/ivy.org: Start writing a manual

[gnu-emacs-elpa] / doc / ivy.org

#+TITLE: Ivy User Manual
#+AUTHOR: Oleh Krehel
#+EMAIL: ohwoeowho@gmail.com
#+DATE: 2015
#+LANGUAGE: en

#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: Ivy: (ivy).
#+TEXINFO_DIR_DESC: Using Ivy for completion.
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css"/>

#+OPTIONS: H:4 num:3 toc:2
#+STARTUP: indent

* Copying
:PROPERTIES:
:COPYING:  t
:END:

#+BEGIN_TEXINFO
@ifnottex
This manual is for Ivy version 0.7.0.

Ivy is a completion interface for Emacs. When @code{ivy-mode} is active,
any time another Elisp code requires completion you'll be able to
preview the candidates in the minibuffer and select them with both
simple input and powerful regexps.
@end ifnottex

Copyright @copyright{} 2015 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License.''

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.''
@end quotation
#+END_TEXINFO

* Introduction
Any time Emacs prompts you for a string, with several choices, Ivy
allows you to preview and quickly select among these choices.

The key aspects of Ivy are minimalism, simplicity, customizability and
being discoverable.

#+BEGIN_TEXINFO
@subsubheading Minimalism
#+END_TEXINFO
Only the minimal necessary amount of information is
displayed in the minibuffer. Compared to the default completion,
additionally the current number of matches is displayed before the
prompt, and a few candidates are displayed below the input. You can
customize =ivy-length= to adjust the amount of displayed candidates,
it's 10 by default.

#+BEGIN_TEXINFO
@subsubheading Simplicity
#+END_TEXINFO
The minibuffer area should behave as a
=fundamental-mode= buffer as much as possible. For example, unlike the
default completion, ~SPC~ simply inserts a space, instead of being
bound to =minibuffer-complete-word=. Additionally Ivy aims to have
simple to understand code: everything is stored in easy to examine
global variables, and no branch-introducing custom macros are used.

#+BEGIN_TEXINFO
@subsubheading Customizability
#+END_TEXINFO
Ideally, you should be able to customize your completion session as
much as possible, with different settings for different completions,
if you so prefer. For example, you can add your own display function
to that points to a selected candidate with =->=, instead of
highlighting it with the =ivy-current-match= face. It's also possible
to customize many commands to do different things with the selected
candidate. For example, when describing functions with
=counsel-decribe-function=, you describe the candidate with ~RET~, but
can also jump to definition with ~M-o d~. While the ~M-o~ prefix isn't
normally customized, you can bind any following key like ~d~ to do
anything to the selected candidate. This way, it's possible to group
several functions into one through the completion interface.

#+BEGIN_TEXINFO
@subsubheading Discoverability
#+END_TEXINFO
While in the minibuffer, you can press ~C-o~ to call
=hydra-ivy/body=. This will expose a large amount of commands
available in the minibuffer, all annotated with short docstrings.

* Installation

Ivy can be installed using Emacs' package manager or manually from its
development repository.

** Installing from ELPA
If you haven't used Emacs' package manager before, you can read about
it in the Emacs manual, see [[info:emacs#Packages]].

Ivy is available from both GNU ELPA - the official Emacs package
repository, and from MELPA - the most popular unofficial Emacs package
repository.

Your Emacs should be configured to use GNU ELPA automatically.  To
also add MELPA, use this code:

#+begin_src elisp
(require 'package)
(add-to-list 'package-archives
             '("melpa" . "http://melpa.org/packages/") t)
#+end_src

After this do ~M-x~ =package-refresh-contents= ~RET~, followed by
~M-x~ =package-install= ~RET~ =swiper= ~RET~.

There's a version difference between GELPA and MELPA. GELPA holds the
latest stable version, while MELPA contains current hourly builds.

** Installing from the Git repository

Installing from Git offers advanced users numerous advantages:

- You don't have to wait for MELPA's hourly build to finish to receive
  an update.
- You can update to the current version and revert to an earlier one
  whenever you want.
- You can contribute to the development of Ivy by editing the code and
  sending patches/pull requests.

*Configuration steps*

Clone the Swiper repository:
#+begin_src sh
cd ~/git && git clone https://github.com/abo-abo/swiper
cd swiper && make compile
#+end_src

Add this code to your init:
#+begin_src elisp
(add-to-list 'load-path "~/git/swiper/")
(require 'ivy)
#+end_src

To update the code use:
#+begin_src sh
git pull
make
#+end_src

* Getting started

This section describes the most common configuration steps.  First of
all, to get Ivy completion everywhere, use:

#+begin_src elisp
(ivy-mode 1)
#+end_src

You can also toggle =ivy-mode= on and off with ~M-x~ =ivy-mode=. This
is the minimal necessary step to get Ivy working.

** Setting up Ivy global key bindings
These are the recommended mnemonic (and otherwise) key bindings:
#+BEGIN_TEXINFO
@subsubheading Ivy-improved versions of standard commands
#+END_TEXINFO
#+begin_src elisp
(global-set-key (kbd "C-s") 'swiper)
(global-set-key (kbd "M-x") 'counsel-M-x)
(global-set-key (kbd "C-x C-f") 'counsel-find-file)
(global-set-key (kbd "<f1> f") 'counsel-describe-function)
(global-set-key (kbd "<f1> v") 'counsel-describe-variable)
(global-set-key (kbd "<f1> l") 'counsel-load-library)
(global-set-key (kbd "<f2> i") 'counsel-info-lookup-symbol)
(global-set-key (kbd "<f2> u") 'counsel-unicode-char)
#+end_src
#+BEGIN_TEXINFO
@subsubheading Ivy-based interfaces to great shell and system tools
#+END_TEXINFO
#+begin_src elisp
(global-set-key (kbd "C-c g") 'counsel-git)
(global-set-key (kbd "C-c j") 'counsel-git-grep)
(global-set-key (kbd "C-c k") 'counsel-ag)
(global-set-key (kbd "C-x l") 'counsel-locate)
(global-set-key (kbd "C-S-o") 'counsel-rhythmbox)
#+end_src
#+BEGIN_TEXINFO
@subsubheading Other useful commands
#+END_TEXINFO
The =ivy-resume= command allows to resume the last Ivy-based
completion.
#+begin_src elisp
(global-set-key (kbd "C-c C-r") 'ivy-resume)
#+end_src
** Setting up common customizations

Here are some basic customizations that a new user might be interested
in, in no particular order:
#+begin_src elisp
(setq ivy-use-virtual-buffers t)
(setq ivy-height 10)
(setq ivy-display-style 'fancy)
(setq ivy-count-format "(%d/%d) ")
#+end_src

You can examine them more closely by looking at the documentation of
these variables.

** Minibuffer bindings

Most of Ivy's minibuffer bindings are defined in =ivy-minibuffer-map=
keymap.  Some commands, like =swiper= or =counsel-M-x= pass an
additional keymap through the =keymap= argument to =ivy-read=.  The
additional bindings will be described in each command's section.  This
section describes the most useful default key bindings.

*** Candidate navigation keys
The most basic navigation keys are ~C-n~ (=ivy-next-line=) and ~C-p~
(=ivy-previous-line=), they select the next and the previous candidate
respectively. By default, they don't wrap-around after reaching the
first or the last candidate. I you'd like to change this, customize
=ivy-wrap=.

Next, ~M-<~ (=ivy-beginning-of-buffer=) and ~M->~
(=ivy-end-of-buffer=) will select the first and the last candidate
respectively.

Additionally, ~C-v~ (=ivy-scroll-up-command=) and ~M-v~
(=ivy-scroll-down-command=) allow you to scroll by whole candidate
screen, which has the size =ivy-height=, 10 by default.

*** Candidate selection keys that exit the minibuffer
When you've finally selected a candidate you like, you'll want to do
something with it. In Ivy's terms it's called "calling an action",
which can also be combined with exiting the minibuffer and thus
finishing completion. Note that unlike with the default completion,
exiting the minibuffer is optional, because you might want to call an
action or actions for several candidates and not just one.

The most basic binding is ~C-m~ or ~RET~ (=ivy-done=). It calls the
action and exits the minibuffer.

The second important binding is ~C-j~ (=ivy-alt-done=). It's no
different from =ivy-done=, except when completing file names.  In that
case pressing ~C-j~ on a directory will offer completion for that
directory, while ~C-m~ will select that directory and exit the
minibuffer.

Another binding, which may be familiar is ~TAB~
(=ivy-partial-or-done=). It will attempt to do partial completion:
extend the current input as much as possible, according to the
candidates that currently match. Pressing ~TAB TAB~ is equivalent to
~C-j~.

With all above bindings, the action is called for the /currently
selected/ candidate.  But what if the input you want isn't in the
collection, but still matches one of the candidates?  Pressing either
~C-m~, or ~C-j~ would call the action for that selected candidate,
which isn't what you wanted to do.  Use ~C-M-j~ (=ivy-immediate-done=)
to call the action for /the current input/ instead of /the current
candidate/. Common uses of ~C-M-j~ are with =find-file= and
=dired-create-directory=: the new name might match the already
existing files or directories.

The penultimate key binding from the set that exits the minibuffer is
~M-o~ (=ivy-dispatching-done=).  In case the current completion has
more than one action to choose from to act on the selected candidate,
~M-o~ will allow you to select and call that action. In case there's
only one action, ~M-o~ does the same and ~C-m~.

#+BEGIN_TEXINFO
And the final binding is @kbd{C-'} (@code{ivy-avy}).
#+END_TEXINFO
It allows to select a visible candidate faster than e.g. ~C-n C-n C-n C-n C-m~.

*** Candidate selection keys that don't exit the minibuffer
The bindings that don't exit the minibuffer are usually constructed by
adding the meta key to the other version.

~C-M-m~ (=ivy-call=) is the non-exiting version of ~C-m~. Suppose you
have a =counsel-describe-function= completion session, you've narrowed
the candidate list significantly, say to 5 candidates, and you want to
describe the second and the fourth candidates.  With the default
completion you would probably describe the second candidate, then
call =describe-function= again, recall history with ~M-p~ and edit it
to match the forth candidate and exit once more. With Ivy, you can
press ~C-n~ to select the second candidate, ~C-M-m~ to describe it,
~C-n C-n~ to skip to the fourth candidate and ~C-m~ to describe it and
exit the minibuffer.

Alternatively, you could select the second candidate with ~C-m~, then
resume completion with =ivy-resume=. That will bring up the completion
session in a state as if you hadn't exited: the input will be the
same, and the second candidate will still be selected. Then you could
once again select the fourth one with ~C-n C-n C-m~.

~C-M-o~ (=ivy-dispatching-call=) is a non-exiting version of ~M-o~.
It might be useful for instance in =counsel-rhythmbox=: use ~C-M-o e~
to enqueue the selected candidate, and ~C-n C-m~ to play the next
one. Here, =play= is the default action, and =enqueue= is an extra
action bound to ~e~.

~C-M-n~ (=ivy-next-line-and-call=) is a combination of ~C-n~ and
~C-M-m~.  ~C-M-p~ (=ivy-previous-line-and-call=) is a combination of
~C-p~ and ~C-M-m~.  Both can be used to call the action many
times. For instance to open a lot of files in the current directory
with =counsel-find-file=, press and hold ~C-M-n~.  Same for cycling
matches in =counsel-git-grep= / =counsel-ag= / =counsel-locate=.

*** Key bindings that change the minibuffer input
~M-p~ (=ivy-previous-history-element=) and ~M-n~
(=ivy-next-history-element=) allow to cycle a command's history.  A
new entry is added to the history each time an action is called on a
candidate. Additionally, ~M-n~ has a special behavior when it's the
first command (i.e. there's no history element to scroll down to): in
that case URL or symbol at point is inserted into the minibuffer.

~M-i~ (=ivy-insert-current=) will insert the current candidate into
the minibuffer.  It's especially useful for copying files to a
slightly different name: press ~M-i~ to insert the original, modify it
slightly and ~C-m~.

~M-j~ (=ivy-yank-word=) will insert the subword at point into the
minibuffer.  This is the closest thing to ~C-s C-w~ with
=isearch=. It's not bound to ~C-w~ because ~C-w~ calls =kill-region= -
a pretty useful editing function.

~S-SPC~ (=ivy-restrict-to-matches=) will delete all current input. In
addition it will reset the candidates collection to the one that was
active at the moment of calling. This allows to narrow the candidate
list in tiers if necessary.

~C-r~ (=ivy-reverse-i-search=) works in a similar way to ~C-r~ bash:
it opens a recursive completion session with the history elements as
candidates. Once finished, that history element is inserted into the
minibuffer.

*** Miscellaneous key bindings
~M-w~ (=ivy-kill-ring-save=) will work as regular =kill-ring-save=
when the region is active, otherwise it will copy all selected
candidates to the kill ring.

*** The mini-documentation hydra
~C-o~ (=hydra-ivy/body=) is a prefix to a multitude of shortcuts.  For
example: ~C-n C-n C-n C-n~ is equivalent to ~C-o jjjj~.  When ~C-o~ is
toggled on, you can no longer enter text into the minibuffer. If you
want to resume entering text, press ~C-o~ or ~i~.

It serves several purposes:

- It can be more efficient in terms of shorter bindings.
- It contains less popular bindings, like ~<~ and ~>~ for adjusting
  the height of the minibuffer.
- It describes the current completion state, like the case folding and
  the current action.

*** Storing the current completion session to a buffer
~C-c C-o~ (=ivy-occur=) will store the current candidates into a new
buffer.  Pressing ~RET~ or ~mouse-1~ in that buffer will result in the
appropriate action being called on the selected candidate.  You can
have as many of these buffers as you like, and they will be named
appropriately to show what they do, e.g =*ivy-occur
cousnel-describe-variable "function$*=.

** Completion styles
The completion in Ivy is customizable through regex builder functions.
The default settings start out at:
#+begin_src elisp
(setq ivy-re-builders-alist
      '((t . ivy--regex-plus)))
#+end_src

Which means that =ivy--regex-plus= is used for all collections. Here's
how to use another re-builder specifically for file name completion:
#+begin_src elisp
(setq ivy-re-builders-alist
      '((read-file-name-internal . ivy--regex-fuzzy)
        (t . ivy--regex-plus)))
#+end_src

These two and other styles of re-builders will be described below.

*** ivy--regex-plus
The default completion method in Ivy is represented by the
=ivy--regex-plus= function. For this function, the matching is done by
splitting the input by spaces and rebuilding it into a regex.

So "for example" is transformed into "\\(for\\).*\\(example\\)", which
means to match "for", followed by wildcard, followed by "example".
You get used to how this works very fast since each part is
highlighted with a different face in the minibuffer.

If you need to match literal spaces, input that amount of spaces plus
one, e.g. input two spaces to match one, three to match two etc.

Regexp negation is also supported and is done by entering words that
you don't want to match after a "!". For example "define key ! ivy
quit" will first select everything that matches "define.*key", then
remove everything that matches "ivy" and everything that matches
"quit".

Other than spaces being translated into ".*" and "!" starting a
negation group, the minibuffer input is treated as a regular regexp,
so you can simply input things like "^", "$", "\b" or "[a-z]".

*** ivy--regex-ignore-order
This works similarly to =ivy--regex-plus= except the order of the
parts doesn't matter any more.  For instance, the input "for example"
will match "example test for".

*** ivy--regex-fuzzy
This method splits each character separately, so "for" is translated
into "f.*o.*r". This means it might result in a huge amount of
matches.  To manage this amount of matches somehow, you can install
the =flx= package which will automatically be used by Ivy to do the
candidate scoring. If you've used =ido-flx= before, it's almost the
same.