Merge branch 'docs' of https://github.com/page-down/kitty
This commit is contained in:
Kovid Goyal
commit
99409f0a8b
@ -1,12 +1,13 @@
|
||||
Tabs and Windows
|
||||
-------------------
|
||||
|
||||
|kitty| is capable of running multiple programs organized into tabs and
|
||||
windows. The top level of organization is the *Tab*. Each tab consists
|
||||
of one or more *windows*. The windows can be arranged in multiple
|
||||
different layouts, like windows are organized in a tiling window
|
||||
manager. The keyboard controls (which are all customizable) for tabs and
|
||||
windows are:
|
||||
|kitty| is capable of running multiple programs organized into tabs and windows.
|
||||
The top level of organization is the :term:`OS window <os_window>`. Each OS
|
||||
window consists of one or :term:`tabs <tab>`. Each tab consists of one or more
|
||||
:term:`kitty windows <window>`. The kitty windows can be arranged in multiple
|
||||
different :term:`layouts <layout>`, like windows are organized in a tiling
|
||||
window manager. The keyboard controls (which are :ref:`all customizable
|
||||
<conf-kitty-shortcuts>`) for tabs and windows are:
|
||||
|
||||
Scrolling
|
||||
~~~~~~~~~~~~~~
|
||||
@ -64,8 +65,9 @@ Focus specific window :sc:`first_window`, :sc:`second_window` ... :sc:`ten
|
||||
(clockwise from the top-left)
|
||||
======================== =======================
|
||||
|
||||
Additionally, you can define shortcuts in :file:`kitty.conf` to focus neighboring
|
||||
windows and move windows around (similar to window movement in vim)::
|
||||
Additionally, you can define shortcuts in :file:`kitty.conf` to focus
|
||||
neighboring windows and move windows around (similar to window movement in
|
||||
:program:`vim`)::
|
||||
|
||||
map ctrl+left neighboring_window left
|
||||
map shift+left move_window right
|
||||
@ -77,20 +79,20 @@ You can also define a shortcut to switch to the previously active window::
|
||||
|
||||
map ctrl+p nth_window -1
|
||||
|
||||
``nth_window`` will focus the nth window for positive numbers (starting from
|
||||
: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 ``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`. Only
|
||||
positive numbers are accepted, starting from one.
|
||||
|
||||
.. _detach_window:
|
||||
|
||||
You can define shortcuts to detach the current window and
|
||||
move it to another tab or another OS window::
|
||||
You can define shortcuts to detach the current window and move it to another tab
|
||||
or another OS window::
|
||||
|
||||
# moves the window into a new OS window
|
||||
map ctrl+f2 detach_window
|
||||
# moves the window into a new Tab
|
||||
# moves the window into a new tab
|
||||
map ctrl+f3 detach_window new-tab
|
||||
# moves the window into the previously active tab
|
||||
map ctrl+f3 detach_window tab-prev
|
||||
@ -106,8 +108,8 @@ Similarly, you can detach the current tab, with::
|
||||
# asks which OS Window to move the tab into
|
||||
map ctrl+f4 detach_tab ask
|
||||
|
||||
Finally, you can define a shortcut to close all windows in a tab other than
|
||||
the currently active window::
|
||||
Finally, you can define a shortcut to close all windows in a tab other than the
|
||||
currently active window::
|
||||
|
||||
map f9 close_other_windows_in_tab
|
||||
|
||||
@ -124,18 +126,18 @@ Action Shortcut
|
||||
Copy to clipboard :sc:`copy_to_clipboard` (also :kbd:`⌘+c` on macOS)
|
||||
Paste from clipboard :sc:`paste_from_clipboard` (also :kbd:`⌘+v` on macOS)
|
||||
Paste from selection :sc:`paste_from_selection`
|
||||
Pass selection to program :sc:`pass_selection_to_program`
|
||||
Increase font size :sc:`increase_font_size` (also :kbd:`⌘++` on macOS)
|
||||
Decrease font size :sc:`decrease_font_size` (also :kbd:`⌘+-` on macOS)
|
||||
Restore font size :sc:`reset_font_size` (also :kbd:`⌘+0` on macOS)
|
||||
Toggle fullscreen :sc:`toggle_fullscreen` (also :kbd:`⌃+⌘+f` on macOS)
|
||||
Toggle maximized :sc:`toggle_maximized`
|
||||
Input unicode character :sc:`input_unicode_character` (also :kbd:`⌃+⌘+space` on macOS)
|
||||
Input Unicode character :sc:`input_unicode_character` (also :kbd:`⌃+⌘+space` on macOS)
|
||||
Open URL in web browser :sc:`open_url`
|
||||
Reset the terminal :sc:`reset_terminal` (also :kbd:`⌥+⌘+r` on macOS)
|
||||
Edit :file:`kitty.conf` :sc:`edit_config_file` (also :kbd:`⌘+,` on macOS)
|
||||
Reload :file:`kitty.conf` :sc:`reload_config_file` (also :kbd:`⌃+⌘+,` on macOS)
|
||||
Debug :file:`kitty.conf` :sc:`debug_config` (also :kbd:`⌥+⌘+,` on macOS)
|
||||
Pass current selection to program :sc:`pass_selection_to_program`
|
||||
Edit |kitty| config file :sc:`edit_config_file` (also :kbd:`⌘+,` on macOS)
|
||||
Open a |kitty| shell :sc:`kitty_shell`
|
||||
Increase background opacity :sc:`increase_background_opacity`
|
||||
Decrease background opacity :sc:`decrease_background_opacity`
|
||||
|
||||
@ -21,7 +21,7 @@ simply re-run the command.
|
||||
|
||||
.. warning::
|
||||
**Do not** copy the kitty binary out of the installation folder. If you want
|
||||
to add it to your ``PATH`` create a symlink in :file:`~/.local/bin` or
|
||||
to add it to your :envvar:`PATH`, create a symlink in :file:`~/.local/bin` or
|
||||
:file:`/usr/bin` or wherever.
|
||||
|
||||
|
||||
@ -30,11 +30,12 @@ Manually installing
|
||||
|
||||
If something goes wrong or you simply do not want to run the installer, you can
|
||||
manually download and install |kitty| from the `GitHub releases page
|
||||
<https://github.com/kovidgoyal/kitty/releases>`_. If you are on macOS, download
|
||||
the :file:`.dmg` and install as normal. If you are on Linux, download the tarball
|
||||
and extract it into a directory. The |kitty| executable will be in the
|
||||
<https://github.com/kovidgoyal/kitty/releases>`__. If you are on macOS, download
|
||||
the :file:`.dmg` and install as normal. If you are on Linux, download the
|
||||
tarball and extract it into a directory. The |kitty| executable will be in the
|
||||
:file:`bin` sub-directory.
|
||||
|
||||
|
||||
Desktop integration on Linux
|
||||
--------------------------------
|
||||
|
||||
@ -57,9 +58,19 @@ particular desktop, but it should work for most major desktop environments.
|
||||
sed -i "s|Exec=kitty|Exec=/home/$USER/.local/kitty.app/bin/kitty|g" ~/.local/share/applications/kitty*.desktop
|
||||
|
||||
.. note::
|
||||
If you use the venerable `stow <https://www.gnu.org/software/stow/>`_
|
||||
In :file:`kitty-open.desktop`, kitty is registered to handle some supported
|
||||
MIME types. This will cause kitty to take precedence on some systems where
|
||||
the default apps are not explicitly set. For example, you expect to use
|
||||
other GUI file managers to open dir paths when using commands such as
|
||||
:program:`xdg-open`, you should configure the default opener for the MIME
|
||||
type ``inode/directory``::
|
||||
|
||||
xdg-mime default org.kde.dolphin.desktop inode/directory
|
||||
|
||||
.. note::
|
||||
If you use the venerable `stow <https://www.gnu.org/software/stow/>`__
|
||||
command to manage your manual installations, the following takes care of the
|
||||
above for you (use with :file:`dest=~/.local/stow`)::
|
||||
above for you (use with :code:`dest=~/.local/stow`)::
|
||||
|
||||
cd ~/.local/stow
|
||||
stow -v kitty.app
|
||||
|
||||
@ -7,21 +7,21 @@ Build from source
|
||||
|
||||
.. highlight:: sh
|
||||
|
||||
|kitty| is designed to run from source, for easy hack-ability. Make sure
|
||||
the following dependencies are installed first.
|
||||
|kitty| is designed to run from source, for easy hack-ability. Make sure the
|
||||
following dependencies are installed first.
|
||||
|
||||
.. note::
|
||||
If you just want to test the latest changes to kitty you dont need to build
|
||||
If you just want to test the latest changes to kitty, you don't need to build
|
||||
from source. Instead install the :ref:`latest nightly build <nightly>`.
|
||||
|
||||
.. note::
|
||||
If you are making small changes only to the python parts of kitty, there is no need to
|
||||
build kitty at all, instead, assuming you have installed the official kitty
|
||||
binaries, you can simply set the KITTY_DEVELOP_FROM enviroment variable to
|
||||
point to the directory into which you have checked out the kitty source
|
||||
code. kitty will then load its python code from there. You should use a
|
||||
version of the source that matches the binary version as closely as
|
||||
possible, since the two are tightly coupled.
|
||||
If you are making small changes only to the Python parts of kitty, there is
|
||||
no need to build kitty at all, instead, assuming you have installed the
|
||||
official kitty binaries, you can simply set the :envvar:`KITTY_DEVELOP_FROM`
|
||||
enviroment variable to point to the directory into which you have checked out
|
||||
the kitty source code. kitty will then load its Python code from there. You
|
||||
should use a version of the source that matches the binary version as closely
|
||||
as possible, since the two are tightly coupled.
|
||||
|
||||
|
||||
Dependencies
|
||||
@ -46,7 +46,9 @@ Build-time dependencies:
|
||||
|
||||
* ``gcc`` or ``clang``
|
||||
* ``pkg-config``
|
||||
* For building on Linux in addition to the above dependencies you might also need to install the following packages, if they are not already installed by your distro:
|
||||
* For building on Linux in addition to the above dependencies you might also
|
||||
need to install the following packages, if they are not already installed by
|
||||
your distro:
|
||||
|
||||
- ``libdbus-1-dev``
|
||||
- ``libxcursor-dev``
|
||||
@ -77,9 +79,8 @@ You can run |kitty|, as::
|
||||
|
||||
./kitty/launcher/kitty
|
||||
|
||||
If that works, you can create a symlink to the launcher in :file:`~/bin` or
|
||||
some other directory on your PATH so that you can run |kitty| using
|
||||
just ``kitty``.
|
||||
If that works, you can create a symlink to the launcher in :file:`~/bin` or some
|
||||
other directory on your PATH so that you can run |kitty| using just ``kitty``.
|
||||
|
||||
|
||||
Building kitty.app on macOS from source
|
||||
@ -90,25 +91,24 @@ Run::
|
||||
make app
|
||||
|
||||
This :file:`kitty.app` unlike the released one does not include its own copy of
|
||||
python and the other dependencies. So if you ever un-install/upgrade those dependencies
|
||||
you might have to rebuild the app.
|
||||
Python and the other dependencies. So if you ever un-install/upgrade those
|
||||
dependencies you might have to rebuild the app.
|
||||
|
||||
.. note::
|
||||
The released :file:`kitty.dmg` includes all dependencies, unlike the
|
||||
:file:`kitty.app` built above and is built automatically by using the
|
||||
`bypy framework <https://github.com/kovidgoyal/bypy>`_ however, that is
|
||||
`bypy framework <https://github.com/kovidgoyal/bypy>`__ however, that is
|
||||
designed to run on Linux and is not for the faint of heart.
|
||||
|
||||
.. note::
|
||||
Apple disallows certain functionality, such as notifications for unsigned applications.
|
||||
If you need this functionality, you can try signing the built kitty.app with
|
||||
a self signed certificate, see for example, `here
|
||||
<https://stackoverflow.com/questions/27474751/how-can-i-codesign-an-app-without-being-in-the-mac-developer-program/27474942>`_.
|
||||
Apple disallows certain functionality, such as notifications for unsigned
|
||||
applications. If you need this functionality, you can try signing the built
|
||||
:file:`kitty.app` with a self signed certificate, see for example, `here
|
||||
<https://stackoverflow.com/questions/27474751/how-can-i-codesign-an-app-without-being-in-the-mac-developer-program/27474942>`__.
|
||||
|
||||
.. note::
|
||||
If you are facing issues with ``linker`` while building,
|
||||
try with a ``brew`` installed python instead, see :iss:`289`
|
||||
for more discussion.
|
||||
If you are facing issues with ``linker`` while building, try with a ``brew``
|
||||
installed Python instead, see :iss:`289` for more discussion.
|
||||
|
||||
|
||||
Build and run from source with Nix
|
||||
@ -116,13 +116,14 @@ Build and run from source with Nix
|
||||
|
||||
On NixOS or any other Linux or macOS system with the Nix package manager
|
||||
installed, execute `nix-shell
|
||||
<https://nixos.org/guides/nix-pills/developing-with-nix-shell.html>`_ to create
|
||||
<https://nixos.org/guides/nix-pills/developing-with-nix-shell.html>`__ to create
|
||||
the correct environment to build kitty or use ``nix-shell --pure`` instead to
|
||||
eliminate most of the influence of the outside system, e.g. globally installed
|
||||
packages. ``nix-shell`` will automatically fetch all required dependencies and
|
||||
make them available in the newly spawned shell.
|
||||
|
||||
Then proceed with ``make`` or ``make app`` according to the platform specific instructions above.
|
||||
Then proceed with ``make`` or ``make app`` according to the platform specific
|
||||
instructions above.
|
||||
|
||||
|
||||
Debug builds
|
||||
@ -132,7 +133,8 @@ A basic debug build can be done with::
|
||||
|
||||
make debug
|
||||
|
||||
This includes debug info in the binary for better traces. To build with address sanitizer, use::
|
||||
This includes debug info in the binary for better traces. To build with address
|
||||
sanitizer, use::
|
||||
|
||||
make asan
|
||||
|
||||
@ -144,46 +146,45 @@ Notes for Linux/macOS packagers
|
||||
----------------------------------
|
||||
|
||||
The released |kitty| source code is available as a `tarball`_ from
|
||||
`the GitHub releases page <https://github.com/kovidgoyal/kitty/releases>`_.
|
||||
`the GitHub releases page <https://github.com/kovidgoyal/kitty/releases>`__.
|
||||
|
||||
While |kitty| does use python, it is not a traditional python package, so please
|
||||
While |kitty| does use Python, it is not a traditional Python package, so please
|
||||
do not install it in site-packages.
|
||||
Instead run::
|
||||
|
||||
python3 setup.py linux-package
|
||||
|
||||
This will install |kitty| into the directory :file:`linux-package`. You can run |kitty|
|
||||
with :file:`linux-package/bin/kitty`. All the files needed to run kitty will be in
|
||||
:file:`linux-package/lib/kitty`. The terminfo file will be installed into
|
||||
:file:`linux-package/share/terminfo`. Simply copy these files into :file:`/usr` to install
|
||||
|kitty|. In other words, :file:`linux-package` is the staging area into which |kitty| is
|
||||
installed. You can choose a different staging area, by passing the ``--prefix``
|
||||
argument to :file:`setup.py`.
|
||||
This will install |kitty| into the directory :file:`linux-package`. You can run
|
||||
|kitty| with :file:`linux-package/bin/kitty`. All the files needed to run kitty
|
||||
will be in :file:`linux-package/lib/kitty`. The terminfo file will be installed
|
||||
into :file:`linux-package/share/terminfo`. Simply copy these files into
|
||||
:file:`/usr` to install |kitty|. In other words, :file:`linux-package` is the
|
||||
staging area into which |kitty| is installed. You can choose a different staging
|
||||
area, by passing the ``--prefix`` argument to :file:`setup.py`.
|
||||
|
||||
You should probably split |kitty| into three packages:
|
||||
|
||||
:code:`kitty-terminfo`
|
||||
installs the terminfo file
|
||||
Installs the terminfo file
|
||||
|
||||
:code:`kitty-shell-integration`
|
||||
installs the shell integration scripts (the contents of the
|
||||
shell-integration directory in the kitty source code, probably to
|
||||
Installs the shell integration scripts (the contents of the
|
||||
shell-integration directory in the kitty source code), probably to
|
||||
:file:`/usr/share/kitty/shell-integration`
|
||||
|
||||
:code:`kitty`
|
||||
installs the main program
|
||||
Installs the main program
|
||||
|
||||
This allows users to install the terminfo and shell integration files on
|
||||
servers into which they ssh, without needing to install all of |kitty|.
|
||||
This allows users to install the terminfo and shell integration files on servers
|
||||
into which they ssh, without needing to install all of |kitty|.
|
||||
|
||||
.. note::
|
||||
You need a couple of extra dependencies to build linux-package.
|
||||
:file:`tic` to compile terminfo files, usually found in the
|
||||
development package of :file:`ncurses`. Also, if you are building from
|
||||
a git checkout instead of the released source code tarball, you will
|
||||
need to install the dependencies from ``docs/requirements.txt`` to
|
||||
build the kitty documentation. They can be installed most easily with
|
||||
``python -m pip -r docs/requirements.txt``.
|
||||
You need a couple of extra dependencies to build linux-package. :file:`tic`
|
||||
to compile terminfo files, usually found in the development package of
|
||||
:file:`ncurses`. Also, if you are building from a git checkout instead of the
|
||||
released source code tarball, you will need to install the dependencies from
|
||||
:file:`docs/requirements.txt` to build the kitty documentation. They can be
|
||||
installed most easily with ``python -m pip -r docs/requirements.txt``.
|
||||
|
||||
This applies to creating packages for |kitty| for macOS package managers such as
|
||||
Homebrew or MacPorts as well.
|
||||
|
||||
@ -2,25 +2,25 @@ Saving and restoring colors
|
||||
==============================
|
||||
|
||||
It is often useful for a full screen application with its own color themes to
|
||||
set the default foreground, background, selection and cursor colors and the
|
||||
ANSI color table. This allows for various performance optimizations when
|
||||
drawing the screen. The problem is that if the user previously used the escape
|
||||
codes to change these colors herself, then running the full screen application
|
||||
will lose her changes even after it exits. To avoid this, kitty introduces a
|
||||
new pair of *OSC* escape codes to push and pop the current color values from a
|
||||
set the default foreground, background, selection and cursor colors and the ANSI
|
||||
color table. This allows for various performance optimizations when drawing the
|
||||
screen. The problem is that if the user previously used the escape codes to
|
||||
change these colors themselves, then running the full screen application will
|
||||
lose those changes even after it exits. To avoid this, kitty introduces a new
|
||||
pair of *OSC* escape codes to push and pop the current color values from a
|
||||
stack::
|
||||
|
||||
<ESC>]30001<ESC>\ # push onto stack
|
||||
<ESC>]30101<ESC>\ # pop from stack
|
||||
|
||||
These escape codes save/restore the colors, default
|
||||
background, default foreground, selection background, selection foreground and
|
||||
cursor color and the 256 colors of the ANSI color table.
|
||||
These escape codes save/restore the colors, default background, default
|
||||
foreground, selection background, selection foreground and cursor color and the
|
||||
256 colors of the ANSI color table.
|
||||
|
||||
.. note:: In July 2020, after several years, XTerm copied this protocol
|
||||
.. note:: In July 2020, after several years, xterm copied this protocol
|
||||
extension, without acknowledgement, and using incompatible escape codes
|
||||
(XTPUSHCOLORS, XTPOPCOLORS, XTREPORTCOLORS). And they decided to save not
|
||||
just the dynamic colors but the entire ANSI color table. In the interests of
|
||||
promoting interoperability, kitty added support for XTerm's escape codes as
|
||||
promoting interoperability, kitty added support for xterm's escape codes as
|
||||
well, and changed this extension to also save/restore the entire ANSI color
|
||||
table.
|
||||
|
||||
@ -3,9 +3,8 @@ kitty.conf
|
||||
|
||||
.. highlight:: conf
|
||||
|
||||
|kitty| is highly customizable, everything from keyboard shortcuts, to
|
||||
rendering frames-per-second. See below for an overview of all customization
|
||||
possibilities.
|
||||
|kitty| is highly customizable, everything from keyboard shortcuts, to rendering
|
||||
frames-per-second. See below for an overview of all customization possibilities.
|
||||
|
||||
You can open the config file within kitty by pressing :sc:`edit_config_file`
|
||||
(:kbd:`⌘+,` on macOS). A :file:`kitty.conf` with commented default
|
||||
@ -23,8 +22,8 @@ You can also display the current configuration by pressing :sc:`debug_config`
|
||||
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.
|
||||
character. This works only if the ``#`` character is the first character in the
|
||||
line.
|
||||
|
||||
.. _include:
|
||||
|
||||
@ -44,7 +43,7 @@ from environment variables. For example::
|
||||
|
||||
|
||||
.. note:: Syntax highlighting for :file:`kitty.conf` in vim is available via
|
||||
`vim-kitty <https://github.com/fladson/vim-kitty>`_.
|
||||
`vim-kitty <https://github.com/fladson/vim-kitty>`__.
|
||||
|
||||
|
||||
.. include:: /generated/conf-kitty.rst
|
||||
@ -55,17 +54,17 @@ Sample kitty.conf
|
||||
|
||||
.. only:: html
|
||||
|
||||
You can download a sample :file:`kitty.conf` file with all default settings and
|
||||
comments describing each setting by clicking: :download:`sample kitty.conf
|
||||
</generated/conf/kitty.conf>`.
|
||||
You can download a sample :file:`kitty.conf` file with all default settings
|
||||
and comments describing each setting by clicking: :download:`sample
|
||||
kitty.conf </generated/conf/kitty.conf>`.
|
||||
|
||||
.. only:: man
|
||||
|
||||
You can edit a fully commented sample kitty.conf by pressing the
|
||||
:sc:`edit_config_file` shortcut in kitty. This will generate a config
|
||||
file with full documentation and all settings commented out. If you
|
||||
have a pre-existing kitty.conf, then that will be used instead, delete
|
||||
it to see the sample file.
|
||||
:sc:`edit_config_file` shortcut in kitty. This will generate a config file
|
||||
with full documentation and all settings commented out. If you have a
|
||||
pre-existing :file:`kitty.conf`, then that will be used instead, delete it to
|
||||
see the sample file.
|
||||
|
||||
|
||||
All mappable actions
|
||||
|
||||
@ -3,19 +3,18 @@ Setting text styles/colors in arbitrary regions of the screen
|
||||
|
||||
There already exists an escape code to set *some* text attributes in arbitrary
|
||||
regions of the screen, `DECCARA
|
||||
<https://vt100.net/docs/vt510-rm/DECCARA.html>`_. However, it is limited to
|
||||
<https://vt100.net/docs/vt510-rm/DECCARA.html>`__. However, it is limited to
|
||||
only a few attributes. |kitty| extends this to work with *all* SGR attributes.
|
||||
So, for example, this can be used to set the background color in an arbitrary
|
||||
region of the screen.
|
||||
|
||||
The motivation for this extension is the various problems with the existing
|
||||
solution for erasing to background color, namely the *background color erase
|
||||
(bce)* capability. See
|
||||
:iss:`this discussion <160#issuecomment-346470545>`
|
||||
and `this FAQ <https://invisible-island.net/ncurses/ncurses.faq.html#bce_mismatches>`_
|
||||
(bce)* capability. See :iss:`this discussion <160#issuecomment-346470545>`
|
||||
and `this FAQ <https://invisible-island.net/ncurses/ncurses.faq.html#bce_mismatches>`__
|
||||
for a summary of problems with *bce*.
|
||||
|
||||
For example, to set the background color to blue in a
|
||||
rectangular region of the screen from (3, 4) to (10, 11), you use::
|
||||
For example, to set the background color to blue in a rectangular region of the
|
||||
screen from (3, 4) to (10, 11), you use::
|
||||
|
||||
<ESC>[2*x<ESC>[4;3;11;10;44$r<ESC>[*x
|
||||
|
||||
@ -5,21 +5,20 @@ Desktop notifications
|
||||
=======================
|
||||
|
||||
|kitty| implements an extensible escape code (OSC 99) to show desktop
|
||||
notifications. It is easy to use from shell scripts and fully extensible to
|
||||
show title and body. Clicking on the notification can optionally focus the
|
||||
window it came from, and/or send an escape code back to the application running
|
||||
in that window.
|
||||
notifications. It is easy to use from shell scripts and fully extensible to show
|
||||
title and body. Clicking on the notification can optionally focus the window it
|
||||
came from, and/or send an escape code back to the application running in that
|
||||
window.
|
||||
|
||||
The design of the escape code is partially based on the discussion in
|
||||
the defunct
|
||||
`terminal-wg <https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/13>`_
|
||||
The design of the escape code is partially based on the discussion in the
|
||||
defunct `terminal-wg <https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/13>`__
|
||||
|
||||
The escape code has the form::
|
||||
|
||||
<OSC> 99 ; metadata ; payload <terminator>
|
||||
|
||||
Here ``<OSC>`` is :code:`<ESC>]` and ``<terminator>`` is
|
||||
:code:`<ESC><backslash>`. The metadata is a section of colon separated
|
||||
:code:`<ESC><backslash>`. The ``metadata`` is a section of colon separated
|
||||
:code:`key=value` pairs. Every key must be a single character from the set
|
||||
:code:`a-zA-Z` and every value must be a word consisting of characters from
|
||||
the set :code:`a-zA-Z0-9-_/\+.,(){}[]*&^%$#@!`~`. The payload must be
|
||||
@ -45,28 +44,27 @@ The design of the escape code is fundamentally chunked, this is because
|
||||
different terminal emulators have different limits on how large a single escape
|
||||
code can be. Chunking is accomplished by the ``i`` and ``d`` keys. The ``i``
|
||||
key is the *notification id* which can be any string containing the characters
|
||||
``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and
|
||||
can only take the values ``0`` and ``1``. A value of ``0`` means the
|
||||
notification is not yet done and the terminal emulator should hold off
|
||||
displaying it. A value of ``1`` means the notification is done, and should be
|
||||
displayed. You can specify the title or body multiple times and the terminal
|
||||
emulator will concatenate them, thereby allowing arbitrarily long text
|
||||
(terminal emulators are free to impose a sensible limit to avoid
|
||||
Denial-of-Service attacks).
|
||||
``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and can only take the
|
||||
values ``0`` and ``1``. A value of ``0`` means the notification is not yet done
|
||||
and the terminal emulator should hold off displaying it. A value of ``1`` means
|
||||
the notification is done, and should be displayed. You can specify the title or
|
||||
body multiple times and the terminal emulator will concatenate them, thereby
|
||||
allowing arbitrarily long text (terminal emulators are free to impose a sensible
|
||||
limit to avoid Denial-of-Service attacks).
|
||||
|
||||
Both the ``title`` and ``body`` payloads must be either UTF-8 encoded plain
|
||||
text with no embedded escape codes, or UTF-8 text that is base64 encoded, in
|
||||
text with no embedded escape codes, or UTF-8 text that is Base64 encoded, in
|
||||
which case there must be an ``e=1`` key in the metadata to indicate the payload
|
||||
is base64 encoded.
|
||||
is Base64 encoded.
|
||||
|
||||
When the user clicks the notification, a couple of things can happen, the
|
||||
terminal emulator can focus the window from which the notification came, and/or
|
||||
it can send back an escape code to the application indicating the notification
|
||||
was activated. This is controlled by the ``a`` key which takes a comma
|
||||
separated set of values, ``report`` and ``focus``. The value ``focus`` means
|
||||
focus the window from which the notification was issued and is the default.
|
||||
``report`` means send an escape code back to the application. The format of the
|
||||
returned escape code is::
|
||||
was activated. This is controlled by the ``a`` key which takes a comma separated
|
||||
set of values, ``report`` and ``focus``. The value ``focus`` means focus the
|
||||
window from which the notification was issued and is the default. ``report``
|
||||
means send an escape code back to the application. The format of the returned
|
||||
escape code is::
|
||||
|
||||
<OSC> 99 ; i=identifier ; <terminator>
|
||||
|
||||
@ -87,9 +85,9 @@ to display it based on what it does understand.
|
||||
|
||||
.. note::
|
||||
It is possible to extend this escape code to allow specifying an icon for
|
||||
the notification, however, given that some platforms, such as macOS, dont
|
||||
allow displaying custom icons on a notification, at all, it was decided to
|
||||
leave it out of the spec for the time being.
|
||||
the notification, however, given that some platforms, such as legacy versions
|
||||
of macOS, don't allow displaying custom images on a notification, it was
|
||||
decided to leave it out of the spec for the time being.
|
||||
|
||||
Similarly, features such as scheduled notifications could be added in future
|
||||
revisions.
|
||||
@ -107,7 +105,7 @@ Key Value Default Description
|
||||
``d`` ``0`` or ``1`` ``1`` Indicates if the notification is
|
||||
complete or not.
|
||||
|
||||
``e`` ``0`` or ``1`` ``0`` If set to ``1`` means the payload is base64 encoded UTF-8,
|
||||
``e`` ``0`` or ``1`` ``0`` If set to ``1`` means the payload is Base64 encoded UTF-8,
|
||||
otherwise it is plain UTF-8 text with no C0 control codes in it
|
||||
|
||||
``i`` ``[a-zA-Z0-9-_+.]`` ``0`` Identifier for the notification
|
||||
@ -118,5 +116,6 @@ Key Value Default Description
|
||||
|
||||
|
||||
.. note::
|
||||
|kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for
|
||||
desktop notifications.
|
||||
|kitty| also supports the `legacy OSC 9 protocol developed by iTerm2
|
||||
<https://iterm2.com/documentation-escape-codes.html>`__ for desktop
|
||||
notifications.
|
||||
|
||||
@ -67,8 +67,9 @@ Variables that influence kitty behavior
|
||||
|
||||
.. envvar:: VISUAL
|
||||
|
||||
The terminal editor (such as ``vi`` or ``nano``) kitty uses, when, for
|
||||
instance, opening :file:`kitty.conf` in response to :sc:`edit_config_file`.
|
||||
The terminal based text editor (such as :program:`vi` or :program:`nano`)
|
||||
kitty uses, when, for instance, opening :file:`kitty.conf` in response to
|
||||
:sc:`edit_config_file`.
|
||||
|
||||
.. envvar:: EDITOR
|
||||
|
||||
@ -101,6 +102,11 @@ Variables that influence kitty behavior
|
||||
Set this to the path of a file that will be sourced in the cloned window when
|
||||
:ref:`clone-in-kitty <clone_shell>` is used.
|
||||
|
||||
.. envvar:: KITTY_DEVELOP_FROM
|
||||
|
||||
Set this to the directory path of the kitty source code and its Python code
|
||||
will be loaded from there. Only works with official binary builds.
|
||||
|
||||
|
||||
Variables that kitty sets when running child programs
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -189,3 +195,21 @@ Variables that kitty sets when running child programs
|
||||
|
||||
Set when enabling :ref:`shell_integration`. It is automatically removed by
|
||||
the shell integration scripts.
|
||||
|
||||
|
||||
.. envvar:: ZDOTDIR
|
||||
|
||||
Set when enabling :ref:`shell_integration` with :program:`zsh`, allowing
|
||||
:program:`zsh` to automatically load the integration script.
|
||||
|
||||
|
||||
.. envvar:: XDG_DATA_DIRS
|
||||
|
||||
Set when enabling :ref:`shell_integration` with :program:`fish`, allowing
|
||||
:program:`fish` to automatically load the integration script.
|
||||
|
||||
|
||||
.. envvar:: ENV
|
||||
|
||||
Set when enabling :ref:`shell_integration` with :program:`bash`, allowing
|
||||
:program:`bash` to automatically load the integration script.
|
||||
|
||||
@ -4,8 +4,8 @@ Integrations with other tools
|
||||
================================
|
||||
|
||||
kitty provides extremely powerful interfaces such as :doc:`remote-control` and
|
||||
:doc:`kittens/custom` and :doc:`kittens/icat`
|
||||
that allow it to be integrated with other tools seamlessly.
|
||||
:doc:`kittens/custom` and :doc:`kittens/icat` that allow it to be integrated
|
||||
with other tools seamlessly.
|
||||
|
||||
|
||||
Image and document viewers
|
||||
@ -30,19 +30,22 @@ Display markdown files nicely formatted with images in the terminal
|
||||
|
||||
`ranger <https://github.com/ranger/ranger>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
A terminal file manager, with previews of file contents powered by kitty's graphics protocol.
|
||||
A terminal file manager, with previews of file contents powered by kitty's
|
||||
graphics protocol.
|
||||
|
||||
.. _tool_nnn:
|
||||
|
||||
`nnn <https://github.com/jarun/nnn/>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Another terminal file manager, with previews of file contents powered by kitty's graphics protocol.
|
||||
Another terminal file manager, with previews of file contents powered by kitty's
|
||||
graphics protocol.
|
||||
|
||||
.. _tool_hunter:
|
||||
|
||||
`hunter <https://github.com/rabite0/hunter>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Another terminal file manager, with previews of file contents powered by kitty's graphics protocol.
|
||||
Another terminal file manager, with previews of file contents powered by kitty's
|
||||
graphics protocol.
|
||||
|
||||
.. _tool_koneko:
|
||||
|
||||
@ -61,8 +64,8 @@ View images in the terminal, similar to kitty's icat.
|
||||
|
||||
`nb <https://github.com/xwmx/nb>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
command line and local web note-taking, bookmarking, archiving, and
|
||||
knowledge base application that uses kitty's graphics protocol for images.
|
||||
Command line and local web note-taking, bookmarking, archiving, and knowledge
|
||||
base application that uses kitty's graphics protocol for images.
|
||||
|
||||
.. _tool_w3m:
|
||||
|
||||
@ -75,9 +78,9 @@ images.
|
||||
|
||||
`timg <https://github.com/hzeller/timg>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
A terminal image and video viewer, that displays static and animated
|
||||
images or plays videos. Fast multi-threaded loading, JPEG exif rotation,
|
||||
grid view and connecting to the webcam make it a versatile terminal utility.
|
||||
A terminal image and video viewer, that displays static and animated images or
|
||||
plays videos. Fast multi-threaded loading, JPEG exif rotation, grid view and
|
||||
connecting to the webcam make it a versatile terminal utility.
|
||||
|
||||
|
||||
System and data visualisation tools
|
||||
@ -87,7 +90,8 @@ System and data visualisation tools
|
||||
|
||||
`neofetch <https://github.com/dylanaraps/neofetch>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
A command line system information tool that shows images using kitty's graphics protocol
|
||||
A command line system information tool that shows images using kitty's graphics
|
||||
protocol
|
||||
|
||||
.. _tool_matplotlib:
|
||||
|
||||
@ -105,16 +109,16 @@ Show images from Julia directly in kitty
|
||||
|
||||
`euporie <https://github.com/joouha/euporie>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
A text-based user interface for running and editing Jupyter notebooks,
|
||||
powered by kitty's graphics protocol for displaying plots
|
||||
A text-based user interface for running and editing Jupyter notebooks, powered
|
||||
by kitty's graphics protocol for displaying plots
|
||||
|
||||
.. _tool_gnuplot:
|
||||
|
||||
`gnuplot <http://www.gnuplot.info/>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A graphing and data visualization tool that can be made to display its
|
||||
output in kitty with the following bash snippet:
|
||||
A graphing and data visualization tool that can be made to display its output in
|
||||
kitty with the following bash snippet:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
@ -171,26 +175,28 @@ Run applications on your system with fuzzy find inside a kitty window
|
||||
Editor integration
|
||||
-----------------------
|
||||
|
||||
|kitty| can be integrated into many different terminal editors to add features
|
||||
such a split windows, previews, REPLs etc.
|
||||
|kitty| can be integrated into many different terminal based text editors to add
|
||||
features such a split windows, previews, REPLs etc.
|
||||
|
||||
.. tool_kakoune:
|
||||
|
||||
`kakoune <https://kakoune.org/>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
integrates with kitty to use native kitty windows for its windows/panels and REPLs.
|
||||
Integrates with kitty to use native kitty windows for its windows/panels and
|
||||
REPLs.
|
||||
|
||||
.. tool_vim_slime:
|
||||
|
||||
`vim-slime <https://github.com/jpalardy/vim-slime#kitty>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
uses kitty remote control for a Lisp REPL.
|
||||
Uses kitty remote control for a Lisp REPL.
|
||||
|
||||
.. tool_vim_kitty_navigator:
|
||||
|
||||
`vim-kitty-navigator <https://github.com/knubie/vim-kitty-navigator>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
allows you to navigate seamlessly between vim and kitty splits using a consistent set of hotkeys.
|
||||
Allows you to navigate seamlessly between vim and kitty splits using a
|
||||
consistent set of hotkeys.
|
||||
|
||||
.. tool_vim_test:
|
||||
|
||||
@ -202,7 +208,7 @@ Allows easily running tests in a terminal window
|
||||
|
||||
`hologram.nvim <https://github.com/edluffy/hologram.nvim>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Terminal image viewer for nvim
|
||||
Terminal image viewer for Neovim
|
||||
|
||||
|
||||
Scrollback manipulation
|
||||
@ -228,21 +234,21 @@ Miscellaneous
|
||||
|
||||
`kitty-smart-tab <https://github.com/yurikhan/kitty-smart-tab>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
use keys to either control tabs or pass them onto running applications if
|
||||
no tabs are present
|
||||
Use keys to either control tabs or pass them onto running applications if no
|
||||
tabs are present
|
||||
|
||||
.. tool_kitty_smart_scroll:
|
||||
|
||||
`kitty-smart-scroll <https://github.com/yurikhan/kitty-smart-scroll>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
use keys to either scroll or pass them onto running applications if
|
||||
no scrollback buffer is present
|
||||
Use keys to either scroll or pass them onto running applications if no
|
||||
scrollback buffer is present
|
||||
|
||||
.. tool_kitti3:
|
||||
|
||||
`kitti3 <https://github.com/LandingEllipse/kitti3>`_
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
allow using kitty as a drop-down terminal under the i3 window manager
|
||||
Allow using kitty as a drop-down terminal under the i3 window manager
|
||||
|
||||
.. tool_weechat_hints:
|
||||
|
||||
|
||||
@ -52,7 +52,7 @@ snippets. See :sc:`insert_selected_path <insert_selected_path>` for examples.
|
||||
Completely customizing the matching and actions of the kitten
|
||||
---------------------------------------------------------------
|
||||
|
||||
The hints kitten supports writing simple python scripts that can be used to
|
||||
The hints kitten supports writing simple Python scripts that can be used to
|
||||
completely customize how it finds matches and what happens when a match is
|
||||
selected. This allows the hints kitten to provide the user interface, while you
|
||||
can provide the logic for finding matches and performing actions on them. This
|
||||
|
||||
@ -5,7 +5,7 @@ This kitten is used to query |kitty| from terminal programs about version, value
|
||||
of various runtime options controlling its features, etc.
|
||||
|
||||
The querying is done using the (*semi*) standard XTGETTCAP escape sequence
|
||||
pioneered by XTerm, so it works over SSH as well. The downside is that it is
|
||||
pioneered by xterm, so it works over SSH as well. The downside is that it is
|
||||
slow, since it requires a roundtrip to the terminal emulator and back.
|
||||
|
||||
If you want to do some of the same querying in your terminal program without
|
||||
|
||||
@ -124,7 +124,7 @@ How it works
|
||||
The ssh kitten works by having SSH transmit and execute a POSIX sh (or
|
||||
:opt:`optionally <kitten-ssh.interpreter>` Python) bootstrap script on the
|
||||
remote host using an :opt:`interpreter <kitten-ssh.interpreter>`. This script
|
||||
reads setup data over the TTY device, which kitty sends as a base64 encoded
|
||||
reads setup data over the TTY device, which kitty sends as a Base64 encoded
|
||||
compressed tarball. The script extracts it and places the :opt:`files <kitten-ssh.copy>`
|
||||
and sets the :opt:`environment variables <kitten-ssh.env>` before finally
|
||||
launching the :opt:`login shell <kitten-ssh.login_shell>` with :opt:`shell
|
||||
|
||||
@ -20,8 +20,8 @@ Extend with kittens
|
||||
kittens/*
|
||||
|
||||
|kitty| has a framework for easily creating terminal programs that make use of
|
||||
its advanced features. These programs are called kittens. They are used both
|
||||
to add features to |kitty| itself and to create useful standalone programs.
|
||||
its advanced features. These programs are called kittens. They are used both to
|
||||
add features to |kitty| itself and to create useful standalone programs.
|
||||
Some prominent kittens:
|
||||
|
||||
:doc:`icat <kittens/icat>`
|
||||
@ -33,7 +33,7 @@ Some prominent kittens:
|
||||
images
|
||||
|
||||
|
||||
:doc:`Unicode Input <kittens/unicode_input>`
|
||||
:doc:`Unicode input <kittens/unicode_input>`
|
||||
Easily input arbitrary Unicode characters in |kitty| by name or hex code.
|
||||
|
||||
|
||||
@ -48,29 +48,31 @@ Some prominent kittens:
|
||||
|
||||
|
||||
:doc:`Transfer files <kittens/transfer>`
|
||||
Transfer files and directories seamlessly and easily from remote machines over your existing
|
||||
SSH sessions with a simple command.
|
||||
Transfer files and directories seamlessly and easily from remote machines
|
||||
over your existing SSH sessions with a simple command.
|
||||
|
||||
|
||||
:doc:`Hyperlinked grep <kittens/hyperlinked_grep>`
|
||||
Search your files using `ripgrep <https://github.com/BurntSushi/ripgrep>`__
|
||||
and open the results directly in your favorite editor in the terminal,
|
||||
at the line containing the search result, simply by clicking on the result you want.
|
||||
at the line containing the search result, simply by clicking on the result
|
||||
you want.
|
||||
|
||||
|
||||
:doc:`Broadcast <kittens/broadcast>`
|
||||
Type in one :term:`kitty window <window>` and have it broadcast to all (or a subset) of
|
||||
other :term:`kitty windows <window>`.
|
||||
Type in one :term:`kitty window <window>` and have it broadcast to all (or a
|
||||
subset) of other :term:`kitty windows <window>`.
|
||||
|
||||
|
||||
:doc:`SSH <kittens/ssh>`
|
||||
SSH with automatic shell integration, connection re-use for low latency and easy cloning
|
||||
of local shell and editor configuration to the remote machine.
|
||||
SSH with automatic :ref:`shell integration <shell_integration>`, connection
|
||||
re-use for low latency and easy cloning of local shell and editor
|
||||
configuration to the remote host.
|
||||
|
||||
|
||||
:doc:`Panel <kittens/panel>`
|
||||
Draw a GPU accelerated dock panel on your desktop showing the output
|
||||
from an arbitrary terminal program.
|
||||
Draw a GPU accelerated dock panel on your desktop showing the output from an
|
||||
arbitrary terminal program.
|
||||
|
||||
|
||||
:doc:`Clipboard <kittens/clipboard>`
|
||||
|
||||
@ -5,22 +5,21 @@ The :command:`launch` command
|
||||
|
||||
|
||||
|kitty| has a :code:`launch` action that can be used to run arbitrary programs
|
||||
in new windows/tabs. It can be mapped to user defined shortcuts in kitty.conf.
|
||||
It is very powerful and allows sending the contents of
|
||||
the current window to the launched program, as well as many other options.
|
||||
in new windows/tabs. It can be mapped to user defined shortcuts in
|
||||
:file:`kitty.conf`. It is very powerful and allows sending the contents of the
|
||||
current window to the launched program, as well as many other options.
|
||||
|
||||
In the simplest form, you can use it to open a new kitty window running the
|
||||
shell, as shown below::
|
||||
|
||||
map f1 launch
|
||||
|
||||
To run a different program simply pass the command line as arguments to
|
||||
launch::
|
||||
To run a different program simply pass the command line as arguments to launch::
|
||||
|
||||
map f1 launch vim path/to/some/file
|
||||
|
||||
To open a new window with the same working directory as the currently
|
||||
active window::
|
||||
To open a new window with the same working directory as the currently active
|
||||
window::
|
||||
|
||||
map f1 launch --cwd=current
|
||||
|
||||
@ -30,9 +29,10 @@ To open the new window in a new tab::
|
||||
|
||||
To run multiple commands in a shell, use::
|
||||
|
||||
map f1 launch sh -c "ls && zsh"
|
||||
map f1 launch sh -c "ls && exec zsh"
|
||||
|
||||
To pass the contents of the current screen and scrollback to the started process::
|
||||
To pass the contents of the current screen and scrollback to the started
|
||||
process::
|
||||
|
||||
map f1 launch --stdin-source=@screen_scrollback less
|
||||
|
||||
@ -46,16 +46,16 @@ There are many more powerful options, refer to the complete list below.
|
||||
map f1 launch_tab vim
|
||||
map f2 launch_tab emacs
|
||||
|
||||
The :kbd:`F1` key will now open vim in a new tab with the current windows
|
||||
working directory
|
||||
The :kbd:`F1` key will now open :program:`vim` in a new tab with the current
|
||||
windows working directory.
|
||||
|
||||
|
||||
The piping environment
|
||||
--------------------------
|
||||
|
||||
When using :option:`launch --stdin-source`, the program to which the data is
|
||||
piped has a special environment variable declared, :envvar:`KITTY_PIPE_DATA` whose
|
||||
contents are::
|
||||
piped has a special environment variable declared, :envvar:`KITTY_PIPE_DATA`
|
||||
whose contents are::
|
||||
|
||||
KITTY_PIPE_DATA={scrolled_by}:{cursor_x},{cursor_y}:{lines},{columns}
|
||||
|
||||
@ -73,33 +73,33 @@ the command line:
|
||||
|
||||
|
||||
``@selection``
|
||||
replaced by the currently selected text
|
||||
Replaced by the currently selected text.
|
||||
|
||||
``@active-kitty-window-id``
|
||||
replaced by the id of the currently active kitty window
|
||||
Replaced by the id of the currently active kitty window.
|
||||
|
||||
``@line-count``
|
||||
replaced by the number of lines in STDIN. Only present when passing some
|
||||
data to STDIN
|
||||
Replaced by the number of lines in STDIN. Only present when passing some
|
||||
data to STDIN.
|
||||
|
||||
``@input-line-number``
|
||||
replaced the number of lines a pager should scroll to match the current
|
||||
scroll position in kitty. See :opt:`scrollback_pager` for details
|
||||
Replaced the number of lines a pager should scroll to match the current
|
||||
scroll position in kitty. See :opt:`scrollback_pager` for details.
|
||||
|
||||
``@scrolled-by``
|
||||
replaced by the number of lines kitty is currently scrolled by
|
||||
Replaced by the number of lines kitty is currently scrolled by.
|
||||
|
||||
``@cursor-x``
|
||||
replaced by the current cursor x position with 1 being the leftmost cell
|
||||
Replaced by the current cursor x position with 1 being the leftmost cell.
|
||||
|
||||
``@cursor-y``
|
||||
replaced by the current cursor y position with 1 being the topmost cell
|
||||
Replaced by the current cursor y position with 1 being the topmost cell.
|
||||
|
||||
``@first-line-on-screen``
|
||||
replaced by the first line on screen. Can be used for pager positioning.
|
||||
Replaced by the first line on screen. Can be used for pager positioning.
|
||||
|
||||
``@last-line-on-screen``
|
||||
replaced by the last line on screen. Can be used for pager positioning.
|
||||
Replaced by the last line on screen. Can be used for pager positioning.
|
||||
|
||||
|
||||
For example::
|
||||
@ -112,44 +112,51 @@ For example::
|
||||
Watching launched windows
|
||||
---------------------------
|
||||
|
||||
The :option:`launch --watcher` option allows you to specify python functions
|
||||
The :option:`launch --watcher` option allows you to specify Python functions
|
||||
that will be called at specific events, such as when the window is resized or
|
||||
closed. Simply specify the path to a python module that specifies callback
|
||||
closed. Simply specify the path to a Python module that specifies callback
|
||||
functions for the events you are interested in, for example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def on_resize(boss, window, data):
|
||||
from typing import Any, Dict
|
||||
|
||||
from kitty.boss import Boss
|
||||
from kitty.window import Window
|
||||
|
||||
|
||||
def on_resize(boss: Boss, window: Window, data: Dict[str, Any]) -> None:
|
||||
# Here data will contain old_geometry and new_geometry
|
||||
|
||||
def on_focus_change(boss, window, data):
|
||||
def on_focus_change(boss: Boss, window: Window, data: Dict[str, Any])-> None:
|
||||
# Here data will contain focused
|
||||
|
||||
def on_close(boss, window, data):
|
||||
def on_close(boss: Boss, window: Window, data: Dict[str, Any])-> None:
|
||||
# called when window is closed, typically when the program running in
|
||||
# it exits.
|
||||
|
||||
|
||||
Every callback is passed a reference to the global ``Boss`` object as well as
|
||||
the ``Window`` object the action is occurring on. The ``data`` object is
|
||||
a dict that contains event dependent data. Some useful methods and attributes
|
||||
for the ``Window`` object are: ``as_text(as_ans=False, add_history=False,
|
||||
the ``Window`` object the action is occurring on. The ``data`` object is a dict
|
||||
that contains event dependent data. Some useful methods and attributes for the
|
||||
``Window`` object are: ``as_text(as_ans=False, add_history=False,
|
||||
add_wrap_markers=False, alternate_screen=False)`` with which you can get the
|
||||
contents of the window and its scrollback buffer. Similarly,
|
||||
``window.child.pid`` is the PID of the processes that was launched
|
||||
in the window and ``window.id`` is the internal kitty ``id`` of the
|
||||
window.
|
||||
in the window and ``window.id`` is the internal kitty ``id`` of the window.
|
||||
|
||||
|
||||
Finding executables
|
||||
-----------------------
|
||||
|
||||
When you specify a command to run as just a name rather than an absolute path,
|
||||
it is searched for in the system-wide ``PATH`` environment variable. Note that
|
||||
this **may not** be the value of ``PATH`` inside a shell, as shell startup scripts
|
||||
often change the value of this variable. If it is not found there, then a
|
||||
system specific list of default paths is searched. If it is still not found,
|
||||
then your shell is run and the value of ``PATH`` inside the shell is used.
|
||||
it is searched for in the system-wide :envvar:`PATH` environment variable. Note
|
||||
that this **may not** be the value of :envvar:`PATH` inside a shell, as shell
|
||||
startup scripts often change the value of this variable. If it is not found
|
||||
there, then a system specific list of default paths is searched. If it is still
|
||||
not found, then your shell is run and the value of :envvar:`PATH` inside the
|
||||
shell is used.
|
||||
|
||||
See :opt:`exe_search_path` for details and how to control this.
|
||||
|
||||
Syntax reference
|
||||
|
||||
@ -10,7 +10,8 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples:
|
||||
:align: center
|
||||
:width: 100%
|
||||
|
||||
Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout
|
||||
Screenshot, showing :program:`vim`, :program:`tig` and :program:`git`
|
||||
running in |kitty| with the *Tall* layout
|
||||
|
||||
|
||||
.. figure:: screenshots/splits.png
|
||||
@ -18,21 +19,22 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples:
|
||||
:align: center
|
||||
:width: 100%
|
||||
|
||||
Screenshot, showing windows with arbitrary arrangement in the 'Splits'
|
||||
Screenshot, showing windows with arbitrary arrangement in the *Splits*
|
||||
layout
|
||||
|
||||
|
||||
There are many different layouts available. They are all enabled by default,
|
||||
you can switch layouts using :sc:`next_layout`. To control which layouts
|
||||
are available use :opt:`enabled_layouts`, the first listed layout becomes
|
||||
the default. Individual layouts and how to use them are described below.
|
||||
There are many different layouts available. They are all enabled by default, you
|
||||
can switch layouts using :ac:`next_layout` (:sc:`next_layout` by default). To
|
||||
control which layouts are available use :opt:`enabled_layouts`, the first listed
|
||||
layout becomes the default. Individual layouts and how to use them are described
|
||||
below.
|
||||
|
||||
|
||||
The Stack Layout
|
||||
------------------
|
||||
|
||||
This is the simplest layout it displays a single window using all available
|
||||
space, other windows are hidden behind it. It has no options::
|
||||
This is the simplest layout. It displays a single window using all available
|
||||
space, other windows are hidden behind it. This layout has no options::
|
||||
|
||||
enabled_layouts stack
|
||||
|
||||
@ -40,14 +42,14 @@ space, other windows are hidden behind it. It has no options::
|
||||
The Tall Layout
|
||||
------------------
|
||||
|
||||
Displays one (or optionally more) full height windows on the left half of the
|
||||
Displays one (or optionally more) full-height windows on the left half of the
|
||||
screen. Remaining windows are tiled vertically on the right half of the screen.
|
||||
There are options to control how the screen is split horizontally ``bias``
|
||||
(an integer between ``10`` and ``90``) and options to control how many
|
||||
full-height windows there are ``full_size`` (a positive integer). The
|
||||
``mirrored`` option when set to ``true`` will cause the short windows to be
|
||||
on the left side of the screen instead of the right. The syntax
|
||||
for the options is shown below::
|
||||
``mirrored`` option when set to ``true`` will cause the full-height windows to
|
||||
be on the right side of the screen instead of the left. The syntax
|
||||
for the options is::
|
||||
|
||||
enabled_layouts tall:bias=50;full_size=1;mirrored=false
|
||||
|
||||
@ -65,7 +67,7 @@ for the options is shown below::
|
||||
│ │ │
|
||||
└──────────────┴───────────────┘
|
||||
|
||||
In addition, you can map keys to increase or decrease the number of full size
|
||||
In addition, you can map keys to increase or decrease the number of full-height
|
||||
windows, for example::
|
||||
|
||||
map ctrl+[ layout_action decrease_num_full_size_windows
|
||||
@ -75,14 +77,13 @@ windows, for example::
|
||||
The Fat Layout
|
||||
----------------
|
||||
|
||||
Displays one (or optionally more) full width windows on the top half of the
|
||||
screen. Remaining windows are tiled horizontally on the bottom half of the screen.
|
||||
There are options to control how the screen is split vertically ``bias``
|
||||
Displays one (or optionally more) full-width windows on the top half of the
|
||||
screen. Remaining windows are tiled horizontally on the bottom half of the
|
||||
screen. There are options to control how the screen is split vertically ``bias``
|
||||
(an integer between ``10`` and ``90``) and options to control how many
|
||||
full-height windows there are ``full_size`` (a positive integer). The
|
||||
``mirrored`` option when set to ``true`` will cause the narrow windows to be
|
||||
on the top of the screen instead of the bottom. The syntax for the options is
|
||||
shown below::
|
||||
full-width windows there are ``full_size`` (a positive integer). The
|
||||
``mirrored`` option when set to ``true`` will cause the full-width windows to be
|
||||
on the bottom of the screen instead of the top. The syntax for the options is::
|
||||
|
||||
enabled_layouts fat:bias=50;full_size=1;mirrored=false
|
||||
|
||||
@ -100,11 +101,16 @@ shown below::
|
||||
└─────────┴──────────┴─────────┘
|
||||
|
||||
|
||||
This layout also supports ``decrease_num_full_size_windows`` layout action like
|
||||
the *Tall* layout, shown above.
|
||||
|
||||
|
||||
The Grid Layout
|
||||
--------------------
|
||||
|
||||
Display windows in a balanced grid with all windows the same size except the
|
||||
last column if there are not enough windows to fill the grid. Has no options::
|
||||
last column if there are not enough windows to fill the grid. This layout has no
|
||||
options::
|
||||
|
||||
enabled_layouts grid
|
||||
|
||||
@ -132,20 +138,20 @@ define a few extra key bindings in :file:`kitty.conf`::
|
||||
|
||||
# Create a new window splitting the space used by the existing one so that
|
||||
# the two windows are placed one above the other
|
||||
map F5 launch --location=hsplit
|
||||
map f5 launch --location=hsplit
|
||||
|
||||
# Create a new window splitting the space used by the existing one so that
|
||||
# the two windows are placed side by side
|
||||
map F6 launch --location=vsplit
|
||||
map f6 launch --location=vsplit
|
||||
|
||||
# Create a new window splitting the space used by the existing one so that
|
||||
# the two windows are placed side by side if the existing window is wide or
|
||||
# one above the other if the existing window is tall.
|
||||
map F4 launch --location=split
|
||||
map f4 launch --location=split
|
||||
|
||||
# Rotate the current split, chaging its split axis from vertical to
|
||||
# horizontal or vice versa
|
||||
map F7 layout_action rotate
|
||||
map f7 layout_action rotate
|
||||
|
||||
# Move the active window in the indicated direction
|
||||
map shift+up move_window up
|
||||
@ -164,11 +170,11 @@ in a split using the ``rotate`` action with an argument of ``180`` and rotate
|
||||
and swap with an argument of ``270``.
|
||||
|
||||
This layout takes one option, ``split_axis`` that controls whether new windows
|
||||
are placed into vertical or horizontal splits when a ``--location`` is not
|
||||
specified. A value of ``horizontal`` (same as ``--location=vsplit``)
|
||||
means when a new split is created the two windows will be placed side by side
|
||||
and a value of ``vertical`` (same as ``--location=hsplit``) means the two
|
||||
windows will be placed one on top of the other. By default::
|
||||
are placed into vertical or horizontal splits when a :option:`--location <launch
|
||||
--location>` is not specified. A value of ``horizontal`` (same as
|
||||
``--location=vsplit``) means when a new split is created the two windows will be
|
||||
placed side by side and a value of ``vertical`` (same as ``--location=hsplit``)
|
||||
means the two windows will be placed one on top of the other. By default::
|
||||
|
||||
enabled_layouts splits:split_axis=horizontal
|
||||
|
||||
@ -193,7 +199,7 @@ windows will be placed one on top of the other. By default::
|
||||
The Horizontal Layout
|
||||
------------------------
|
||||
|
||||
All windows are shown side by side. Has no options::
|
||||
All windows are shown side by side. This layout has no options::
|
||||
|
||||
enabled_layouts horizontal
|
||||
|
||||
@ -213,7 +219,7 @@ All windows are shown side by side. Has no options::
|
||||
The Vertical Layout
|
||||
-----------------------
|
||||
|
||||
All windows are shown one below the other. Has no options::
|
||||
All windows are shown one below the other. This layout has no options::
|
||||
|
||||
enabled_layouts vertical
|
||||
|
||||
@ -239,14 +245,14 @@ Resizing windows
|
||||
|
||||
You can resize windows inside layouts. Press :sc:`start_resizing_window` (also
|
||||
:kbd:`⌘+r` on macOS) to enter resizing mode and follow the on-screen
|
||||
instructions. In a given window layout only some operations may be possible
|
||||
for a particular window. For example, in the Tall layout you can make the first
|
||||
instructions. In a given window layout only some operations may be possible for
|
||||
a particular window. For example, in the *Tall* layout you can make the first
|
||||
window wider/narrower, but not taller/shorter. Note that what you are resizing
|
||||
is actually not a window, but a row/column in the layout, all windows in that
|
||||
row/column will be resized.
|
||||
|
||||
You can also define shortcuts in :file:`kitty.conf` to make the active window
|
||||
wider, narrower, taller, or shorter by mapping to the ``resize_window``
|
||||
wider, narrower, taller, or shorter by mapping to the :ac:`resize_window`
|
||||
action, for example::
|
||||
|
||||
map ctrl+left resize_window narrower
|
||||
@ -256,22 +262,21 @@ action, for example::
|
||||
# reset all windows in the tab to default sizes
|
||||
map ctrl+home resize_window reset
|
||||
|
||||
The ``resize_window`` action has a second, optional argument to control
|
||||
The :ac:`resize_window` action has a second optional argument to control
|
||||
the resizing increment (a positive integer that defaults to 1).
|
||||
|
||||
|
||||
Some layouts take options to control their behavior. For example, the ``fat``
|
||||
and ``tall`` layouts accept the ``bias`` and ``full_size`` options to control
|
||||
how the available space is split up.
|
||||
To specify the option, in :opt:`kitty.conf <enabled_layouts>` use::
|
||||
Some layouts take options to control their behavior. For example, the *Fat*
|
||||
and *Tall* layouts accept the ``bias`` and ``full_size`` options to control
|
||||
how the available space is split up. To specify the option, in :opt:`kitty.conf
|
||||
<enabled_layouts>` use::
|
||||
|
||||
enabled_layouts tall:bias=70;full_size=2
|
||||
|
||||
This will have ``2`` instead of a single tall window, that occupy ``70%``
|
||||
instead of ``50%`` of available width. ``bias`` can be any number between 10
|
||||
and 90.
|
||||
instead of ``50%`` of available width. ``bias`` can be any number between ``10``
|
||||
and ``90``.
|
||||
|
||||
Writing a new layout only requires about two hundred lines of code, so if there
|
||||
is some layout you want, take a look at one of the existing layouts in the
|
||||
`layout <https://github.com/kovidgoyal/kitty/tree/master/kitty/layout>`_
|
||||
`layout <https://github.com/kovidgoyal/kitty/tree/master/kitty/layout>`__
|
||||
package and submit a pull request!
|
||||
|
||||
@ -53,21 +53,20 @@ If you want to create markers dynamically rather than pre-defining them in
|
||||
map f1 create_marker
|
||||
map f2 remove_marker
|
||||
|
||||
Then pressing :kbd:`F1` will allow you to enter the marker definition and set
|
||||
it and pressing :kbd:`F2` will remove the marker. ``create_marker`` accepts
|
||||
the same syntax as ``toggle_marker`` above. Note that while creating markers,
|
||||
the prompt has history so you can easily re-use previous marker expressions.
|
||||
Then pressing :kbd:`F1` will allow you to enter the marker definition and set it
|
||||
and pressing :kbd:`F2` will remove the marker. :ac:`create_marker` accepts the
|
||||
same syntax as :ac:`toggle_marker` above. Note that while creating markers, the
|
||||
prompt has history so you can easily re-use previous marker expressions.
|
||||
|
||||
You can also use the facilities for :doc:`remote-control` to dynamically
|
||||
add/remove markers.
|
||||
You can also use the facilities for :doc:`remote-control` to dynamically add or
|
||||
remove markers.
|
||||
|
||||
|
||||
Scrolling to marks
|
||||
--------------------
|
||||
|
||||
kitty has an action :ac:`scroll_to_mark` to scroll to the next line that
|
||||
contains a mark. You can use it by mapping it to some shortcut in
|
||||
:file:`kitty.conf`::
|
||||
kitty has a :ac:`scroll_to_mark` action to scroll to the next line that contains
|
||||
a mark. You can use it by mapping it to some shortcut in :file:`kitty.conf`::
|
||||
|
||||
map ctrl+p scroll_to_mark prev
|
||||
map ctrl+n scroll_to_mark next
|
||||
@ -92,8 +91,8 @@ The syntax of the :ac:`toggle_marker` action is::
|
||||
|
||||
Here :code:`marker-type` is one of:
|
||||
|
||||
* :code:`text` - simple substring matching
|
||||
* :code:`itext` - case-insensitive substring matching
|
||||
* :code:`text` - Simple substring matching
|
||||
* :code:`itext` - Case-insensitive substring matching
|
||||
* :code:`regex` - A Python regular expression
|
||||
* :code:`iregex` - A case-insensitive Python regular expression
|
||||
* :code:`function` - An arbitrary function defined in a Python file, see :ref:`marker_funcs`.
|
||||
@ -104,8 +103,8 @@ Arbitrary marker functions
|
||||
-----------------------------
|
||||
|
||||
You can create your own marker functions. Create a Python file named
|
||||
:file:`mymarker.py` and in it create a :code:`marker` function. This
|
||||
function receives the text of the line as input and must yield three numbers,
|
||||
:file:`mymarker.py` and in it create a :code:`marker` function. This function
|
||||
receives the text of the line as input and must yield three numbers,
|
||||
the starting character position, the ending character position and the mark
|
||||
group (1-3). For example:
|
||||
|
||||
|
||||
@ -4,23 +4,22 @@ Overview
|
||||
Design philosophy
|
||||
-------------------
|
||||
|
||||
|kitty| is designed for power keyboard users. To that end all its controls
|
||||
work with the keyboard (although it fully supports mouse interactions as
|
||||
well). Its configuration is a simple, human editable, single file for
|
||||
easy reproducibility (I like to store configuration in source control).
|
||||
|kitty| is designed for power keyboard users. To that end all its controls work
|
||||
with the keyboard (although it fully supports mouse interactions as well). Its
|
||||
configuration is a simple, human editable, single file for easy reproducibility
|
||||
(I like to store configuration in source control).
|
||||
|
||||
The code in |kitty| is designed to be simple, modular and hackable. It is
|
||||
written in a mix of C (for performance sensitive parts) and Python (for
|
||||
easy hackability of the UI). It does not depend on any large and complex
|
||||
UI toolkit, using only OpenGL for rendering everything.
|
||||
written in a mix of C (for performance sensitive parts) and Python (for easy
|
||||
hackability of the UI). It does not depend on any large and complex UI toolkit,
|
||||
using only OpenGL for rendering everything.
|
||||
|
||||
Finally, |kitty| is designed from the ground up to support all modern
|
||||
terminal features, such as unicode, true color, bold/italic fonts, text
|
||||
formatting, etc. It even extends existing text formatting escape codes,
|
||||
to add support for features not available elsewhere, such as colored and
|
||||
styled (curly) underlines. One of the design goals of |kitty| is to be
|
||||
easily extensible so that new features can be added in the future with
|
||||
relatively little effort.
|
||||
Finally, |kitty| is designed from the ground up to support all modern terminal
|
||||
features, such as Unicode, true color, bold/italic fonts, text formatting, etc.
|
||||
It even extends existing text formatting escape codes, to add support for
|
||||
features not available elsewhere, such as colored and styled (curly) underlines.
|
||||
One of the design goals of |kitty| is to be easily extensible so that new
|
||||
features can be added in the future with relatively little effort.
|
||||
|
||||
.. include:: basic.rst
|
||||
|
||||
@ -28,10 +27,10 @@ relatively little effort.
|
||||
Configuring kitty
|
||||
-------------------
|
||||
|
||||
|kitty| is highly configurable, everything from keyboard shortcuts to
|
||||
painting frames-per-second. Press :sc:`edit_config_file` in kitty
|
||||
to open its fully commented sample config file in your text editor.
|
||||
For details see the :doc:`configuration docs <conf>`.
|
||||
|kitty| is highly configurable, everything from keyboard shortcuts to painting
|
||||
frames-per-second. Press :sc:`edit_config_file` in kitty to open its fully
|
||||
commented sample config file in your text editor. For details see the
|
||||
:doc:`configuration docs <conf>`.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
@ -51,17 +50,26 @@ windows automatically, resizing and moving them as needed. You can create a new
|
||||
|
||||
Currently, there are seven layouts available:
|
||||
|
||||
* **Fat** -- One (or optionally more) windows are shown full width on the top, the rest of the windows are shown side-by-side on the bottom
|
||||
* **Fat** -- One (or optionally more) windows are shown full width on the top,
|
||||
the rest of the windows are shown side-by-side on the bottom
|
||||
|
||||
* **Grid** -- All windows are shown in a grid
|
||||
|
||||
* **Horizontal** -- All windows are shown side-by-side
|
||||
* **Splits** -- Windows arranged in arbitrary patterns created using horizontal and vertical splits
|
||||
|
||||
* **Splits** -- Windows arranged in arbitrary patterns created using horizontal
|
||||
and vertical splits
|
||||
|
||||
* **Stack** -- Only a single maximized window is shown at a time
|
||||
* **Tall** -- One (or optionally more) windows are shown full height on the left, the rest of the windows are shown one below the other on the right
|
||||
|
||||
* **Tall** -- One (or optionally more) windows are shown full height on the
|
||||
left, the rest of the windows are shown one below the other on the right
|
||||
|
||||
* **Vertical** -- All windows are shown one below the other
|
||||
|
||||
By default, all layouts are enabled and you can switch between layouts using
|
||||
the :sc:`next_layout` key combination. You can also create shortcuts to select
|
||||
particular layouts, and choose which layouts you want to enable/disable, see
|
||||
particular layouts, and choose which layouts you want to enable, see
|
||||
:ref:`conf-kitty-shortcuts.layout` for examples. The first layout listed in
|
||||
:opt:`enabled_layouts` becomes the default layout.
|
||||
|
||||
@ -79,9 +87,9 @@ Extending kitty
|
||||
kitty has a powerful framework for scripting. You can create small terminal
|
||||
programs called :doc:`kittens <kittens_intro>`. These can used to add features
|
||||
to kitty, for example, :doc:`editing remote files <kittens/remote_file>` or
|
||||
:doc:`inputting unicode characters <kittens/unicode_input>`. They can also be
|
||||
:doc:`inputting Unicode characters <kittens/unicode_input>`. They can also be
|
||||
used to create programs that leverage kitty's powerful features, for example,
|
||||
:doc:`viewing images <kittens/icat>` or :doc:`diffing files with images
|
||||
:doc:`viewing images <kittens/icat>` or :doc:`diffing files with image support
|
||||
<kittens/diff>`.
|
||||
|
||||
You can :doc:`create your own kittens to scratch your own itches
|
||||
@ -101,9 +109,9 @@ Remote control
|
||||
|kitty| has a very powerful system that allows you to control it from the
|
||||
:doc:`shell prompt, even over SSH <remote-control>`. You can change colors,
|
||||
fonts, open new :term:`windows <window>`, :term:`tabs <tab>`, set their titles,
|
||||
change window layout, get text
|
||||
from one window and send text to another, etc, etc. The possibilities are
|
||||
endless. See the :doc:`tutorial <remote-control>` to get started.
|
||||
change window layout, get text from one window and send text to another, etc.
|
||||
The possibilities are endless. See the :doc:`tutorial <remote-control>` to get
|
||||
started.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
@ -117,10 +125,9 @@ Startup Sessions
|
||||
------------------
|
||||
|
||||
You can control the :term:`tabs <tab>`, :term:`kitty window <window>` layout,
|
||||
working directory, startup programs,
|
||||
etc. by creating a "session" file and using the :option:`kitty --session`
|
||||
command line flag or the :opt:`startup_session` option in :file:`kitty.conf`.
|
||||
For example:
|
||||
working directory, startup programs, etc. by creating a *session* file and using
|
||||
the :option:`kitty --session` command line flag or the :opt:`startup_session`
|
||||
option in :file:`kitty.conf`. For example:
|
||||
|
||||
.. code-block:: session
|
||||
|
||||
@ -130,28 +137,28 @@ For example:
|
||||
cd ~
|
||||
# Create a window and run the specified command in it
|
||||
launch zsh
|
||||
# Create a window with some environment variables set and run
|
||||
# vim in it
|
||||
# Create a window with some environment variables set and run vim in it
|
||||
launch --env FOO=BAR vim
|
||||
# Set the title for the next window
|
||||
launch --title "Chat with x" irssi --profile x
|
||||
|
||||
# Create a new tab (the part after new_tab is the optional tab
|
||||
# name which will be displayed in the tab bar, if omitted, the
|
||||
# title of the active window will be used instead)
|
||||
# Create a new tab
|
||||
# The part after new_tab is the optional tab title which will be displayed in
|
||||
# the tab bar, if omitted, the title of the active window will be used instead.
|
||||
new_tab my tab
|
||||
cd ~/somewhere
|
||||
# Set the layouts allowed in this tab
|
||||
enabled_layouts tall, stack
|
||||
enabled_layouts tall,stack
|
||||
# Set the current layout
|
||||
layout stack
|
||||
launch zsh
|
||||
|
||||
# Create a new OS window
|
||||
# Any definitions specifed before the first new_os_window will apply to first OS window.
|
||||
new_os_window
|
||||
# set new window size to 80x25 cells (if specifed before new_os_window will apply to first OS window)
|
||||
os_window_size 80c 25c
|
||||
# set the --class for the new OS window
|
||||
# Set new window size to 80x24 cells
|
||||
os_window_size 80c 24c
|
||||
# Set the --class for the new OS window
|
||||
os_window_class mywindow
|
||||
launch sh
|
||||
# Make the current window the active (focused) window
|
||||
@ -159,8 +166,8 @@ For example:
|
||||
launch emacs
|
||||
|
||||
.. note::
|
||||
The :doc:`launch <launch>` command when used in a session file
|
||||
cannot create new OS windows, or tabs.
|
||||
The :doc:`launch <launch>` command when used in a session file cannot create
|
||||
new OS windows, or tabs.
|
||||
|
||||
|
||||
Creating tabs/windows
|
||||
@ -182,25 +189,25 @@ Mouse features
|
||||
* You can click on a URL to open it in a browser.
|
||||
* You can double click to select a word and then drag to select more words.
|
||||
* You can triple click to select a line and then drag to select more lines.
|
||||
* You can triple click while holding :kbd:`ctrl+alt` to select from clicked
|
||||
* You can triple click while holding :kbd:`Ctrl+Alt` to select from clicked
|
||||
point to end of line.
|
||||
* You can right click to extend a previous selection.
|
||||
* You can hold down :kbd:`ctrl+alt` and drag with the mouse to select in
|
||||
* You can hold down :kbd:`Ctrl+Alt` and drag with the mouse to select in
|
||||
columns.
|
||||
* Selecting text automatically copies it to the primary clipboard (on
|
||||
platforms with a primary clipboard).
|
||||
* You can middle click to paste from the primary clipboard (on platforms
|
||||
* Selecting text automatically copies it to the primary clipboard (on platforms
|
||||
with a primary clipboard).
|
||||
* You can right click while holding :kbd:`ctrl+shift` to open the output
|
||||
of the clicked on command in a pager (requires :ref:`shell_integration`)
|
||||
* You can select text with kitty even when a terminal program has grabbed
|
||||
the mouse by holding down the :kbd:`shift` key
|
||||
* You can middle click to paste from the primary clipboard (on platforms with a
|
||||
primary clipboard).
|
||||
* You can right click while holding :kbd:`Ctrl+Shift` to open the output of the
|
||||
clicked on command in a pager (requires :ref:`shell_integration`)
|
||||
* You can select text with kitty even when a terminal program has grabbed the
|
||||
mouse by holding down the :kbd:`Shift` key
|
||||
|
||||
All these actions can be customized in :file:`kitty.conf` as described
|
||||
:ref:`here <conf-kitty-mouse.mousemap>`.
|
||||
|
||||
You can also customize what happens when clicking on :term:`hyperlinks` in kitty,
|
||||
having it open files in your editor, download remote files, open things
|
||||
You can also customize what happens when clicking on :term:`hyperlinks` in
|
||||
kitty, having it open files in your editor, download remote files, open things
|
||||
in your browser, etc.
|
||||
|
||||
For details, see :doc:`here <open_actions>`.
|
||||
@ -214,12 +221,11 @@ Font control
|
||||
-----------------
|
||||
|
||||
|kitty| has extremely flexible and powerful font selection features. You can
|
||||
specify individual families for the regular, bold, italic and bold+italic
|
||||
fonts. You can even specify specific font families for specific ranges of
|
||||
unicode characters. This allows precise control over text rendering. It can
|
||||
come in handy for applications like powerline, without the need to use patched
|
||||
fonts. See the various font related configuration directives in
|
||||
:ref:`conf-kitty-fonts`.
|
||||
specify individual families for the regular, bold, italic and bold+italic fonts.
|
||||
You can even specify specific font families for specific ranges of Unicode
|
||||
characters. This allows precise control over text rendering. It can comein handy
|
||||
for applications like powerline, without the need to use patched fonts. See the
|
||||
various font related configuration directives in :ref:`conf-kitty-fonts`.
|
||||
|
||||
|
||||
.. _scrollback:
|
||||
@ -229,28 +235,28 @@ The scrollback buffer
|
||||
|
||||
|kitty| supports scrolling back to view history, just like most terminals. You
|
||||
can use either keyboard shortcuts or the mouse scroll wheel to do so. However,
|
||||
|kitty| has an extra, neat feature. Sometimes you need to explore the
|
||||
scrollback buffer in more detail, maybe search for some text or refer to it
|
||||
side-by-side while typing in a follow-up command. |kitty| allows you to do this
|
||||
by pressing the :sc:`show_scrollback` key-combination, which will open the
|
||||
scrollback buffer in your favorite pager program (which is ``less`` by default).
|
||||
Colors and text formatting are preserved. You can explore the scrollback buffer
|
||||
comfortably within the pager.
|
||||
|kitty| has an extra, neat feature. Sometimes you need to explore the scrollback
|
||||
buffer in more detail, maybe search for some text or refer to it side-by-side
|
||||
while typing in a follow-up command. |kitty| allows you to do this by pressing
|
||||
the :sc:`show_scrollback` shortcut, which will open the scrollback buffer in
|
||||
your favorite pager program (which is :program:`less` by default). Colors and
|
||||
text formatting are preserved. You can explore the scrollback buffer comfortably
|
||||
within the pager.
|
||||
|
||||
Additionally, you can pipe the contents of the scrollback buffer to an
|
||||
arbitrary, command running in a new :term:`window`, :term:`tab` or :term:`overlay`,
|
||||
for example::
|
||||
arbitrary, command running in a new :term:`window`, :term:`tab` or
|
||||
:term:`overlay`. For example::
|
||||
|
||||
map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting less +G -R
|
||||
|
||||
Would open the scrollback buffer in a new :term:`window` when you press the :kbd:`F1`
|
||||
key. See :sc:`show_scrollback <show_scrollback>` for details.
|
||||
Would open the scrollback buffer in a new :term:`window` when you press the
|
||||
:kbd:`F1` key. See :sc:`show_scrollback <show_scrollback>` for details.
|
||||
|
||||
If you want to use it with an editor such as vim to get more powerful features,
|
||||
you can see tips for doing so, in :iss:`this thread <719>`.
|
||||
If you want to use it with an editor such as :program:`vim` to get more powerful
|
||||
features, you can see tips for doing so, in :iss:`this thread <719>`.
|
||||
|
||||
If you wish to store very large amounts of scrollback to view using the piping or
|
||||
:sc:`show_scrollback <show_scrollback>` features, you can use the
|
||||
If you wish to store very large amounts of scrollback to view using the piping
|
||||
or :sc:`show_scrollback <show_scrollback>` features, you can use the
|
||||
:opt:`scrollback_pager_history_size` option.
|
||||
|
||||
|
||||
@ -258,8 +264,8 @@ Integration with shells
|
||||
---------------------------------
|
||||
|
||||
kitty has the ability to integrate closely within common shells, such as `zsh
|
||||
<https://www.zsh.org/>`_, `fish <https://fishshell.com>`_ and `bash
|
||||
<https://www.gnu.org/software/bash/>`_ to enable features such as jumping to
|
||||
<https://www.zsh.org/>`__, `fish <https://fishshell.com>`__ and `bash
|
||||
<https://www.gnu.org/software/bash/>`__ to enable features such as jumping to
|
||||
previous prompts in the scrollback, viewing the output of the last command in
|
||||
:program:`less`, using the mouse to move the cursor while editing prompts, etc.
|
||||
See :doc:`shell-integration` for details.
|
||||
@ -274,17 +280,16 @@ See :doc:`shell-integration` for details.
|
||||
Multiple copy/paste buffers
|
||||
-----------------------------
|
||||
|
||||
In addition to being able to copy/paste from the system clipboard, in |kitty| you
|
||||
can also setup an arbitrary number of copy paste buffers. To do so, simply add
|
||||
something like the following to your :file:`kitty.conf`::
|
||||
In addition to being able to copy/paste from the system clipboard, in |kitty|
|
||||
you can also setup an arbitrary number of copy paste buffers. To do so, simply
|
||||
add something like the following to your :file:`kitty.conf`::
|
||||
|
||||
map f1 copy_to_buffer a
|
||||
map f2 paste_from_buffer a
|
||||
|
||||
This will allow you to press :kbd:`F1` to copy the current selection to an
|
||||
internal buffer named ``a`` and :kbd:`F2` to paste from that buffer. The buffer
|
||||
names are arbitrary strings, so you can define as many such buffers as you
|
||||
need.
|
||||
names are arbitrary strings, so you can define as many such buffers as you need.
|
||||
|
||||
|
||||
Marks
|
||||
|
||||
@ -2,30 +2,31 @@ Performance
|
||||
===================
|
||||
|
||||
The main goals for |kitty| performance are user perceived latency while typing
|
||||
and "smoothness" while scrolling as well as CPU usage. |kitty| tries hard to find
|
||||
an optimum balance for these. To that end it keeps a cache of each rendered
|
||||
glyph in video RAM so that font rendering is not a bottleneck. Interaction
|
||||
with child programs takes place in a separate thread from rendering, to improve
|
||||
and "smoothness" while scrolling as well as CPU usage. |kitty| tries hard to
|
||||
find an optimum balance for these. To that end it keeps a cache of each rendered
|
||||
glyph in video RAM so that font rendering is not a bottleneck. Interaction with
|
||||
child programs takes place in a separate thread from rendering, to improve
|
||||
smoothness.
|
||||
|
||||
There are two parameters you can tune to adjust the performance. :opt:`repaint_delay`
|
||||
and :opt:`input_delay`. These control the artificial delays introduced into the
|
||||
render loop to reduce CPU usage. See :ref:`conf-kitty-performance` for details.
|
||||
See also the :opt:`sync_to_monitor` option to further decrease latency at the cost
|
||||
of some `tearing <https://en.wikipedia.org/wiki/Screen_tearing>`_ while scrolling.
|
||||
There are two config options you can tune to adjust the performance,
|
||||
:opt:`repaint_delay` and :opt:`input_delay`. These control the artificial delays
|
||||
introduced into the render loop to reduce CPU usage. See
|
||||
:ref:`conf-kitty-performance` for details. See also the :opt:`sync_to_monitor`
|
||||
option to further decrease latency at the cost of some `screen tearing
|
||||
<https://en.wikipedia.org/wiki/Screen_tearing>`__ while scrolling.
|
||||
|
||||
You can generate detailed per-function performance data using `gperftools
|
||||
<https://github.com/gperftools/gperftools>`_. Build |kitty| with `make
|
||||
profile`. Run kitty and perform the task you want to analyse, for example,
|
||||
scrolling a large file with `less`. After you quit, function call statistics
|
||||
will be printed to `stdout` and you can use tools like *kcachegrind* for more
|
||||
detailed analysis.
|
||||
You can generate detailed per-function performance data using
|
||||
`gperftools <https://github.com/gperftools/gperftools>`__. Build |kitty| with
|
||||
``make profile``. Run kitty and perform the task you want to analyse, for
|
||||
example, scrolling a large file with :program:`less`. After you quit, function
|
||||
call statistics will be printed to STDOUT and you can use tools like
|
||||
*KCachegrind* for more detailed analysis.
|
||||
|
||||
Here are some CPU usage numbers for the task of scrolling a file continuously
|
||||
in less. The CPU usage is for the terminal process and X together and is
|
||||
measured using htop. The measurements are taken at the same font and window
|
||||
size for all terminals on a ``Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz`` CPU
|
||||
with a ``Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD
|
||||
Here are some CPU usage numbers for the task of scrolling a file continuously in
|
||||
:program:`less`. The CPU usage is for the terminal process and X together and is
|
||||
measured using :program:`htop`. The measurements are taken at the same font and
|
||||
window size for all terminals on a ``Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz``
|
||||
CPU with a ``Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD
|
||||
7770/8760 / R7 250X]`` GPU.
|
||||
|
||||
============== =========================
|
||||
@ -49,11 +50,11 @@ admittedly biased, eyes).
|
||||
|
||||
.. note::
|
||||
|
||||
Some people have asked why kitty does not perform better than terminal XXX in
|
||||
the test of sinking large amounts of data, such as catting a large text
|
||||
file. The answer is because this is not a goal for kitty. kitty
|
||||
deliberately throttles input parsing and output rendering to minimize
|
||||
resource usage while still being able to sink output faster than any real
|
||||
world program can produce it. Reducing CPU usage, and hence battery drain
|
||||
while achieving instant response times and smooth scrolling to a human eye
|
||||
is a far more important goal.
|
||||
Some people have asked why kitty does not perform better than terminal XXX
|
||||
in the test of sinking large amounts of data, such as catting a large text
|
||||
file. The answer is because this is not a goal for kitty. kitty deliberately
|
||||
throttles input parsing and output rendering to minimize resource usage
|
||||
while still being able to sink output faster than any real world program can
|
||||
produce it. Reducing CPU usage, and hence battery drain while achieving
|
||||
instant response times and smooth scrolling to a human eye is a far more
|
||||
important goal.
|
||||
|
||||
@ -1,23 +1,24 @@
|
||||
Terminal protocol extensions
|
||||
===================================
|
||||
|
||||
|kitty| has extensions to the legacy terminal protocol, to enable advanced features.
|
||||
These are typically in the form of new or re-purposed escape codes. While these
|
||||
extensions are currently |kitty| specific, it would be nice to get some of them
|
||||
adopted more broadly, to push the state of terminal emulators forward.
|
||||
|kitty| has extensions to the legacy terminal protocol, to enable advanced
|
||||
features. These are typically in the form of new or re-purposed escape codes.
|
||||
While these extensions are currently |kitty| specific, it would be nice to get
|
||||
some of them adopted more broadly, to push the state of terminal emulators
|
||||
forward.
|
||||
|
||||
The goal of these extensions is to be as small and unobtrusive as possible,
|
||||
while filling in some gaps in the existing xterm protocol. In particular, one
|
||||
of the goals of this specification is explicitly not to "re-imagine" the tty.
|
||||
The tty should remain what it is -- a device for efficiently processing text
|
||||
while filling in some gaps in the existing xterm protocol. In particular, one of
|
||||
the goals of this specification is explicitly not to "re-imagine" the TTY. The
|
||||
TTY should remain what it is -- a device for efficiently processing text
|
||||
received as a simple byte stream. Another objective is to only move the minimum
|
||||
possible amount of extra functionality into the terminal program itself. This
|
||||
is to make it as easy to implement these protocol extensions as possible,
|
||||
thereby hopefully encouraging their widespread adoption.
|
||||
possible amount of extra functionality into the terminal program itself. This is
|
||||
to make it as easy to implement these protocol extensions as possible, thereby
|
||||
hopefully encouraging their widespread adoption.
|
||||
|
||||
If you wish to discuss these extensions, propose additions/changes to them
|
||||
please do so by opening issues in the `GitHub
|
||||
<https://github.com/kovidgoyal/kitty/issues>`_ bug tracker.
|
||||
If you wish to discuss these extensions, propose additions or changes to them,
|
||||
please do so by opening issues in the `GitHub bug tracker
|
||||
<https://github.com/kovidgoyal/kitty/issues>`__.
|
||||
|
||||
|
||||
.. toctree::
|
||||
|
||||
@ -9,9 +9,9 @@ Quickstart
|
||||
binary
|
||||
build
|
||||
|
||||
Pre-built binaries of |kitty| are available for both macOS and Linux.
|
||||
See the :doc:`binary install instructions </binary>`. You can also
|
||||
:doc:`build from source </build>`.
|
||||
Pre-built binaries of |kitty| are available for both macOS and Linux. See the
|
||||
:doc:`binary install instructions </binary>`. You can also :doc:`build from
|
||||
source </build>`.
|
||||
|
||||
Additionally, you can use your favorite package manager to install the |kitty|
|
||||
package, but note that some Linux distribution packages are woefully outdated.
|
||||
@ -25,4 +25,4 @@ and Linux.
|
||||
See :doc:`Configuring kitty <conf>` for help on configuring |kitty| and
|
||||
:doc:`Invocation <invocation>` for the command line arguments |kitty| supports.
|
||||
|
||||
For a tour of kitty's design and features, see the :doc:`/overview`.
|
||||
For a tour of kitty's design and features, see the :doc:`overview`.
|
||||
|
||||
@ -16,25 +16,26 @@ Where ``<ESC>`` is the byte ``0x1b``. The JSON object has the form::
|
||||
"payload": <Optional JSON object>,
|
||||
}
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Set ``no_response`` to ``true`` if you don't want a response from kitty.
|
||||
|
||||
The optional payload is a JSON object that is specific to the actual command being sent.
|
||||
The fields in the object for every command are documented below.
|
||||
The optional payload is a JSON object that is specific to the actual command
|
||||
being sent. The fields in the object for every command are documented below.
|
||||
|
||||
As a quick example showing how easy to use this protocol is, we will implement
|
||||
the ``@ ls`` command from the shell using only shell tools. First, run kitty
|
||||
as::
|
||||
the ``@ ls`` command from the shell using only shell tools.
|
||||
|
||||
First, run kitty as::
|
||||
|
||||
kitty -o allow_remote_control=socket-only --listen-on unix:/tmp/test
|
||||
|
||||
Now, in a different terminal, you can get the pretty printed ``@ ls`` output
|
||||
with the following command line::
|
||||
|
||||
echo -en '\eP@kitty-cmd{"cmd":"ls","version":[0,14,2]}\e\' | socat - unix:/tmp/test | awk '{ print substr($0, 13, length($0) - 14) }' | jq -c '.data | fromjson' | jq .
|
||||
echo -en '\eP@kitty-cmd{"cmd":"ls","version":[0,14,2]}\e\\' | socat - unix:/tmp/test | awk '{ print substr($0, 13, length($0) - 14) }' | jq -c '.data | fromjson' | jq .
|
||||
|
||||
.. include:: generated/rc.rst
|
||||
|
||||
@ -4,8 +4,8 @@ Shell integration
|
||||
-------------------
|
||||
|
||||
kitty has the ability to integrate closely within common shells, such as `zsh
|
||||
<https://www.zsh.org/>`_, `fish <https://fishshell.com>`_ and `bash
|
||||
<https://www.gnu.org/software/bash/>`_ to enable features such as jumping to
|
||||
<https://www.zsh.org/>`__, `fish <https://fishshell.com>`__ and `bash
|
||||
<https://www.gnu.org/software/bash/>`__ to enable features such as jumping to
|
||||
previous prompts in the scrollback, viewing the output of the last command in
|
||||
:program:`less`, using the mouse to move the cursor while editing prompts, etc.
|
||||
|
||||
@ -22,7 +22,7 @@ Features
|
||||
|
||||
* Click with the mouse anywhere in the current command to move the cursor there
|
||||
|
||||
* Hold :kbd:`ctrl+shift` and right-click on any command output in the scrollback
|
||||
* Hold :kbd:`Ctrl+Shift` and right-click on any command output in the scrollback
|
||||
to view it in a pager
|
||||
|
||||
* The current working directory or the command being executed are automatically
|
||||
@ -30,7 +30,8 @@ Features
|
||||
|
||||
* The text cursor is changed to a bar when editing commands at the shell prompt
|
||||
|
||||
* :ref:`clone_shell` with all environment variables and the working directory copied
|
||||
* :ref:`clone_shell` with all environment variables and the working directory
|
||||
copied
|
||||
|
||||
* Glitch free window resizing even with complex prompts. Achieved by erasing
|
||||
the prompt on resize and allowing the shell to redraw it cleanly.
|
||||
@ -45,7 +46,7 @@ Configuration
|
||||
---------------
|
||||
|
||||
Shell integration is controlled by the :opt:`shell_integration` option. By
|
||||
default, all shell integration is enabled. Individual features can be turned
|
||||
default, all integration features are enabled. Individual features can be turned
|
||||
off or it can be disabled entirely as well. The :opt:`shell_integration` option
|
||||
takes a space separated list of keywords:
|
||||
|
||||
@ -55,26 +56,28 @@ disabled
|
||||
:ref:`manual integration <manual_shell_integration>`.
|
||||
|
||||
no-rc
|
||||
Do not modify the shell's launch environment to enable integration. Useful if you prefer
|
||||
to load the kitty shell integration code yourself, either as part of
|
||||
:ref:`manually integration <manual_shell_integration>` or because you have
|
||||
some other software that sets up shell integration.
|
||||
This will still set the :envvar:`KITTY_SHELL_INTEGRATION` environment variable when kitty runs the shell.
|
||||
Do not modify the shell's launch environment to enable integration. Useful
|
||||
if you prefer to load the kitty shell integration code yourself, either as
|
||||
part of :ref:`manually integration <manual_shell_integration>` or because
|
||||
you have some other software that sets up shell integration.
|
||||
This will still set the :envvar:`KITTY_SHELL_INTEGRATION` environment
|
||||
variable when kitty runs the shell.
|
||||
|
||||
no-cursor
|
||||
Turn off changing of the text cursor to a bar when editing text
|
||||
Turn off changing of the text cursor to a bar when editing shell command
|
||||
line.
|
||||
|
||||
no-title
|
||||
Turn off setting the kitty window/tab title based on shell state.
|
||||
Note that for the ``fish`` shell kitty relies on fish's native title
|
||||
setting functionality instead.
|
||||
Note that for the fish shell kitty relies on fish's native title setting
|
||||
functionality instead.
|
||||
|
||||
no-cwd
|
||||
Turn off reporting the current working directory. This is used to allow
|
||||
:ac:`new_window_with_cwd` and similar to open windows logged
|
||||
into remote machines using the :doc:`ssh kitten <kittens/ssh>`
|
||||
automatically with the same working directory as the current window.
|
||||
Note that for the ``fish`` shell this will not disable its built-in current
|
||||
:ac:`new_window_with_cwd` and similar to open windows logged into remote
|
||||
machines using the :doc:`ssh kitten <kittens/ssh>` automatically with the
|
||||
same working directory as the current window.
|
||||
Note that for the fish shell this will not disable its built-in current
|
||||
working directory reporting.
|
||||
|
||||
no-prompt-mark
|
||||
@ -83,16 +86,16 @@ no-prompt-mark
|
||||
|
||||
no-complete
|
||||
Turn off completion for the kitty command.
|
||||
Note that for the ``fish`` shell this does not take effect, since fish
|
||||
already comes with a kitty completion script.
|
||||
Note that for the fish shell this does not take effect, since fish already
|
||||
comes with a kitty completion script.
|
||||
|
||||
|
||||
More ways to browse command output
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You can add further key and mouse bindings to browse the output of commands
|
||||
easily. For example to select the output of a command by right clicking the mouse
|
||||
on the output, define the following in :file:`kitty.conf`:
|
||||
easily. For example to select the output of a command by right clicking the
|
||||
mouse on the output, define the following in :file:`kitty.conf`:
|
||||
|
||||
.. code:: conf
|
||||
|
||||
@ -103,8 +106,8 @@ to be copied.
|
||||
|
||||
The feature to jump to previous prompts (
|
||||
:sc:`scroll_to_previous_prompt` and :sc:`scroll_to_next_prompt`) and mouse
|
||||
actions (:ac:`mouse_select_command_output` and :ac:`mouse_show_command_output`) can
|
||||
be integrated with browsing command output as well. For example, define the
|
||||
actions (:ac:`mouse_select_command_output` and :ac:`mouse_show_command_output`)
|
||||
can be integrated with browsing command output as well. For example, define the
|
||||
following mapping in :file:`kitty.conf`:
|
||||
|
||||
.. code:: conf
|
||||
@ -136,34 +139,34 @@ How it works
|
||||
-----------------
|
||||
|
||||
At startup, kitty detects if the shell you have configured (either system wide
|
||||
or in kitty.conf) is a supported shell. If so, kitty injects some shell specific
|
||||
code into the shell, to enable shell integration. How it does so varies for
|
||||
different shells.
|
||||
or the :opt:`shell` option in :file:`kitty.conf`) is a supported shell. If so,
|
||||
kitty injects some shell specific code into the shell, to enable shell
|
||||
integration. How it does so varies for different shells.
|
||||
|
||||
|
||||
.. tab:: zsh
|
||||
|
||||
For zsh, kitty sets the ``ZDOTDIR`` environment variable to make zsh load
|
||||
kitty's :file:`.zshenv` which restores the original value of ``ZDOTDIR``
|
||||
and sources the original :file:`.zshenv`. It then loads the shell integration code.
|
||||
The remainder of zsh's startup process proceeds as normal.
|
||||
For zsh, kitty sets the :envvar:`ZDOTDIR` environment variable to make zsh
|
||||
load kitty's :file:`.zshenv` which restores the original value of
|
||||
:envvar:`ZDOTDIR` and sources the original :file:`.zshenv`. It then loads
|
||||
the shell integration code. The remainder of zsh's startup process proceeds
|
||||
as normal.
|
||||
|
||||
.. tab:: fish
|
||||
|
||||
For fish, to make it automatically load the integration code provided by
|
||||
kitty, the integration script directory path is prepended to the
|
||||
``XDG_DATA_DIRS`` environment variable. This is only applied to the fish
|
||||
process and will be cleaned up by the integration script after startup. No files
|
||||
are added or modified.
|
||||
:envvar:`XDG_DATA_DIRS` environment variable. This is only applied to the
|
||||
fish process and will be cleaned up by the integration script after startup.
|
||||
No files are added or modified.
|
||||
|
||||
.. tab:: bash
|
||||
|
||||
For bash, kitty starts bash in POSIX mode, using the environment variable
|
||||
``ENV`` to load the shell integration script. This prevents bash from
|
||||
:envvar:`ENV` to load the shell integration script. This prevents bash from
|
||||
loading any startup files itself. The loading of the startup files is done
|
||||
by the integration script, after disabling POSIX mode. From the
|
||||
perspective of those scripts there should be no difference to running
|
||||
vanilla bash.
|
||||
by the integration script, after disabling POSIX mode. From the perspective
|
||||
of those scripts there should be no difference to running vanilla bash.
|
||||
|
||||
|
||||
Then, when launching the shell, kitty sets the environment variable
|
||||
@ -232,8 +235,8 @@ You can clone the current shell into a new kitty window by simply running the
|
||||
clone-in-kitty --title "I am a clone"
|
||||
|
||||
This will open a new window running a new shell instance but with all
|
||||
environment variables and the current working directory copied. This even
|
||||
works over SSH when using :doc:`kittens/ssh`.
|
||||
environment variables and the current working directory copied. This even works
|
||||
over SSH when using :doc:`kittens/ssh`.
|
||||
|
||||
The :command:`clone-in-kitty` command takes almost all the same arguments as the
|
||||
:doc:`launch <launch>` command, so you can open a new tab instead or a new OS
|
||||
@ -321,9 +324,10 @@ to point to the location of the scripts.
|
||||
Integration with other shells
|
||||
-------------------------------
|
||||
|
||||
There exist third-party integrations to use these features for various other shells:
|
||||
There exist third-party integrations to use these features for various other
|
||||
shells:
|
||||
|
||||
* Jupyter console via a patch (:iss:`4475`)
|
||||
* Jupyter console and IPython via a patch (:iss:`4475`)
|
||||
* `xonsh <https://github.com/xonsh/xonsh/issues/4623>`__
|
||||
|
||||
|
||||
|
||||
@ -1,24 +1,25 @@
|
||||
Colored and styled underlines
|
||||
================================
|
||||
|
||||
|kitty| supports colored and styled (wavy) underlines. This is of particular
|
||||
use in terminal editors such as vim and emacs to display red, wavy underlines
|
||||
under mis-spelled words and/or syntax errors. This is done by re-purposing some
|
||||
SGR escape codes that are not used in modern terminals (`CSI codes
|
||||
<https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_(Control_Sequence_Introducer)_sequences>`_)
|
||||
|kitty| supports colored and styled (wavy) underlines. This is of particular use
|
||||
in terminal based text editors such as :program:`vim` and :program:`emacs` to
|
||||
display red, wavy underlines under mis-spelled words and/or syntax errors. This
|
||||
is done by re-purposing some SGR escape codes that are not used in modern
|
||||
terminals (`CSI codes <https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_(Control_Sequence_Introducer)_sequences>`__)
|
||||
|
||||
To set the underline style::
|
||||
|
||||
<ESC>[4:0m # this is no underline
|
||||
<ESC>[4:1m # this is a straight underline
|
||||
<ESC>[4:2m # this is a double underline
|
||||
<ESC>[4:3m # this is a curly underline
|
||||
<ESC>[4:4m # this is a dotted underline
|
||||
<ESC>[4:5m # this is a dashed underline
|
||||
<ESC>[4m # this is a straight underline (for backwards compat)
|
||||
<ESC>[24m # this is no underline (for backwards compat)
|
||||
<ESC>[4:0m # no underline
|
||||
<ESC>[4:1m # straight underline
|
||||
<ESC>[4:2m # double underline
|
||||
<ESC>[4:3m # curly underline
|
||||
<ESC>[4:4m # dotted underline
|
||||
<ESC>[4:5m # dashed underline
|
||||
<ESC>[4m # straight underline (for backwards compat)
|
||||
<ESC>[24m # no underline (for backwards compat)
|
||||
|
||||
To set the underline color (this is reserved and as far as I can tell not actually used for anything)::
|
||||
To set the underline color (this is reserved and as far as I can tell not
|
||||
actually used for anything)::
|
||||
|
||||
<ESC>[58...m
|
||||
|
||||
@ -29,8 +30,8 @@ To reset the underline color (also previously reserved and unused)::
|
||||
|
||||
<ESC>[59m
|
||||
|
||||
The underline color must remain the same under reverse video, if it has a
|
||||
color, if not, it should follow the foreground color.
|
||||
The underline color must remain the same under reverse video, if it has a color,
|
||||
if not, it should follow the foreground color.
|
||||
|
||||
To detect support for this feature in a terminal emulator, query the terminfo database
|
||||
for the ``Su`` boolean capability.
|
||||
To detect support for this feature in a terminal emulator, query the terminfo
|
||||
database for the ``Su`` boolean capability.
|
||||
|
||||
@ -4,10 +4,10 @@ Unscrolling the screen
|
||||
========================
|
||||
|
||||
This is a small extension to the `SD (Pan up) escape code
|
||||
<https://vt100.net/docs/vt510-rm/SD.html>`_ from the VT-420 terminal. The
|
||||
``SD`` escape code normally causes the text on screen to scroll down by the
|
||||
specified number of lines, with empty lines appearing at the top of the screen.
|
||||
This extension allows the new lines to be filled in from the scrollback buffer
|
||||
<https://vt100.net/docs/vt510-rm/SD.html>`_ from the VT-420 terminal. The ``SD``
|
||||
escape code normally causes the text on screen to scroll down by the specified
|
||||
number of lines, with empty lines appearing at the top of the screen. This
|
||||
extension allows the new lines to be filled in from the scrollback buffer
|
||||
instead of being blank.
|
||||
|
||||
The motivation for this is that many modern shells will show completions in a
|
||||
@ -22,17 +22,17 @@ scrolled down is implementation defined, but must be at least one screen worth.
|
||||
|
||||
The syntax of the escape code is identical to that of ``SD`` except that it has
|
||||
a trailing ``+`` modifier. This is legal under the `ECMA 48 standard
|
||||
<https://www.ecma-international.org/publications-and-standards/standards/ecma-48/>`_
|
||||
<https://www.ecma-international.org/publications-and-standards/standards/ecma-48/>`__
|
||||
and unused for any other purpose as far as I can tell. So for example, to
|
||||
unscroll three lines, the escape code would be::
|
||||
|
||||
CSI 3 + T
|
||||
|
||||
See `discussion here
|
||||
<https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/30>`_.
|
||||
<https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/30>`__.
|
||||
|
||||
.. versionadded:: 0.20.2
|
||||
|
||||
Also supported by the terminals:
|
||||
|
||||
* `mintty <https://github.com/mintty/mintty/releases/tag/3.5.2>`_
|
||||
* `mintty <https://github.com/mintty/mintty/releases/tag/3.5.2>`__
|
||||
|
||||
@ -136,6 +136,8 @@ Within a single kitty instance, all connections to a particular server can be
|
||||
shared. This reduces startup latency for subsequent connections and means that
|
||||
you have to enter the password only once. Under the hood, it uses SSH
|
||||
ControlMasters and these are automatically cleaned up by kitty when it quits.
|
||||
You can map a shortcut to :ac:`close_shared_ssh_connections` to disconnect all
|
||||
active shared connections.
|
||||
''')
|
||||
|
||||
opt('askpass', 'unless-set', choices=('unless-set', 'ssh', 'native'), long_text='''
|
||||
|
||||
@ -2245,7 +2245,11 @@ class Boss:
|
||||
output = '\n'.join(f'{k}={v}' for k, v in os.environ.items())
|
||||
self.display_scrollback(w, output, title=_('Current kitty env vars'), report_cursor=False)
|
||||
|
||||
@ac('debug', 'Close all shared SSH connections')
|
||||
@ac('debug', '''
|
||||
Close all shared SSH connections
|
||||
|
||||
See :opt:`share_connections <kitten-ssh.share_connections>` for details.
|
||||
''')
|
||||
def close_shared_ssh_connections(self) -> None:
|
||||
cleanup_ssh_control_masters()
|
||||
|
||||
|
||||
164
kitty/launch.py
164
kitty/launch.py
@ -36,51 +36,51 @@ def options_spec() -> str:
|
||||
return '''
|
||||
--window-title --title
|
||||
The title to set for the new window. By default, title is controlled by the
|
||||
child process. The special value :code:`current` will copy the title from the currently
|
||||
active window.
|
||||
child process. The special value :code:`current` will copy the title from the
|
||||
currently active window.
|
||||
|
||||
|
||||
--tab-title
|
||||
The title for the new tab if launching in a new tab. By default, the title
|
||||
of the active window in the tab is used as the tab title. The special value
|
||||
:code:`current` will copy the title form the title of the currently active tab.
|
||||
:code:`current` will copy the title from the title of the currently active tab.
|
||||
|
||||
|
||||
--type
|
||||
type=choices
|
||||
default=window
|
||||
choices=window,tab,os-window,overlay,background,clipboard,primary
|
||||
Where to launch the child process, in a new kitty window in the current tab,
|
||||
a new tab, or a new OS window or an overlay over the current window.
|
||||
Note that if the current window already has an overlay, then it will
|
||||
open a new window. The value of background means the process will be
|
||||
run in the background. The values clipboard and primary are meant
|
||||
to work with :option:`launch --stdin-source` to copy data to the system
|
||||
clipboard or primary selection.
|
||||
Where to launch the child process, in a new kitty :code:`window` in the current
|
||||
tab, a new :code:`tab`, or a new :code:`os-window` or an :code:`overlay` over
|
||||
the current window. Note that if the current window already has an overlay, then
|
||||
it will open a new window. The value of :code:`background` means the process
|
||||
will be run in the background. The values :code:`clipboard` and :code:`primary`
|
||||
are meant to work with :option:`--stdin-source <launch --stdin-source>` to copy
|
||||
data to the system clipboard or primary selection.
|
||||
|
||||
|
||||
--keep-focus --dont-take-focus
|
||||
type=bool-set
|
||||
Keep the focus on the currently active window instead of switching
|
||||
to the newly opened window.
|
||||
Keep the focus on the currently active window instead of switching to the newly
|
||||
opened window.
|
||||
|
||||
|
||||
--cwd
|
||||
The working directory for the newly launched child. Use the special value
|
||||
:code:`current` to use the working directory of the currently active window.
|
||||
The special value :code:`last_reported` uses the last working directory
|
||||
reported by the shell (needs :ref:`shell_integration` to work). The special
|
||||
value :code:`oldest` works like :code:`current` but uses the working directory
|
||||
of the oldest foreground process associated with the currently active window
|
||||
rather than the newest foreground process.
|
||||
The special value :code:`last_reported` uses the last working directory reported
|
||||
by the shell (needs :ref:`shell_integration` to work). The special value
|
||||
:code:`oldest` works like :code:`current` but uses the working directory of the
|
||||
oldest foreground process associated with the currently active window rather
|
||||
than the newest foreground process.
|
||||
|
||||
|
||||
--env
|
||||
type=list
|
||||
Environment variables to set in the child process. Can be specified multiple
|
||||
times to set different environment variables. Syntax: :code:`name=value`.
|
||||
Using :code:`name=` will set to empty string and just :code:`name` will
|
||||
remove the environment variable.
|
||||
times to set different environment variables. Syntax: :code:`name=value`. Using
|
||||
:code:`name=` will set to empty string and just :code:`name` will remove the
|
||||
environment variable.
|
||||
|
||||
|
||||
--hold
|
||||
@ -102,121 +102,129 @@ currently active window.
|
||||
|
||||
--copy-env
|
||||
type=bool-set
|
||||
Copy the environment variables from the currently active window into the
|
||||
newly launched child process. Note that most shells only set environment
|
||||
variables for child processes, so this will only copy the environment
|
||||
variables that the shell process itself has not the environment variables
|
||||
child processes inside the shell see. To copy that enviroment, use the
|
||||
kitty remote control feature with :code:`kitty @launch --copy-env`.
|
||||
Copy the environment variables from the currently active window into the newly
|
||||
launched child process. Note that most shells only set environment variables for
|
||||
child processes, so this will only copy the environment variables that the shell
|
||||
process itself has, not the environment variables child processes inside the
|
||||
shell see. To copy that enviroment, use the kitty remote control feature with
|
||||
:option:`kitty @ launch --copy-env`, and the :ref:`clone-in-kitty <clone_shell>`
|
||||
feature can also be used.
|
||||
|
||||
|
||||
--location
|
||||
type=choices
|
||||
default=default
|
||||
choices=first,after,before,neighbor,last,vsplit,hsplit,split,default
|
||||
Where to place the newly created window when it is added to a tab which
|
||||
already has existing windows in it. :code:`after` and :code:`before` place the new
|
||||
window before or after the active window. :code:`neighbor` is a synonym for :code:`after`.
|
||||
Also applies to creating a new tab, where the value of :code:`after`
|
||||
will cause the new tab to be placed next to the current tab instead of at the end.
|
||||
The values of :code:`vsplit`, :code:`hsplit` and :code:`split` are only used by the
|
||||
:code:`splits` layout and control if the new window is placed in a vertical,
|
||||
horizontal or automatic split with the currently active window. The default is
|
||||
to place the window in a layout dependent manner, typically, after the
|
||||
currently active window.
|
||||
Where to place the newly created window when it is added to a tab which already
|
||||
has existing windows in it. :code:`after` and :code:`before` place the new
|
||||
window before or after the active window. :code:`neighbor` is a synonym for
|
||||
:code:`after`. Also applies to creating a new tab, where the value of
|
||||
:code:`after` will cause the new tab to be placed next to the current tab
|
||||
instead of at the end. The values of :code:`vsplit`, :code:`hsplit` and
|
||||
:code:`split` are only used by the :code:`splits` layout and control if the new
|
||||
window is placed in a vertical, horizontal or automatic split with the currently
|
||||
active window. The default is to place the window in a layout dependent manner,
|
||||
typically, after the currently active window.
|
||||
|
||||
|
||||
--allow-remote-control
|
||||
type=bool-set
|
||||
Programs running in this window can control kitty (if remote control is
|
||||
enabled). Note that any program with the right level of permissions can still
|
||||
write to the pipes of any other program on the same computer and therefore can
|
||||
control kitty. It can, however, be useful to block programs running on other
|
||||
computers (for example, over ssh) or as other users.
|
||||
Programs running in this window can control kitty (even if remote control is not
|
||||
enabled in :file:`kitty.conf`). Note that any program with the right level of
|
||||
permissions can still write to the pipes of any other program on the same
|
||||
computer and therefore can control kitty. It can, however, be useful to block
|
||||
programs running on other computers (for example, over SSH) or as other users.
|
||||
|
||||
|
||||
--stdin-source
|
||||
type=choices
|
||||
default=none
|
||||
choices=none,@selection,@screen,@screen_scrollback,@alternate,@alternate_scrollback,@first_cmd_output_on_screen,@last_cmd_output,@last_visited_cmd_output
|
||||
Pass the screen contents as :code:`STDIN` to the child process. :code:`@selection` is
|
||||
the currently selected text. :code:`@screen` is the contents of the currently active
|
||||
window. :code:`@screen_scrollback` is the same as :code:`@screen`, but includes the
|
||||
scrollback buffer as well. :code:`@alternate` is the secondary screen of the current
|
||||
active window. For example if you run a full screen terminal application, the
|
||||
secondary screen will be the screen you return to when quitting the application.
|
||||
:code:`@first_cmd_output_on_screen` is the output from the first command run in the shell on screen,
|
||||
:code:`@last_cmd_output` is the output from the last command run in the shell,
|
||||
:code:`@last_visited_cmd_output` is the first output below the last scrolled position via
|
||||
scroll_to_prompt, this three needs :ref:`shell_integration` to work.
|
||||
Pass the screen contents as :file:`STDIN` to the child process.
|
||||
:code:`@selection` is the currently selected text. :code:`@screen` is the
|
||||
contents of the currently active window. :code:`@screen_scrollback` is the same
|
||||
as :code:`@screen`, but includes the scrollback buffer as well.
|
||||
:code:`@alternate` is the secondary screen of the current active window. For
|
||||
example if you run a full screen terminal application, the secondary screen will
|
||||
be the screen you return to when quitting the application.
|
||||
:code:`@first_cmd_output_on_screen` is the output from the first command run in
|
||||
the shell on screen, :code:`@last_cmd_output` is the output from the last
|
||||
command run in the shell, :code:`@last_visited_cmd_output` is the first output
|
||||
below the last scrolled position via :ac:`scroll_to_prompt`, this three needs
|
||||
:ref:`shell integration <shell_integration>` to work.
|
||||
|
||||
|
||||
--stdin-add-formatting
|
||||
type=bool-set
|
||||
When using :option:`launch --stdin-source` add formatting escape codes, without this
|
||||
only plain text will be sent.
|
||||
When using :option:`--stdin-source <launch --stdin-source>` add formatting
|
||||
escape codes, without this only plain text will be sent.
|
||||
|
||||
|
||||
--stdin-add-line-wrap-markers
|
||||
type=bool-set
|
||||
When using :option:`launch --stdin-source` add a carriage return at every line wrap
|
||||
location (where long lines are wrapped at screen edges). This is useful if you
|
||||
want to pipe to program that wants to duplicate the screen layout of the
|
||||
screen.
|
||||
When using :option:`--stdin-source <launch --stdin-source>` add a carriage
|
||||
return at every line wrap location (where long lines are wrapped at screen
|
||||
edges). This is useful if you want to pipe to program that wants to duplicate
|
||||
the screen layout of the screen.
|
||||
|
||||
|
||||
--marker
|
||||
Create a marker that highlights text in the newly created window. The syntax is
|
||||
the same as for the :code:`toggle_marker` map action (see :doc:`/marks`).
|
||||
the same as for the :ac:`toggle_marker` action (see :doc:`/marks`).
|
||||
|
||||
|
||||
--os-window-class
|
||||
Set the WM_CLASS property on X11 and the application id property on Wayland for
|
||||
the newly created OS Window when using :option:`launch --type`=os-window.
|
||||
Defaults to whatever is used by the parent kitty process, which in turn
|
||||
defaults to :code:`kitty`.
|
||||
Set the *WM_CLASS* property on X11 and the application id property on Wayland
|
||||
for the newly created OS window when using :option:`--type=os-window
|
||||
<launch --type>`. Defaults to whatever is used by the parent kitty process,
|
||||
which in turn defaults to :code:`kitty`.
|
||||
|
||||
|
||||
--os-window-name
|
||||
Set the WM_NAME property on X11 for the newly created OS Window when using
|
||||
:option:`launch --type`=os-window. Defaults to :option:`launch --os-window-class`.
|
||||
Set the *WM_NAME* property on X11 for the newly created OS Window when using
|
||||
:option:`--type=os-window <launch --type>`. Defaults to
|
||||
:option:`--os-window-class <launch --os-window-class>`.
|
||||
|
||||
|
||||
--os-window-title
|
||||
Set the title for the newly created OS window. This title will override any
|
||||
titles set by programs running in kitty. The special value :code:`current`
|
||||
will use the title of the current OS Window, if any.
|
||||
titles set by programs running in kitty. The special value :code:`current` will
|
||||
use the title of the current OS window, if any.
|
||||
|
||||
|
||||
--logo
|
||||
Path to a PNG image to use as the logo for the newly created window. See :opt:`window_logo_path`.
|
||||
Path to a PNG image to use as the logo for the newly created window. See
|
||||
:opt:`window_logo_path`.
|
||||
|
||||
|
||||
--logo-position
|
||||
The position for the window logo. Only takes effect if :option:`--logo` is specified. See :opt:`window_logo_position`.
|
||||
The position for the window logo. Only takes effect if :option:`--logo` is
|
||||
specified. See :opt:`window_logo_position`.
|
||||
|
||||
|
||||
--logo-alpha
|
||||
type=float
|
||||
default=-1
|
||||
The amount the window logo should be faded into the background.
|
||||
Only takes effect if :option:`--logo` is specified. See :opt:`window_logo_position`.
|
||||
The amount the window logo should be faded into the background. Only takes
|
||||
effect if :option:`--logo` is specified. See :opt:`window_logo_position`.
|
||||
|
||||
|
||||
--color
|
||||
type=list
|
||||
Change colors in the newly launched window. You can either specify a path to a .conf
|
||||
file with the same syntax as kitty.conf to read the colors from, or specify them
|
||||
individually, for example: ``--color background=white`` ``--color foreground=red``
|
||||
Change colors in the newly launched window. You can either specify a path to a
|
||||
:file:`.conf` file with the same syntax as :file:`kitty.conf` to read the colors
|
||||
from, or specify them individually, for example: ``--color background=white``
|
||||
``--color foreground=red``
|
||||
|
||||
|
||||
--watcher -w
|
||||
type=list
|
||||
Path to a python file. Appropriately named functions in this file will be called
|
||||
for various events, such as when the window is resized, focused or closed. See the section
|
||||
on watchers in the launch command documentation: :ref:`watchers`. Relative paths are
|
||||
resolved relative to the kitty config directory. Global watchers for all windows can be
|
||||
specified with :opt:`watcher`.
|
||||
Path to a Python file. Appropriately named functions in this file will be called
|
||||
for various events, such as when the window is resized, focused or closed. See
|
||||
the section on watchers in the launch command documentation: :ref:`watchers`.
|
||||
Relative paths are resolved relative to the :ref:`kitty config directory
|
||||
<confloc>`. Global watchers for all windows can be specified with
|
||||
:opt:`watcher` in :file:`kitty.conf`.
|
||||
'''
|
||||
|
||||
|
||||
|
||||
@ -58,7 +58,7 @@
|
||||
// National Replacement Character Set Mode
|
||||
#define DECNRCM (42 << 5)
|
||||
|
||||
// Xterm mouse protocol
|
||||
// xterm mouse protocol
|
||||
#define MOUSE_BUTTON_TRACKING (1000 << 5)
|
||||
#define MOUSE_MOTION_TRACKING (1002 << 5)
|
||||
#define MOUSE_MOVE_TRACKING (1003 << 5)
|
||||
|
||||
@ -1001,7 +1001,7 @@ dispatch_csi(Screen *screen, PyObject DUMP_UNUSED *dump_callback) {
|
||||
case 'm':
|
||||
if (start_modifier == '>' && !end_modifier) {
|
||||
REPORT_ERROR(
|
||||
"The application is trying to use XTerm's modifyOtherKeys."
|
||||
"The application is trying to use xterm's modifyOtherKeys."
|
||||
" This is superseded by the kitty keyboard protocol: https://sw.kovidgoyal.net/kitty/keyboard-protocol/"
|
||||
" the application should be updated to use that"
|
||||
);
|
||||
|
||||
@ -112,7 +112,7 @@ Where :italic:`field` can be one of: :code:`id`, :code:`index`, :code:`title`, :
|
||||
:italic:`query` is the expression to match. Expressions can be either a number or a regular expression, and can be
|
||||
:ref:`combined using Boolean operators <search_syntax>`.
|
||||
|
||||
The special value :code:`all` matches all windows.
|
||||
The special value :code:`all` matches all tabs.
|
||||
|
||||
For numeric fields: :code:`id`, :code:`index`, :code:`window_id`, :code:`pid` and :code:`recent`, the
|
||||
expression is interpreted as a number, not a regular expression.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user