Docs: Correct protocol references, examples and generated help

This commit is contained in:
Zhizhen He 2026-10-28 13:24:43 +08:00
parent 78d6839881
commit 1e273aa289
24 changed files with 95 additions and 71 deletions

View file

@ -89,8 +89,11 @@ You can also define a shortcut to switch to the previously active window::
:ac:`nth_window` will focus the nth window for positive numbers (starting from
zero) and the previously active windows for negative numbers.
To switch to the nth OS window, you can define :ac:`nth_os_window`. Only
positive numbers are accepted, starting from one.
To switch to the nth OS window, you can define :ac:`nth_os_window`. Positive
numbers start from one, and numbers larger than the number of OS windows focus
the last one. Negative numbers select previously active OS windows. Zero
refocuses the current or most recently focused OS window, if the window manager
allows applications to grab focus.
.. _detach_window:

View file

@ -82,7 +82,7 @@ These dependencies are needed when building against system libraries only.
Run-time dependencies:
* ``python``
* ``python`` >= 3.12
* ``harfbuzz`` >= 2.2.0
* ``zlib``
* ``libpng``

View file

@ -231,6 +231,9 @@ Detailed list of changes
0.50.0 [future]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Documentation: Correct protocol definitions and examples, configuration and
session examples, and generated option help to match the current behavior.
- Allow docking kitty windows to the edges of other windows or of the tab, for
status bars, file trees, etc. Create them with :code:`launch --type=window-dock`
or :code:`launch --type=tab-dock`, see :ref:`docks`

View file

@ -29,9 +29,9 @@ current configuration by pressing :sc:`debug_config` (:kbd:`⌥+⌘+,` on macOS)
:option:`kitty --config` option or use the :envvar:`KITTY_CONFIG_DIRECTORY`
environment variable. See :option:`kitty --config` for full details.
**Comments** can be added to the config file as lines starting with the ``#``
character. This works only if the ``#`` character is the first character in the
line.
**Comments** can be added to the config file as lines whose first non-whitespace
character is ``#``. Trailing comments after configuration values are not
generally supported.
**Lines can be split** by starting the next line with the ``\`` character.
All leading whitespace and the ``\`` character are removed.

View file

@ -319,12 +319,12 @@ Directives inside a group:
``viewport_pos <x> <y>``
The bottom-left corner of this group's rendering region, expressed as
unit floats in UV coordinates (0,0 = bottom-left of the screen, 1,1 =
top-right). Defaults to ``0 0``. Ignored for the final group, which
always covers the full screen.
top-right). Defaults to ``0 0``. The final group must use this default,
since it always covers the full screen. Non-default values are rejected.
``viewport_size <w> <h>``
The width and height of the rendering region as unit floats. Defaults to
``1 1``. Ignored for the final group.
``1 1``. The final group must use this default; non-default values are rejected.
``output_texture <name>``
Where the group writes its output. The default (``default``) ping-pongs
@ -336,8 +336,9 @@ Directives inside a group:
``animation_start <event>[|<event> …]``
Events that trigger the start of this group's animation. Multiple events
are separated by ``|``. If neither this nor ``animation_toggle`` is
specified the group runs on every frame unconditionally. See *Animation events* below for the full list.
are separated by ``|``. A group with neither this nor ``animation_toggle``
nor ``attach`` runs on every frame unconditionally. See *Animation events*
below for the full list.
``animation_stop <token>[|<token> …]``
When to stop the animation. Tokens are separated by ``|`` and may be:
@ -441,10 +442,11 @@ Directives inside a group:
directives. This is the primary way to build multi-pass effects where
several groups must activate and deactivate together. The first group in
a pipeline cannot use ``attach``. An attached group may also carry its
own ``animation_start`` — in that case it becomes active when *either*
condition is true (its own events or the preceding group being active).
If an attached group has no ``animation_start`` of its own, it mirrors
the preceding group exactly: it activates when that group activates and
own ``animation_start`` or ``animation_toggle`` — in that case it becomes
active when *either* condition is true (its own events or the preceding
group being active). If an attached group has neither ``animation_start``
nor ``animation_toggle`` of its own, it mirrors the preceding group
exactly: it activates when that group activates and
deactivates when that group deactivates, and has the same
``animation_progress`` as that group, so both groups animate in perfect
sync. Its own ``animation_curve``, ``animation_duration`` and
@ -492,9 +494,9 @@ reads from ``t.backbuffer`` and writes somewhere:
* ``output_texture a|b|persist``: the group writes into the named texture
instead, leaving the backbuffer intact for the next group.
Groups that have ``animation_start`` set are skipped entirely when their
animation is not active, saving GPU work. Groups without any
``animation_start`` run on every frame.
Groups with ``animation_start``, ``animation_toggle`` or ``attach`` are skipped
entirely when their animation is not active, saving GPU work. Groups without
any of these directives run on every frame.
**A minimal pipeline** — one shader, event-driven animation::

View file

@ -191,7 +191,7 @@ treat these as being two unique *unidentified* notifications.
To close a previous notification, send::
<OSC> i=<notification id> : p=close ; <terminator>
<OSC> 99 ; i=<notification id> : p=close ; <terminator>
This will close a previous notification with the specified id. If no such
notification exists (perhaps because it was already closed or it was activated)

View file

@ -11,7 +11,7 @@ There is one central escape code used for this protocol, which is of the form::
OSC _dnd_code ; metadata ; payload ST
Here, ``OSC`` is the bytes ``ESC ] (0x1b 0x5b)`` and ST is ``ESC \\ (0x1b 0x5c)``.
Here, ``OSC`` is the bytes ``ESC ] (0x1b 0x5d)`` and ST is ``ESC \\ (0x1b 0x5c)``.
The ``metadata`` is a colon separated list of ``key=value`` pairs.
The final part of the escape code is the payload data, whose meaning depends on the metadata.

View file

@ -190,7 +190,7 @@ message for the file, for example::
Once the client is done reading data for all the files it expects, it
terminates the session with::
→ action=finished id=someid
→ action=finish id=someid
Canceling a session
----------------------
@ -524,6 +524,11 @@ is::
The value of ``bypass`` is of the form ``hash_function_name : hash_value``
(without spaces). Currently, only the SHA256 hash function is supported.
The value is base64 encoded in the serialized ``pw`` field. For the example
above, the serialized fields are::
ac=send;id=mysession;pw=c2hhMjU2OjE5MmJkMjE1OTE1ZWVhYThjMmIyYTRjMGY4Zjg1MTgyNjQ5N2QxMmIzMDAzNmQ4YjViMWI0ZmM0NDExY2FmMmM=
.. warning::
Hashing does not effectively hide the value of the password. So this
functionality should only be used in secure/trusted contexts. While there
@ -564,7 +569,7 @@ the numeralization of the word ``file``.
transmission_type tt enum simple, rsync
id id safe_string A unique-ish value, to avoid collisions
file_id fid safe_string Must be unique per file in a session
bypass pw safe_string hash of the bypass password and the session id
bypass pw base64_string hash of the bypass password and the session id
quiet q integer 0 - verbose, 1 - only errors, 2 - totally silent
mtime mod integer the modification time of file in nanoseconds since the UNIX epoch
permissions prm integer the UNIX file permissions bits
@ -592,7 +597,9 @@ safe_string
integer
A base-10 number composed of the characters ``[0-9]`` with a possible
leading ``-`` sign. When missing the value is zero.
leading ``-`` sign. The default for ``quiet`` is zero. The defaults for
``mtime``, ``permissions`` and ``size`` are ``-1``, meaning unspecified.
Omitted permissions and modification times are not applied to the destination.
base64_string
A base64 encoded UTF-8 string using the standard base64 encoding

View file

@ -92,9 +92,12 @@ Variables that influence kitty behavior
.. envvar:: KITTY_RUNTIME_DIRECTORY
Controls where kitty stores runtime files like sockets. Defaults to
the :code:`XDG_RUNTIME_DIR` environment variable if that is defined
otherwise the run directory inside the kitty cache directory is used.
Controls where kitty stores runtime files like sockets. On macOS, the
default is the native per-user cache directory returned by
:code:`getconf DARWIN_USER_CACHE_DIR`. On other platforms, kitty uses
:code:`XDG_RUNTIME_DIR` if defined, otherwise :file:`/run/user/<uid>` if
accessible, falling back to the :file:`run` directory inside the kitty
cache directory.
.. envvar:: VISUAL
@ -268,7 +271,7 @@ Variables that kitty sets when running child programs
.. envvar:: KITTY_SIMD
Set it to ``128`` to use 128 bit vector registers, ``256`` to use 256 bit
vector registers or any other value to prevent kitty from using SIMD CPU
vector instructions. Warning, this overrides CPU capability detection so
will cause kitty to crash with SIGILL if your CPU does not support the
necessary SIMD extensions.
vector registers, or ``512`` to use AVX-512 on x86-64. Any other value
prevents kitty from using SIMD CPU vector instructions. Warning, this
overrides CPU capability detection so will cause kitty to crash with SIGILL
if your CPU does not support the necessary SIMD extensions.

View file

@ -1307,9 +1307,10 @@ Key Value Default Description
-----------------------------------------------------------
``d`` Single character. ``a`` What to delete.
``(
a, A, c, C, n, N,
i, I, p, P, q, Q, r,
R, x, X, y, Y, z, Z
a, A, c, C, f, F,
n, N, i, I, p, P,
q, Q, r, R, x, X,
y, Y, z, Z
)``.
======= ==================== ========= =================

View file

@ -44,7 +44,7 @@ current cursor position, press :sc:`insert_chosen_file` for files or
:sc:`insert_chosen_directory` for directories. Similarly, to have a file
chosen in a command line, use, for example::
some-command $(kitten choose-files)
some-command "$(kitten choose-files)"
Note that the above may not work in a complicated pipeline as it performs
terminal I/O and needs exclusive access to the tty device while choosing a

View file

@ -71,7 +71,8 @@ provide implementations for some backends as well. Service discovery and
configuring which backend to use happens via the :file:`xdg-desktop-portal`
program, usually found at :file:`/usr/lib/xdg-desktop-portal`.
It can be configured by files in :file:`~/.local/share/xdg-desktop-portal`. See
It can be configured by files in :file:`$XDG_CONFIG_HOME/xdg-desktop-portal`,
which defaults to :file:`~/.config/xdg-desktop-portal`. See
`man portals.conf <https://man.archlinux.org/man/portals.conf.5>`__. The
``kitten desktop-ui enable-portal`` command takes care of the setup for you
automatically. If you want to customize exactly which services to use this
@ -108,7 +109,7 @@ returns a not found error, then some other backend is being used for settings.
Read the ``portals.conf`` man page and run::
/usr/lib/xdg-desktop-portal -r v
/usr/lib/xdg-desktop-portal -r -v
this will output a lot of debug information, which should tell you which
backend is chosen for which service. Read the debug output carefully to

View file

@ -28,7 +28,7 @@ following contents:
.. code:: conf
# Open any file with a fragment in vim, fragments are generated
# by the hyperlink-grep kitten and nothing else so far.
# by ripgrep or the hyperlinked-grep kitten.
protocol file
fragment_matches [0-9]+
action launch --type=overlay --cwd=current vim +${FRAGMENT} -- ${FILE_PATH}
@ -71,11 +71,6 @@ hyperlink=none` will cause the command line to be passed directly to
:command:`rg` so no hyperlinking will be performed. :code:`--kitten hyperlink`
may be specified multiple times.
Hopefully, someday this functionality will make it into some `upstream grep
<https://github.com/BurntSushi/ripgrep/issues/665>`__ program directly removing
the need for this kitten.
.. note::
While you can pass any of ripgrep's command line options to the kitten and
they will be forwarded to :program:`rg`, do not use options that change the

View file

@ -122,8 +122,7 @@ this could be achieved using the ssh kitten with :program:`zsh` and
# If you use other zsh init files add them in a similar manner
# Setup vim to read its config from my-conf/vim
env VIMINIT=$HOME/my-conf/vim/vimrc
env VIMRUNTIME=$HOME/my-conf/vim
env VIMINIT=set runtimepath^=$HOME/my-conf/vim runtimepath+=$HOME/my-conf/vim/after | source $HOME/my-conf/vim/vimrc
copy --dest my-conf/vim .vim
copy --dest my-conf/vim/vimrc .vimrc

View file

@ -187,12 +187,12 @@ define a few extra key bindings in :file:`kitty.conf`::
# Maximize the active window along the horizontal axis (fill full width),
# keeping other windows visible in their vertical positions. Press again to
# restore the original layout.
map ctrl+shift+right layout_action maximize horizontal
map ctrl+alt+right layout_action maximize horizontal
# Maximize the active window along the vertical axis (fill full height),
# keeping other windows visible in their horizontal positions. Press again
# to restore the original layout.
map ctrl+shift+up layout_action maximize vertical
map ctrl+alt+up layout_action maximize vertical
# Equalize all splits so that windows share available space proportionally.
map ctrl+shift+e layout_action equalize

View file

@ -110,9 +110,10 @@ for a list of key names. The name to use is the part after the :code:`XKB_KEY_`
prefix. Note that you can only use an XKB key name for keys that are not known
as kitty keys.
Finally, you can use raw system key codes to map keys, again only for keys that
are not known as kitty keys. To see the system key code for a key, start kitty
with the :option:`kitty --debug-input` option, kitty will output some debug text
Finally, you can use raw system key codes to map keys. These mappings are tried
only when no ordinary key mapping or its allowed fallbacks match the event.
System key codes depend on the platform. To see the system key code for a key,
start kitty with the :option:`kitty --debug-input` option, kitty will output some debug text
for every key event. In that text look for :code:`native_code`, the value
of that becomes the key name in the shortcut. For example:
@ -395,7 +396,7 @@ Now, if you run kitty as:
.. code-block:: sh
kitty -o enabled_layouts=vertical --session <(echo "launch\nlaunch\nlaunch")
kitty -o enabled_layouts=vertical --session <(printf '%s\n' launch launch launch)
Press :kbd:`Ctrl+Shift+F7` to enter the mode and then press the up and
down arrow keys to focus the next/previous window. Press :kbd:`Shift+Up` or

View file

@ -63,8 +63,9 @@ one of:
The sequence of ``CO-ORD TYPE : CO-ORDINATES`` can be repeated any number of
times separated by ``;``. The ``SHAPE`` will be set on the cells indicated by
each such group. For example: ``-1;2:3:4;4:5:6:7:8`` will set the shape ``-1``
at the cell ``(3, 2)`` and in the rectangle ``(6, 5)`` to ``(8, 7)`` inclusive.
each such group. For example: ``1;2:3:4;4:5:6:7:8`` will set block cursors
at the cell ``(4, 3)`` and in the rectangle ``(6, 5)`` to ``(8, 7)`` inclusive,
where each pair is written as ``(x, y)``.
Finally, the ``TRAILER`` terminates the sequence and is the bytes SPACE
(``0x20``) and q (``0x71``).

View file

@ -124,6 +124,11 @@ lines. The various available criteria are:
A shell glob pattern that must match the filename, for example:
``image-??.png``
``path``
A shell glob pattern that must match the entire unquoted URL path, for
example: ``/home/*/projects/*.py``. Both ``file`` and ``path`` matching
ignore case.
.. _launch_actions:

View file

@ -21,8 +21,8 @@ Where ``<ESC>`` is the byte ``0x1b``. The JSON object has the form:
The ``version`` above is an array of the form :code:`[0, 14, 2]`. If you are
developing a standalone client, use the kitty version that you are developing
against. Using a version greater than the version of the kitty instance you are
talking to, will cause a failure.
against. A client whose major and minor version pair is greater than that of
the kitty instance will be rejected. The patch version is not compared.
Set ``no_response`` to ``true`` if you don't want a response from kitty.

View file

@ -56,7 +56,7 @@ easily swap between them, kitty has you covered. You can use the
# Browse and select from the list of known projects defined via goto_session commands
map f7>/ goto_session
# Browse and select from the list of active projects defined via goto_session commands
map f7>/ goto_session --active-only [=no]
map f7>/ goto_session --active-only
# Same as above, but the sessions are listed alphabetically instead of by most recent
map f7>/ goto_session --sort-by=alphabetical
# Browse session files inside a directory and pick one
@ -250,7 +250,7 @@ If you use the :doc:`ssh kitten </kittens/ssh>` to connect to remote computers,
session file, preserving the remote working directory and even the currently
running program on the remote host! Try it, run kitty with::
kitty -o 'map f1 save_as_session --use-foreground-process --relocatable' --session <(echo "layout vertical\nlaunch\nlaunch")
kitty -o 'map f1 save_as_session --use-foreground-process --relocatable' --session <(printf '%s\n' 'layout vertical' launch launch)
Now in both windows, run::

View file

@ -55,7 +55,7 @@ at the specified size. It is an ``OSC`` code of the form::
<OSC> _text_size_code ; metadata ; text <terminator>
Here, ``OSC`` is the bytes ``ESC ] (0x1b 0x5b)``. The ``metadata`` is a colon
Here, ``OSC`` is the bytes ``ESC ] (0x1b 0x5d)``. The ``metadata`` is a colon
separated list of ``key=value`` pairs. The final part of the escape code is the
text which is simply plain text encoded as :ref:`safe_utf8`, the text must be
no longer than ``4096`` bytes. Longer strings than that must be broken up into
@ -364,7 +364,7 @@ The algorithm for splitting text into cells
are brought to light in that discussion, there may be small changes to the
algorithm to address them. Additionally, in the future if the Unicode standard
changes in ways that affect this algorithm, it will be updated. Currently the
algorithm is based on Unicode version 16.
algorithm is based on Unicode version 17.
Here, we specify how a terminal must split up text into cells, where a cell is
a width one unit in the character grid the terminal displays.
@ -377,15 +377,15 @@ fully specify text handling for terminals. The full algorithm is specified below
A terminal using this algorithm must decode the bytes they receive
into Unicode scalar values (i.e., code points except surrogates) using UTF-8.
When it encounters any UTF-8 ill-formed subsequences,
it must be replace each
`maximal subpart of the ill-formed subsequence <https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-3/#G66453>`__
it must replace each
`maximal subpart of the ill-formed subsequence <https://www.unicode.org/versions/Unicode17.0.0/core-spec/chapter-3/#G66453>`__
with a :code:`U+FFFD REPLACEMENT CHARACTER` (<28>).
For each decoded code point:
#. First check if the code point is an ASCII control code, and handle it
appropriately. ASCII control codes are the code points less than :code:`U+0032` and the
code point :code:`U+0127 DEL`. The code point :code:`U+0000 NUL` must be discarded.
appropriately. ASCII control codes are the code points less than :code:`U+0020` and the
code point :code:`U+007F DEL`. The code point :code:`U+0000 NUL` must be discarded.
#. Next, check if the code point is *invalid*, and if it is, discard it
and finish processing. Invalid code points are code points with Unicode category :code:`Cc or Cs`
@ -453,7 +453,7 @@ described by the rules below, in order of decreasing priority:
All code points in :code:`RGI_Emoji_Flag_Sequence` have width two.
#. *Marks*: These are all zero width code points. They are code points with Unicode
categories whose first letter is :code:`M` or :code:`S`. Additionally,
categories whose first letter is :code:`M`. Additionally,
code points with Unicode category: :code:`Cf`. Finally, they include
all modifier code points from :code:`RGI_Emoji_Modifier_Sequence` in the
*Wide emoji* rule above.
@ -474,14 +474,14 @@ When adding a code point to the previous cell these have to be handled specially
When the previous cell is two cells wide, its width was not set explicitly using
the ``w`` key of this protocol, and the last code point in the previous
cell is one of the ``Basic_Emoji`` code points from the *Wide emoji* rule above
that is *not* followed by ``FEOF`` then the width of the previous cell is
that is *not* followed by ``FE0F`` then the width of the previous cell is
decreased to one.
``U+FE0F`` - Variation Selector 16
When the previous cell is a single, unscaled cell whose width was not set
explicitly using the ``w`` key of this protocol, and the last code point in the
previous cell is one of the ``Basic_Emoji`` code points from the *Wide emoji*
rule above that is followed by ``FEOF`` then the width of the
rule above that is followed by ``FE0F`` then the width of the
previous cell is increased to two.
In all three of these cases the width the application requested with the ``w`` key
@ -516,7 +516,7 @@ is such a function in the Python language:
yield graphemes[0].text
for i in range(1, len(graphemes)):
g = graphemes[i]
if g is graphemes[-1]:
if i == len(graphemes) - 1:
prev_g = graphemes[i-1]
yield f'\x1b[{prev_g.width}D' # move cursor back
yield g.text
@ -524,6 +524,8 @@ is such a function in the Python language:
yield f'\x1b[{prev_g.width}@' # insert cells
yield prev_g.text
yield f'\x1b[{g.width}C' # move cursor forward
else:
yield g.text
Then, using ``wcswidth()`` the application can split long text into lines of
width no more than the screen width and use the above function to write each

View file

@ -68,9 +68,10 @@ gamut mapping algorithm:
- Uses perceptual color difference (deltaE OK) to minimize visible changes
- Maximizes color saturation while staying in gamut
This ensures that wide gamut colors gracefully degrade on standard sRGB displays while
taking full advantage of wide gamut displays when available. The mapping happens
automatically - you don't need to do anything special.
Colors specified in these formats are converted to 8-bit sRGB values when
parsed, regardless of the display's color gamut. This mapping does not preserve
colors outside sRGB for wide gamut displays. On macOS, :opt:`macos_colorspace`
separately controls how the resulting RGB values are interpreted.
For example, :code:`oklch(0.7 0.4 25)` might be too saturated for sRGB but will be
automatically adjusted to fit while preserving the perceived hue and lightness.

View file

@ -35,7 +35,7 @@ When copying to clipboard both the original and alias are made available on the
clipboard. When copying from clipboard if the original is not found, the alias
is used, as a fallback. Can be specified multiple times to create multiple
aliases. For example: :code:`--alias text/plain=text/x-rst` makes :code:`text/plain` an alias
of :code:`text/rst`. Aliases are not used in filter mode. An alias for
of :code:`text/x-rst`. Aliases are not used in filter mode. An alias for
:code:`text/plain` is automatically created if :code:`text/plain` is not present in the input data, but some
other :code:`text/*` MIME is present.

View file

@ -3781,7 +3781,7 @@ application wide: kitty's own keyboard shortcuts, :opt:`kitty_mod`,
:code:`mouse_map` and the keys sent to the program running in the terminal all
see the remapped modifier. Every mapping in :file:`kitty.conf` is therefore
written in terms of the modifier a key *becomes*, not the one printed on the
keycap — including the built-in shortcuts, so :code:`remap_modifiers ctrl super`
keycap — including the built-in shortcuts, so :code:`remap_modifiers super:ctrl`
moves every default :code:`ctrl+shift+…` binding onto the physical Super key
unless you also change :opt:`kitty_mod`.