code.delx.au - gnu-emacs-elpa/blob - packages/ivy/doc/ivy-help.org

   1 * Ivy Generic Help
   2
   3 =ivy= is an Emacs incremental completion framework.
   4
   5 - Narrow the list by typing some pattern,
   6 - Multiple patterns are allowed by separating with a space,
   7 - Select with ~C-n~ and ~C-p~, choose with ~RET~.
   8
   9 ** Help
  10
  11 - ~C-h m~ :: Pop to this generic help buffer.
  12
  13 ** Basic Operations
  14 *** Key bindings for navigation
  15
  16 - ~C-n~ (=ivy-next-line=) :: next candidate.
  17 - ~C-p~ (=ivy-previous-line=) :: previous candidate.
  18 - ~C-v~ (=ivy-scroll-up-command=) :: next page.
  19 - ~M-v~ (=ivy-scroll-down-command=) :: previous page.
  20 - ~M-<~ (=ivy-beginning-of-buffer=) :: first candidate.
  21 - ~M->~ (=ivy-end-of-buffer=) :: last candidate.
  22
  23 *** Key bindings for single selection
  24
  25 When selecting a candidate, an action is called on it. You can think
  26 of an action as a function that takes the selected candidate as an
  27 argument and does something with it.
  28
  29 Ivy can offer several actions from which to choose. This can be
  30 independently composed with whether you want to end completion when
  31 the action is called. Depending on this, the short term is either
  32 "calling an action" or "exiting with action".
  33
  34 ~C-m~ or ~RET~ (=ivy-done=) - exit with the current action.
  35
  36 ~M-o~ (=ivy-dispatching-done=) - select an action and exit with it.
  37
  38 ~C-j~ (=ivy-alt-done=) - when the candidate is a directory, enter
  39 it. Otherwise, exit with the current action.
  40
  41 ~TAB~ (=ivy-partial-or-done=) - attempt partial completion, extending
  42 the current input as much as possible. ~TAB TAB~ is the same as ~C-j~.
  43
  44 ~C-M-j~ (=ivy-immediate-done=) - exit with the current action, calling
  45 it on the /current input/ instead of the current candidate. This is
  46 useful especially when creating new files or directories - often the
  47 input will match an existing file, which you don't want to select.
  48
  49 ~C-'~ (=ivy-avy=) - select a candidate from the current page with avy
  50 and exit with the current action.
  51
  52 ** Advanced Operations
  53 *** Key bindings for multiple selection
  54
  55 For repeatedly applying multiple actions or acting on multiple
  56 candidates, Ivy does not close the minibuffer between commands. It
  57 keeps the minibuffer open for applying subsequent actions.
  58
  59 Adding an extra meta key to the normal key chord invokes the special
  60 version of the regular commands that enables applying multiple
  61 actions.
  62
  63 ~C-M-m~ (=ivy-call=) is the non-exiting version of ~C-m~ (=ivy-done=).
  64
  65 ~C-M-n~ (=ivy-next-line-and-call=) combines ~C-n~ and ~C-M-m~.
  66
  67 ~C-M-p~ (=ivy-previous-line-and-call=) combines ~C-p~ and ~C-M-m~.
  68
  69 ~C-M-o~ (=ivy-dispatching-call=) is a non-exiting version of ~M-o~
  70 (=ivy-dispatching-done=).
  71
  72 *** Key bindings that alter the minibuffer input
  73
  74 ~M-n~ (=ivy-next-history-element=) select the next history element or
  75 symbol/URL at point.
  76
  77 ~M-p~ (=ivy-previous-history-element=) select the previous history
  78 element.
  79
  80 ~C-r~ (=ivy-reverse-i-search=) start a recursive completion session to
  81 select a history element.
  82
  83 ~M-i~ (=ivy-insert-current=) insert the current candidate into the
  84 minibuffer. Useful for copying and renaming files, for example: ~M-i~
  85 to insert the original file name string, edit it, and then ~C-m~ to
  86 complete the renaming.
  87
  88 ~M-j~ (=ivy-yank-word=) insert the sub-word at point into the
  89 minibuffer.
  90
  91 ~S-SPC~ (=ivy-restrict-to-matches=) deletes the current input, and
  92 resets the candidates list to the currently restricted matches. This
  93 is how Ivy provides narrowing in successive tiers.
  94
  95 *** Other key bindings
  96
  97 ~M-w~ (=ivy-kill-ring-save=) copies the selected candidates to the
  98 kill ring; when the region is active, copies the active region.
  99
 100 *** Saving the current completion session to a buffer
 101
 102 ~C-c C-o~ (=ivy-occur=) saves the current candidates to a new buffer;
 103 the list is active in the new buffer.
 104
 105 ~RET~ or ~mouse-1~ in the new buffer calls the appropriate action on
 106 the selected candidate.
 107
 108 Ivy has no limit on the number of active buffers like these.
 109
 110 Ivy takes care of making these buffer names unique. It applies
 111 descriptive names, for example: =*ivy-occur counsel-describe-variable
 112 "function$*=.
 113
 114 *** Global key bindings
 115
 116 =ivy-resume= recalls the state of the completion session just before
 117 its last exit. Useful after an accidental ~C-m~ (=ivy-done=).
 118 Recommended global binding: ~C-c C-r~.
 119
 120 *** Hydra in the minibuffer
 121
 122 ~C-o~ (=hydra-ivy/body=) invokes Hydra menus with key shortcuts.
 123
 124 When in Hydra, ~C-o~ or ~i~ resumes editing.
 125
 126 Hydra reduces key strokes, for example: ~C-n C-n C-n C-n~ is ~C-o
 127 jjjj~ in Hydra. Besides certain shorter keys, Hydra shows useful info
 128 such as case folding and the current action.
 129
 130 Additionally, here are the keys that are otherwise not bound:
 131
 132 - ~<~ and ~>~ adjust the height of the minibuffer.
 133 - ~c~ (=ivy-toggle-calling=) - toggle calling the current action each
 134   time a different candidate is selected.
 135 - ~m~ (=ivy-toggle-fuzzy=) - toggle regex matcher.
 136 - ~w~ and ~s~ scroll the actions list.
 137
 138 Minibuffer editing is disabled when Hydra is active.