You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
See the changelog additions for user-visible changes.
Since we enable/disable terminal protocols whenever we pass terminal ownership,
tests can no longer run in parallel on the same terminal.
For the same reason, readline shortcuts in the gdb REPL will not work anymore.
As a remedy, use gdbserver, or lobby for CSI u support in libreadline.
Add sleep to some tests, otherwise they fall (both in CI and locally).
There are two weird failures on FreeBSD remaining, disable them for now
https://github.com/fish-shell/fish-shell/pull/10359/checks?check_run_id=23330096362
Design and implementation borrows heavily from Kakoune.
In future, we should try to implement more of the kitty progressive
enhancements.
Closes#10359
The entirety of fish's C++ code has been ported to Rust (:issue:`9512`).
18
18
This means a large change in dependencies and how to build fish.
@@ -21,6 +21,24 @@ Packagers should see the :ref:`For Distributors <rust-packaging>` section at the
21
21
Notable backwards-incompatible changes
22
22
--------------------------------------
23
23
24
+
- Fish now decodes keyboard input into human-readable key names.
25
+
To make this for for a wide range of terminals, fish asks terminals to speak several keyboard protocols,
26
+
including CSI u, XTerm's ``modifyOtherKeys`` and some progressive enhancements from the [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/).
27
+
Depending on terminal support, this allows to bind a lot more key combinations,
28
+
including arbitrary combinations of modifiers ``ctrl``, ``alt`` and ``shift``.
29
+
30
+
This comes with a new syntax for specifying keys to builtin ``bind``.
31
+
The new syntax introduces modifier names and names for some keys that don't have an obvious and printable Unicode code point.
32
+
The old syntax remains mostly supported but the new one is preferred.
33
+
- Existing bindings that use the new names have a different meaning now.
34
+
For example
35
+
- ``bind up 'do something'`` binds the up arrow key instead of a two-key sequence.
36
+
- ``bind ctrl-x,alt-c 'do something'`` binds a sequence of two keys.
37
+
Since ``,`` and ``-`` act as separators, there are some cases where they need to be written as ``comma`` and ``minus`` respectively.
38
+
- To minimize gratuitous breakage, the key argument to ``bind`` is parsed using the old syntax in two cases:
39
+
- If key starts with a raw escape character (``\e``) or a raw ASCII control character (``\c``).
40
+
- If key consists of exactly two characters, contains none of ``,`` or ``-`` and is not a named key.
41
+
24
42
- ``random`` now uses a different random number generator and so the values you get even with the same seed have changed.
25
43
Notably, it will now work much more sensibly with very small seeds.
26
44
The seed was never guaranteed to give the same result across systems,
- New function ``fish_should_add_to_history`` can be overridden to decide whether a command should be added to the history (:issue:`10302`).
42
-
- :kbd:`Control-C` during command input no longer prints ``^C`` and a new prompt but merely clears the command line. This restores the behavior from version 2.2. To revert to the old behavior use ``bind \cc __fish_cancel_commandline`` (:issue:`10213`).
60
+
- :kbd:`Control-C` during command input no longer prints ``^C`` and a new prompt but merely clears the command line. This restores the behavior from version 2.2. To revert to the old behavior use ``bind ctrl-c __fish_cancel_commandline`` (:issue:`10213`).
43
61
- The :kbd:`Control-R` history search now uses glob syntax (:issue:`10131`).
44
62
- The :kbd:`Control-R` history search now operates only on the line at cursor, making it easier to quickly compose a multi-line commandline by recalling previous commands.
45
63
@@ -48,6 +66,12 @@ Deprecations and removed features
48
66
49
67
- ``commandline --tokenize`` (short option ``-o``) has been deprecated in favor of ``commandline --tokens-expanded`` (short option ``-x``) which expands variables and other shell expressions, removing the need to use "eval" in custom completions (:issue:`10212`).
50
68
- A new feature flag, ``remove-percent-self`` (see ``status features``) disables PID expansion of ``%self`` which has been supplanted by ``$fish_pid`` (:issue:`10262`).
69
+
- Specifying key names as terminfo name (``bind -k``) is deprecated and may be removed in a future version.
70
+
- Flow control -- which if enabled by ``stty ixon ixoff`` allows to pause terminal input with ``ctrl-s`` and resume it with ``ctrl-q`` -- now works only while fish is executing an external command.
71
+
- When a terminal pastes text into fish using bracketed paste, fish used to switch to a special ``paste`` bind mode.
72
+
This bind mode has been removed. The behavior on paste is currently not meant to be configurable.
73
+
- When fish is stopped or terminated by a signal that cannot be caught (SIGSTOP or SIGKILL), it may leave the terminal in a state where keypresses with modifiers are sent as CSI u sequences instead of traditional control characters or escape sequecnes (that are recognized by bash/readline). If this happens, you can use the ``reset`` command from ``ncurses`` to restore the terminal state.
74
+
- ``fish_key_reader --verbose`` is now ignored, so it no longer shows raw byte values or timing information. Since fish now decodes keys, this should no longer be necessary.
51
75
52
76
Scripting improvements
53
77
----------------------
@@ -78,13 +102,14 @@ Interactive improvements
78
102
79
103
New or improved bindings
80
104
^^^^^^^^^^^^^^^^^^^^^^^^
81
-
- Bindings can now mix special input functions and shell commands, so ``bind \cg expand-abbr "commandline -i \n"`` works as expected (:issue:`8186`).
105
+
- Bindings can now mix special input functions and shell commands, so ``bind ctrl-g expand-abbr "commandline -i \n"`` works as expected (:issue:`8186`).
82
106
- When the cursor is on a command that resolves to an executable script, :kbd:`Alt-O` will now open that script in your editor (:issue:`10266`).
83
107
- Two improvements to the :kbd:`Alt-E` binding which edits the commandline in an external editor:
84
108
- The editor's cursor position is copied back to fish. This is currently supported for Vim and Kakoune.
85
109
- Cursor position synchronization is only supported for a set of known editors. This has been extended by also resolving aliases. For example use ``complete --wraps my-vim vim`` to synchronize cursors when `EDITOR=my-vim`.
86
110
- ``backward-kill-path-component`` and friends now treat ``#`` as part of a path component (:issue:`10271`).
87
111
- The ``E`` binding in vi mode now correctly handles the last character of the word, by jumping to the next word (:issue:`9700`).
112
+
- If the terminal supports shifted key codes from the [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/), ``shift-enter`` now inserts a newline instead of executing the command line.
88
113
- Vi mode has seen some improvements but continues to suffer from the lack of people working on it.
It can add bindings if given a SEQUENCE of characters to bind to. These should be written as :ref:`fish escape sequences <escapes>`. The most important of these are ``\c`` for the control key, and ``\e`` for escape, and because of historical reasons also the Alt key (sometimes also called "Meta").
22
+
If both ``KEYS`` and ``COMMAND`` are given, ``bind`` adds (or replaces) a binding in ``MODE``.
23
+
If only ``KEYS`` is given, any existing binding in the given ``MODE`` will be printed.
23
24
24
-
For example, :kbd:`Alt`\ +\ :kbd:`W` can be written as ``\ew``, and :kbd:`Control`\ +\ :kbd:`X` (^X) can be written as ``\cx``. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not ``fish``.
25
+
``KEYS`` is a comma-separated list of key names.
26
+
Modifier keys can be specified by prefixing a key name with a combination of ``ctrl-``, ``alt-`` and ``shift-``.
27
+
For example, :kbd:`Alt`\ +\ :kbd:`w` is written as ``alt-w``.
28
+
Key names are case-sensitive; for example ``alt-W`` is the same as ``alt-shift-w``.
25
29
26
-
The generic key binding that matches if no other binding does can be set by specifying a ``SEQUENCE`` of the empty string (``''``). For most key bindings, it makes sense to bind this to the ``self-insert`` function (i.e. ``bind '' self-insert``). This will insert any keystrokes not specifically bound to into the editor. Non-printable characters are ignored by the editor, so this will not result in control sequences being inserted.
30
+
Some keys have names, usually because they don't have an obvious printable character representation.
31
+
They are:
27
32
28
-
If the ``-k`` switch is used, the name of a key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key\_' prefix. (See ``terminfo(5)`` for more information, or use ``bind --key-names`` for a list of all available named keys). Normally this will print an error if the current ``$TERM`` entry doesn't have a given key, unless the ``-s`` switch is given.
33
+
``plus`` (``+``),
34
+
``minus`` (``-``),
35
+
``comma`` (``,``),
36
+
``backspace``,
37
+
``delete``,
38
+
``escape``,
39
+
``enter``,
40
+
the arrow keys ``up``, ``down``, ``left`` and ``right``,
41
+
``pageup``,
42
+
``pagedown``,
43
+
``home``,
44
+
``end``,
45
+
``insert``,
46
+
``tab``,
47
+
``space`` and
48
+
``F1`` through ``F12``.
29
49
30
-
To find out what sequence a key combination sends, you can use :doc:`fish_key_reader <fish_key_reader>`.
50
+
An empty value (``''``) for ``KEYS`` designates the generic binding. For most bind modes, it makes sense to bind this to the ``self-insert`` function (i.e. ``bind '' self-insert``). This will insert any keystrokes not specifically bound to into the editor. Non-printable characters are ignored by the editor, so this will not result in control sequences being inserted.
51
+
52
+
To find the name of a key combination you can use :doc:`fish_key_reader <fish_key_reader>`.
31
53
32
54
``COMMAND`` can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use ``bind --function-names`` or :ref:`see below <special-input-functions>` for a list of these input functions.
33
55
34
56
.. note::
35
57
If a script changes the commandline, it should finish by calling the ``repaint`` special input function.
36
58
37
-
If no ``SEQUENCE`` is provided, all bindings (or just the bindings in the given ``MODE``) are printed. If ``SEQUENCE`` is provided but no ``COMMAND``, just the binding matching that sequence is printed.
59
+
If no ``KEYS`` argument is provided, all bindings (in the given ``MODE``) are printed. If ``KEYS`` is provided but no ``COMMAND``, just the binding matching that sequence is printed.
38
60
39
61
Key bindings may use "modes", which mimics vi's modal input behavior. The default mode is "default". Every key binding applies to a single mode; you can specify which one with ``-M MODE``. If the key binding should change the mode, you can specify the new mode with ``-m NEW_MODE``. The mode can be viewed and changed via the ``$fish_bind_mode`` variable. If you want to change the mode from inside a fish function, use ``set fish_bind_mode MODE``.
40
62
63
+
To bind a sequence of keys, separate them with ``,``.
64
+
41
65
To save custom key bindings, put the ``bind`` statements into :ref:`config.fish <configuration>`. Alternatively, fish also automatically executes a function called ``fish_user_key_bindings`` if it exists.
42
66
43
67
Options
44
68
-------
45
69
The following options are available:
46
70
47
-
**-k** or **--key**
48
-
Specify a key name, such as 'left' or 'backspace' instead of a character sequence
49
-
50
-
**-K** or **--key-names**
51
-
Display a list of available key names. Specifying **-a** or **--all** includes keys that don't have a known mapping
52
-
53
71
**-f** or **--function-names**
54
72
Display a list of available input functions
55
73
@@ -69,7 +87,7 @@ The following options are available:
69
87
Specifying **-a** or **--all** without **-M** or **--mode** erases all binds in all modes regardless of sequence.
70
88
71
89
**-a** or **--all**
72
-
See **--erase** and **--key-names**
90
+
See **--erase**
73
91
74
92
**--preset** and **--user**
75
93
Specify if bind should operate on user or preset bindings.
@@ -349,7 +367,7 @@ Examples
349
367
350
368
Exit the shell when :kbd:`Control`\ +\ :kbd:`D` is pressed::
351
369
352
-
bind \cd 'exit'
370
+
bind ctrl-d 'exit'
353
371
354
372
Perform a history search when :kbd:`Page Up` is pressed::
Copy file name to clipboardExpand all lines: doc_src/cmds/fish_key_reader.rst
+1-16Lines changed: 1 addition & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,16 +15,11 @@ Description
15
15
16
16
:program:`fish_key_reader` is used to explain how you would bind a certain key sequence. By default, it prints the :doc:`bind <bind>` command for one key sequence read interactively over standard input.
17
17
18
-
If the character sequence matches a special key name (see ``bind --key-names``), both ``bind CHARS ...`` and ``bind -k KEYNAME ...`` usage will be shown. In verbose mode (enabled by passing ``--verbose``), additional details about the characters received, such as the delay between chars, are written to standard error.
19
-
20
18
The following options are available:
21
19
22
20
**-c** or **--continuous**
23
21
Begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence.
24
22
25
-
**-V** or **--verbose**
26
-
Tells fish_key_reader to output timing information and explain the sequence in more detail.
27
-
28
23
**-h** or **--help**
29
24
Displays help about using this command.
30
25
@@ -34,8 +29,6 @@ The following options are available:
34
29
Usage Notes
35
30
-----------
36
31
37
-
In verbose mode, the delay in milliseconds since the previous character was received is included in the diagnostic information written to standard error. This information may be useful to determine the optimal ``fish_escape_delay_ms`` setting or learn the amount of lag introduced by tools like ``ssh``, ``mosh`` or ``tmux``.
38
-
39
32
``fish_key_reader`` intentionally disables handling of many signals. To terminate ``fish_key_reader`` in ``--continuous`` mode do:
0 commit comments