From 93ad3a88214b95f571e03c21f7d9bd76f9110938 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Cornell=C3=A0?= Date: Mon, 27 Sep 2021 11:46:42 +0200 Subject: [PATCH] docs(vi-mode): document `$KEYTIMEOUT` issue (#9588) Closes #9588 --- plugins/vi-mode/README.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/plugins/vi-mode/README.md b/plugins/vi-mode/README.md index b59d5f279..46bb6d070 100644 --- a/plugins/vi-mode/README.md +++ b/plugins/vi-mode/README.md @@ -64,7 +64,7 @@ NOTE: some of these key bindings are set by zsh by default when using a vi-mode - `vv` : Edit current command line in Vim -NOTE: this used to be bound to `v`. That is now the default (`visual-mode`) +NOTE: this used to be bound to `v`. That is now the default (`visual-mode`). ### Movement @@ -107,3 +107,21 @@ NOTE: this used to be bound to `v`. That is now the default (`visual-mode`) - `R` : Enter replace mode: Each character replaces existing one - `x` : Delete `count` characters under and after the cursor - `X` : Delete `count` characters before the cursor + +## Known issues + +### Low `$KEYTIMEOUT` + +A low `$KEYTIMEOUT` value (< 15) means that key bindings that need multiple characters, +like `vv`, will be very difficult to trigger. `$KEYTIMEOUT` controls the number of +milliseconds that must pass before a key press is read and the appropriate key binding +is triggered. For multi-character key bindings, the key presses need to happen before +the timeout is reached, so on low timeouts the key press happens too slow, and therefore +another key binding is triggered. + +We recommend either setting `$KEYTIMEOUT` to a higher value, or remapping the key bindings +that you want to trigger to a keyboard sequence. For example: + +```zsh +bindkey -M vicmd 'V' edit-command-line # this remaps `vv` to `V` (but overrides `visual-mode`) +```