diff options
| author | Michelle Tilley <michelle@michelletilley.net> | 2026-02-11 12:25:52 -0800 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-02-11 12:25:52 -0800 |
| commit | 05ffb902161e6d2111efe70a7bc488cfc550ff21 (patch) | |
| tree | 0d0b1c7c4670236de8fea375cf619bee0d9618be /docs | |
| parent | fix(tui): enter in vim normal mode, shift-tab keybind (#3158) (diff) | |
| download | atuin-05ffb902161e6d2111efe70a7bc488cfc550ff21.zip | |
feat: expand keybinding system with vim motions, media keys, and inspector improvements (#3161)
Addresses the keybinding audit (#3157):
- Add missing vim-normal bindings: 0, $, w, b, e, x, dd, D, C
- Add new CursorWordEnd action for vim 'e' motion
- Add VimChangeToEnd action for vim 'C' motion
- Add Media key support (play, pause, stop, volume, etc.)
- Refactor inspector keymap to be minimal but respect enter_accept
and provide vim-style j/k navigation for vim users
- Add $ to special character parsing
- Replace eprintln! with tracing::warn! for config errors
- Document shifted punctuation keys and media keys
To be rebased once #3158 is merged
Diffstat (limited to '')
| -rw-r--r-- | docs/docs/configuration/advanced-key-binding.md | 31 | ||||
| -rw-r--r-- | docs/docs/configuration/key-binding.md | 30 |
2 files changed, 52 insertions, 9 deletions
diff --git a/docs/docs/configuration/advanced-key-binding.md b/docs/docs/configuration/advanced-key-binding.md index 9183ca8b..5027c5a2 100644 --- a/docs/docs/configuration/advanced-key-binding.md +++ b/docs/docs/configuration/advanced-key-binding.md @@ -69,7 +69,34 @@ An uppercase letter represents itself without needing a `shift` modifier. For ex Some special characters are written out directly: ``` -"?", "/", "[", "]" +"?", "/", "[", "]", "$" +``` + +### Shifted and punctuation keys + +When you press a key like `Shift+1`, your terminal sends the resulting character (`!`) rather than "shift-1". To bind shifted punctuation keys, use the character directly: + +```toml +[keymap.emacs] +"!" = "some-action" # Binds to Shift+1 +"@" = "some-action" # Binds to Shift+2 +"#" = "some-action" # Binds to Shift+3 +"$" = "cursor-end" # Binds to Shift+4 (vim $ motion) +``` + +Any single character can be used as a key binding. + +!!! note + The `shift` modifier is still valid for non-character keys like `"shift-tab"` or `"shift-up"`. + +### Media keys + +Media keys are supported on terminals that implement the kitty keyboard protocol with `DISAMBIGUATE_ESCAPE_CODES` enabled: + +``` +"play", "pause", "playpause", "stop" +"fastforward", "rewind", "tracknext", "trackprevious" +"record", "lowervolume", "raisevolume", "mutevolume", "mute" ``` ### Multi-key sequences @@ -127,6 +154,7 @@ Actions are specified as kebab-case strings. | `cursor-right` | Move cursor one character right | | `cursor-word-left` | Move cursor one word left | | `cursor-word-right` | Move cursor one word right | +| `cursor-word-end` | Move cursor to end of current/next word (vim `e` motion) | | `cursor-start` | Move cursor to start of line | | `cursor-end` | Move cursor to end of line | @@ -191,6 +219,7 @@ The difference between `accept` and `return-selection`: `accept` runs the comman | `vim-enter-insert-at-start` | Move to start of line and enter vim insert mode (like vim `I`) | | `vim-enter-insert-at-end` | Move to end of line and enter vim insert mode (like vim `A`) | | `vim-search-insert` | Clear the search input and enter vim insert mode (like vim `?` or `/`) | +| `vim-change-to-end` | Delete to end of line and enter vim insert mode (like vim `C`) | | `enter-prefix-mode` | Enter prefix mode (waits for one more key, e.g. `d` for delete) | ### Inspector diff --git a/docs/docs/configuration/key-binding.md b/docs/docs/configuration/key-binding.md index b3ae7aa2..f292999f 100644 --- a/docs/docs/configuration/key-binding.md +++ b/docs/docs/configuration/key-binding.md @@ -238,6 +238,15 @@ If [vim is enabled in the config](config.md#keymap_mode), the following keybindi | j | Normal | Selects the previous item on the list | | h | Normal | Move cursor left | | l | Normal | Move cursor right | +| 0 | Normal | Move cursor to start of line | +| $ | Normal | Move cursor to end of line | +| w | Normal | Move cursor to next word | +| b | Normal | Move cursor to previous word | +| e | Normal | Move cursor to end of current/next word | +| x | Normal | Delete character under cursor | +| dd | Normal | Clear the entire line | +| D | Normal | Delete to end of line | +| C | Normal | Delete to end of line and enter insert | | i | Normal | Enters insert mode | | I | Normal | Move to start of line and enter insert | | a | Normal | Move right and enter insert mode | @@ -253,17 +262,22 @@ If [vim is enabled in the config](config.md#keymap_mode), the following keybindi | L | Normal | Jump to bottom of visible screen | | ? or / | Normal | Clear input and enter insert mode | | 1-9 | Normal | Select item by number | +| enter | Normal | Execute selected item (respects enter_accept) | | Esc | Insert | Enters normal mode | ### Inspector Open the inspector with ctrl + o -| Shortcut | Action | -| -------- | --------------------------------------------- | -| Esc | Close the inspector, returning to the shell | -| ctrl + o | Close the inspector, returning to search view | -| ctrl + d | Delete the inspected item from the history | -| ↑ | Inspect the previous item in the history | -| ↓ | Inspect the next item in the history | -| tab | Select current item and edit | +| Shortcut | Action | +| --------- | --------------------------------------------- | +| Esc | Close the inspector, returning to the shell | +| ctrl + o | Close the inspector, returning to search view | +| ctrl + d | Delete the inspected item from the history | +| ↑ | Inspect the previous item in the history | +| ↓ | Inspect the next item in the history | +| page up | Inspect the previous item in the history | +| page down | Inspect the next item in the history | +| j / k | Navigate items (when vim mode is enabled) | +| enter | Execute selected item (respects enter_accept) | +| tab | Select current item and edit | |
