stow/oh-my-zsh/.oh-my-zsh/plugins/vi-mode/README.md

   1 # vi-mode plugin
   2
   3 This plugin increase `vi-like` zsh functionality.
   4
   5 To use it, add `vi-mode` to the plugins array in your zshrc file:
   6
   7 ```zsh
   8 plugins=(... vi-mode)
   9 ```
  10
  11 ## Settings
  12
  13 - `VI_MODE_RESET_PROMPT_ON_MODE_CHANGE`: controls whether the prompt is redrawn when
  14   switching to a different input mode. If this is unset, the mode indicator will not
  15   be updated when changing to a different mode.
  16   Set it to `true` to enable it. For example:
  17
  18   ```zsh
  19   VI_MODE_RESET_PROMPT_ON_MODE_CHANGE=true
  20   ```
  21
  22   The default value is unset, unless `vi_mode_prompt_info` is used, in which case it'll
  23   automatically be set to `true`.
  24
  25 - `VI_MODE_SET_CURSOR`: controls whether the cursor style is changed when switching
  26   to a different input mode. Set it to `true` to enable it (default: unset):
  27
  28   ```zsh
  29   VI_MODE_SET_CURSOR=true
  30   ```
  31
  32 - `MODE_INDICATOR`: controls the string displayed when the shell is in normal mode.
  33   See [Mode indicators](#mode-indicators) for details.
  34
  35 - `INSERT_MODE_INDICATOR`: controls the string displayed when the shell is in insert mode.
  36   See [Mode indicators](#mode-indicators) for details.
  37
  38 ## Mode indicators
  39
  40 *Normal mode* is indicated with a red `<<<` mark at the right prompt, when it
  41 hasn't been defined by theme, *Insert mode* is not displayed by default.
  42
  43 You can change these indicators by setting the `MODE_INDICATOR` (*Normal mode*) and
  44 `INSERT_MODE_INDICATORS` (*Insert mode*) variables.
  45 This settings support Prompt Expansion sequences. For example:
  46
  47 ```zsh
  48 MODE_INDICATOR="%F{white}+%f"
  49 INSERT_MODE_INDICATOR="%F{yellow}+%f"
  50 ```
  51
  52 You can also use the `vi_mode_prompt_info` function in your prompt, which will display
  53 this mode indicator.
  54
  55 ## Key bindings
  56
  57 Use `ESC` or `CTRL-[` to enter `Normal mode`.
  58
  59 NOTE: some of these key bindings are set by zsh by default when using a vi-mode keymap.
  60
  61 ### History
  62
  63 - `ctrl-p` : Previous command in history
  64 - `ctrl-n` : Next command in history
  65 - `/`      : Search backward in history
  66 - `n`      : Repeat the last `/`
  67
  68 ### Vim edition
  69
  70 - `vv`     : Edit current command line in Vim
  71
  72 NOTE: this used to be bound to `v`. That is now the default (`visual-mode`).
  73
  74 ### Movement
  75
  76 - `$`   : To the end of the line
  77 - `^`   : To the first non-blank character of the line
  78 - `0`   : To the first character of the line
  79 - `w`   : [count] words forward
  80 - `W`   : [count] WORDS forward
  81 - `e`   : Forward to the end of word [count] inclusive
  82 - `E`   : Forward to the end of WORD [count] inclusive
  83 - `b`   : [count] words backward
  84 - `B`   : [count] WORDS backward
  85 - `t{char}`   : Till before [count]'th occurrence of {char} to the right
  86 - `T{char}`   : Till before [count]'th occurrence of {char} to the left
  87 - `f{char}`   : To [count]'th occurrence of {char} to the right
  88 - `F{char}`   : To [count]'th occurrence of {char} to the left
  89 - `;`   : Repeat latest f, t, F or T [count] times
  90 - `,`   : Repeat latest f, t, F or T in opposite direction
  91
  92 ### Insertion
  93
  94 - `i`   : Insert text before the cursor
  95 - `I`   : Insert text before the first character in the line
  96 - `a`   : Append text after the cursor
  97 - `A`   : Append text at the end of the line
  98 - `o`   : Insert new command line below the current one
  99 - `O`   : Insert new command line above the current one
 100
 101 ### Delete and Insert
 102
 103 - `ctrl-h`      : While in *Insert mode*: delete character before the cursor
 104 - `ctrl-w`      : While in *Insert mode*: delete word before the cursor
 105 - `d{motion}`   : Delete text that {motion} moves over
 106 - `dd`          : Delete line
 107 - `D`           : Delete characters under the cursor until the end of the line
 108 - `c{motion}`   : Delete {motion} text and start insert
 109 - `cc`          : Delete line and start insert
 110 - `C`           : Delete to the end of the line and start insert
 111 - `r{char}`     : Replace the character under the cursor with {char}
 112 - `R`           : Enter replace mode: Each character replaces existing one
 113 - `x`           : Delete `count` characters under and after the cursor
 114 - `X`           : Delete `count` characters before the cursor
 115
 116 ## Known issues
 117
 118 ### Low `$KEYTIMEOUT`
 119
 120 A low `$KEYTIMEOUT` value (< 15) means that key bindings that need multiple characters,
 121 like `vv`, will be very difficult to trigger. `$KEYTIMEOUT` controls the number of
 122 milliseconds that must pass before a key press is read and the appropriate key binding
 123 is triggered. For multi-character key bindings, the key presses need to happen before
 124 the timeout is reached, so on low timeouts the key press happens too slow, and therefore
 125 another key binding is triggered.
 126
 127 We recommend either setting `$KEYTIMEOUT` to a higher value, or remapping the key bindings
 128 that you want to trigger to a keyboard sequence. For example:
 129
 130 ```zsh
 131 bindkey -M vicmd 'V' edit-command-line # this remaps `vv` to `V` (but overrides `visual-mode`)
 132 ```