mirrors/kitty
1
0
Fork 0
mirror of https://github.com/kovidgoyal/kitty synced 2026-07-06 08:01:58 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'docs' of https://github.com/page-down/kitty

Browse Source
This commit is contained in:
Kovid Goyal
2022-04-25 14:16:16 +05:30
parent 9edb772a81 c4710bf9cb
commit 8e98fcf2f6
7 changed files with 240 additions and 210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

190
docs/faq.rst
View File

@@ -27,14 +27,15 @@ turned off for specific symbols using :opt:`narrow_symbols`.
Using a color theme with a background color does not work well in vim?
-----------------------------------------------------------------------
First make sure you have not changed the TERM environment variable, it should
be ``xterm-kitty``. vim uses *background color erase* even if the terminfo file
does not contain the ``bce`` capability. This is a bug in vim. You can work around
it by adding the following to your vimrc::
First make sure you have not changed the :envvar:`TERM` environment variable, it
should be ``xterm-kitty``. vim uses *background color erase* even if the
terminfo file does not contain the ``bce`` capability. This is a bug in vim. You
can work around it by adding the following to your vimrc::
let &t_ut=''
See :doc:`here <deccara>` for why |kitty| does not support background color erase.
See :doc:`here <deccara>` for why |kitty| does not support background color
erase.
I get errors about the terminal being unknown or opening the terminal failing when SSHing into a different computer?
@@ -47,26 +48,26 @@ terminfo files to the server::
kitty +kitten ssh myserver
This :doc:`ssh kitten <kittens/ssh>` takes all the same command line arguments
as ssh, you can alias it to something small in your shell's rc files to avoid
having to type it each time::
as :program:`ssh`, you can alias it to something small in your shell's rc files
to avoid having to type it each time::
alias s="kitty +kitten ssh"
If the ssh kitten fails, use the following one-liner instead (it
is slower as it needs to ssh into the server twice, but will work with most
servers)::
If the ssh kitten fails, use the following one-liner instead (it is slower as it
needs to ssh into the server twice, but will work with most servers)::
infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin
If you are behind a proxy (like Balabit) that prevents this, or ``tic`` comes
with macOS that does not support reading from STDIN, you must redirect the 1st
command to a file, copy that to the server and run ``tic`` manually. If you
connect to a server, embedded or Android system that doesn't have ``tic``, copy over
your local file terminfo to the other system as :file:`~/.terminfo/x/xterm-kitty`.
If you are behind a proxy (like Balabit) that prevents this, or :program:`tic`
comes with macOS that does not support reading from STDIN, you must redirect the
first command to a file, copy that to the server and run :program:`tic`
manually. If you connect to a server, embedded or Android system that doesn't
have :program:`tic`, copy over your local file terminfo to the other system as
:file:`~/.terminfo/x/xterm-kitty`.
Really, the correct solution for this is to convince the OpenSSH maintainers to
have ssh do this automatically, if possible, when connecting to a server, so that
all terminals work transparently.
have :program:`ssh` do this automatically, if possible, when connecting to a
server, so that all terminals work transparently.
If the server is running FreeBSD, or another system that relies on termcap
rather than terminfo, you will need to convert the terminfo file on your local
@@ -84,9 +85,9 @@ command to apply your change (on the server)::
Keys such as arrow keys, backspace, delete, home/end, etc. do not work when using su or sudo?
-------------------------------------------------------------------------------------------------
Make sure the TERM environment variable, is ``xterm-kitty``. And either the
TERMINFO environment variable points to a directory containing :file:`x/xterm-kitty`
or that file is under :file:`~/.terminfo/x/`.
Make sure the :envvar:`TERM` environment variable, is ``xterm-kitty``. And
either the :envvar:`TERMINFO` environment variable points to a directory
containing :file:`x/xterm-kitty` or that file is under :file:`~/.terminfo/x/`.
For macOS, you may also need to put that file under :file:`~/.terminfo/78/`::
@@ -94,18 +95,19 @@ For macOS, you may also need to put that file under :file:`~/.terminfo/78/`::
ln -snf ../x/xterm-kitty ~/.terminfo/78/xterm-kitty
tic -x -o ~/.terminfo "$KITTY_INSTALLATION_DIR/terminfo/kitty.terminfo"
Note that ``sudo`` might remove TERMINFO. Then setting it at the shell prompt can
be too late, because command line editing may not be reinitialized. In that case
you can either ask ``sudo`` to set it or if that is not supported, insert an ``env``
command before starting the shell, or, if not possible, after sudo start another
Shell providing the right terminfo path::
Note that :program:`sudo` might remove :envvar:`TERMINFO`. Then setting it at
the shell prompt can be too late, because command line editing may not be
reinitialized. In that case you can either ask :program:`sudo` to set it or if
that is not supported, insert an :program:`env` command before starting the
shell, or, if not possible, after sudo start another shell providing the right
terminfo path::
sudo … TERMINFO=$HOME/.terminfo bash -i
sudo … env TERMINFO=$HOME/.terminfo bash -i
TERMINFO=/home/ORIGINALUSER/.terminfo exec bash -i
You can configure sudo to preserve TERMINFO by running ``sudo
visudo`` and adding the following line::
You can configure :program:`sudo` to preserve :envvar:`TERMINFO` by running
``sudo visudo`` and adding the following line::
Defaults env_keep += "TERM TERMINFO"
@@ -129,15 +131,15 @@ You can also define keyboard shortcuts to set colors, for example::
map f1 set_colors --configured /path/to/some/config/file/colors.conf
Or you can enable :doc:`remote control <remote-control>` for |kitty| and use :ref:`at_set-colors`.
The shortcut mapping technique has the same syntax as the remote control
command, for details, see :ref:`at_set-colors`.
Or you can enable :doc:`remote control <remote-control>` for |kitty| and use
:ref:`at_set-colors`. The shortcut mapping technique has the same syntax as the
remote control command, for details, see :ref:`at_set-colors`.
To change colors when SSHing into a remote host, use the :opt:`color_scheme
<kitten-ssh.color_scheme>` setting for the :doc:`ssh kitten <kittens/ssh>`.
Additionally, You can use the
`OSC terminal escape codes <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands>`_
`OSC terminal escape codes <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands>`__
to set colors. Examples of using OSC escape codes to set colors::
Change the default foreground color:
@@ -154,7 +156,7 @@ to set colors. Examples of using OSC escape codes to set colors::
printf '\x1b]4;n;green\x1b\\'
You can use various syntaxes/names for color specifications in the above
examples. See `XParseColor <https://linux.die.net/man/3/xparsecolor>`_
examples. See `XParseColor <https://linux.die.net/man/3/xparsecolor>`__
for full details.
If a ``?`` is given rather than a color specification, kitty will respond
@@ -167,14 +169,15 @@ How do I specify command line options for kitty on macOS?
Apple does not want you to use command line options with GUI applications. To
workaround that limitation, |kitty| will read command line options from the file
:file:`<kitty config dir>/macos-launch-services-cmdline` when it is launched
from the GUI, i.e. by clicking the |kitty| application icon or using ``open -a kitty``.
Note that this file is *only read* when running via the GUI.
from the GUI, i.e. by clicking the |kitty| application icon or using
``open -a kitty``. Note that this file is *only read* when running via the GUI.
You can, of course, also run |kitty| from a terminal with command line options, using:
:file:`/Applications/kitty.app/Contents/MacOS/kitty`.
You can, of course, also run |kitty| from a terminal with command line options,
using: :file:`/Applications/kitty.app/Contents/MacOS/kitty`.
And within |kitty| itself, you can always run |kitty| using just ``kitty`` as it
cleverly adds itself to the :envvar:`PATH`.
And within |kitty| itself, you can always run |kitty| using just `kitty` as it
cleverly adds itself to the ``PATH``.
I catted a binary file and now kitty is hung?
-----------------------------------------------
@@ -182,10 +185,10 @@ I catted a binary file and now kitty is hung?
**Never** output unknown binary data directly into a terminal.
Terminals have a single channel for both data and control. Certain bytes
are control codes. Some of these control codes are of arbitrary length, so
if the binary data you output into the terminal happens to contain the starting
sequence for one of these control codes, the terminal will hang waiting for
the closing sequence. Press :kbd:`ctrl+shift+delete` to reset the terminal.
are control codes. Some of these control codes are of arbitrary length, so if
the binary data you output into the terminal happens to contain the starting
sequence for one of these control codes, the terminal will hang waiting for the
closing sequence. Press :sc:`reset_terminal` to reset the terminal.
If you do want to cat unknown data, use ``cat -v``.
@@ -193,30 +196,34 @@ If you do want to cat unknown data, use ``cat -v``.
kitty is not able to use my favorite font?
---------------------------------------------
|kitty| achieves its stellar performance by caching alpha masks of each
rendered character on the GPU, and rendering them all in parallel. This means
it is a strictly character cell based display. As such it can use only
monospace fonts, since every cell in the grid has to be the same size.
Furthermore, it needs fonts to be freely resizable, so it does not support
bitmapped fonts.
|kitty| achieves its stellar performance by caching alpha masks of each rendered
character on the GPU, and rendering them all in parallel. This means it is a
strictly character cell based display. As such it can use only monospace fonts,
since every cell in the grid has to be the same size. Furthermore, it needs
fonts to be freely resizable, so it does not support bitmapped fonts.
.. note::
If you are trying to use a font patched with NERD font symbols, dont do that
as patching destroys fonts. There is no need, simply install the standalone
NERD font (the file :file:`NerdFontsSymbolsOnly.zip` from the `NERD font
releases page <https://github.com/ryanoasis/nerd-fonts/releases>`__). kitty
should pick up symbols from it automatically, and you can tell it to do so
explicitly in case it doesnt with the :opt:`symbol_map` directive::
If you are trying to use a font patched with `Nerd Fonts
<https://nerdfonts.com/>`__ symbols, don't do that as patching destroys
fonts. There is no need, simply install the standalone ``Symbols Nerd Font``
(the file :file:`NerdFontsSymbolsOnly.zip` from the `Nerd Fonts releases page
<https://github.com/ryanoasis/nerd-fonts/releases>`__). kitty should pick up
symbols from it automatically, and you can tell it to do so explicitly in
case it doesn't with the :opt:`symbol_map` directive::
symbol_map U+23FB-U+23FE,U+2665,U+26A1,U+2B58,U+E000-U+E00A,U+E0A0-U+E0A3,U+E0B0-U+E0C8,U+E0CA,U+E0CC-U+E0D2,U+E0D4,U+E200-U+E2A9,U+E300-U+E3E3,U+E5FA-U+E62F,U+E700-U+E7C5,U+F000-U+F2E0,U+F300-U+F31C,U+F400-U+F4A9,U+F500-U+F8FF Symbols Nerd Font
Those Unicode symbols beyond the ``E000-F8FF`` Unicode private use area are
not included.
If your font is not listed in ``kitty +list-fonts`` it means that it is not
monospace or is a bitmapped font. On Linux you can list all monospace fonts with::
monospace or is a bitmapped font. On Linux you can list all monospace fonts
with::
fc-list : family spacing outline scalable | grep -e spacing=100 -e spacing=90 | grep -e outline=True | grep -e scalable=True
Note that the spacing property is calculated by fontconfig based on actual
glyph widths in the font. If for some reason fontconfig concludes your favorite
Note that the spacing property is calculated by fontconfig based on actual glyph
widths in the font. If for some reason fontconfig concludes your favorite
monospace font does not have ``spacing=100`` you can override it by using the
following :file:`~/.config/fontconfig/fonts.conf`::
@@ -278,7 +285,7 @@ homepage:
On macOS you can change the icon by following the steps:
#. Find :file:`kitty.app` in the Applications folder, select it and press :kbd:`⌘+i`
#. Find :file:`kitty.app` in the Applications folder, select it and press :kbd:`⌘+I`
#. Drag :file:`kitty.icns` onto the application icon in the kitty info pane
#. Delete the icon cache and restart Dock::
@@ -301,7 +308,7 @@ the :sc:`send_text <send_text>` you can use the ``show_key`` kitten. Run::
Then press the key you want to emulate. Note that this kitten will only show
keys that actually reach the terminal program, in particular, keys mapped to
actions in kitty will not be shown. To check those first map them to
:code:`no_op`.
:ac:`no_op`.
How do I open a new window or tab with the same working directory as the current window?
--------------------------------------------------------------------------------------------
@@ -328,8 +335,8 @@ variables which kitty will now inherit.
You need to make sure that the environment variables you define in your shell's
rc files are either also defined system wide or via the :opt:`env` directive in
:file:`kitty.conf`. Common environment variables that cause issues are those
related to localization, such as ``LANG, LC_*`` and loading of configuration
files such as ``XDG_*, KITTY_CONFIG_DIRECTORY``.
related to localization, such as :envvar:`LANG`, ``LC_*`` and loading of
configuration files such as ``XDG_*``, :envvar:`KITTY_CONFIG_DIRECTORY`.
To see the environment variables that kitty sees, you can add the following
mapping to :file:`kitty.conf`::
@@ -346,40 +353,42 @@ sorts of places where they may or may not work.
I am using tmux and have a problem
--------------------------------------
First, terminal multiplexers are :iss:`a bad idea <391#issuecomment-638320745>`, do
not use them, if at all possible. kitty contains features that do all of what
First, terminal multiplexers are :iss:`a bad idea <391#issuecomment-638320745>`,
do not use them, if at all possible. kitty contains features that do all of what
tmux does, but better, with the exception of remote persistence (:iss:`391`).
If you still want to use tmux, read on.
Image display will not work, see `tmux issue
<https://github.com/tmux/tmux/issues/1391>`_.
<https://github.com/tmux/tmux/issues/1391>`__.
Using ancient versions of tmux such as 1.8 will
cause gibberish on screen when pressing keys (:iss:`3541`).
Using ancient versions of tmux such as 1.8 will cause gibberish on screen when
pressing keys (:iss:`3541`).
If you are using tmux with multiple terminals or you start it under one
terminal and then switch to another and these terminals have different TERM
variables, tmux will break. You will need to restart it as tmux does not
support multiple terminfo definitions.
If you are using tmux with multiple terminals or you start it under one terminal
and then switch to another and these terminals have different :envvar:`TERM`
variables, tmux will break. You will need to restart it as tmux does not support
multiple terminfo definitions.
If you use any of the advanced features that kitty has innovated, such as
styled underlines, desktop notifications, extended keyboard support, etc.
they may or may not work, depending on the whims of tmux's maintainer, your
version of tmux, etc.
:doc:`styled underlines </underlines>`, :doc:`desktop notifications
</desktop-notifications>`, :doc:`extended keyboard support
</keyboard-protocol>`, etc. they may or may not work, depending on the whims of
tmux's maintainer, your version of tmux, etc.
I opened and closed a lot of windows/tabs and top shows kitty's memory usage is very high?
-------------------------------------------------------------------------------------------
``top`` is not a good way to measure process memory usage. That is because on
modern systems, when allocating memory to a process, the C library functions
will typically allocate memory in large blocks, and give the process chunks of
these blocks. When the process frees a chunk, the C library will not
:program:`top` is not a good way to measure process memory usage. That is
because on modern systems, when allocating memory to a process, the C library
functions will typically allocate memory in large blocks, and give the process
chunks of these blocks. When the process frees a chunk, the C library will not
necessarily release the underlying block back to the OS. So even though the
application has released the memory, ``top`` will still claim the process is
using it.
application has released the memory, :program:`top` will still claim the process
is using it.
To check for memory leaks, instead use a tool like ``valgrind``. Run::
To check for memory leaks, instead use a tool like `Valgrind
<https://valgrind.org/>`__. Run::
PYTHONMALLOC=malloc valgrind --tool=massif kitty
@@ -392,18 +401,19 @@ that window, maybe run yes or find again. Then quit kitty and run::
You will see the allocations graph goes up when you opened the windows, then
goes back down when you closed them, indicating there were no memory leaks.
For those interested, you can get a similar profile out of ``valgrind`` as you get
with ``top`` by adding ``--pages-as-heap=yes`` then you will see that memory
allocated in malloc is not freed in free. This can be further refined if you
use `glibc`` as your C library by setting the environment variable
``MALLOC_MMAP_THRESHOLD_=64``. This will cause free to actually free memory
allocated in sizes of more than 64 bytes. With this set, memory usage will
climb high, then fall when closing windows, but not fall all the way back. The
remaining used memory can be investigated using valgrind again, and it will
For those interested, you can get a similar profile out of :program:`valgrind`
as you get with :program:`top` by adding ``--pages-as-heap=yes`` then you will
see that memory allocated in malloc is not freed in free. This can be further
refined if you use ``glibc`` as your C library by setting the environment
variable ``MALLOC_MMAP_THRESHOLD_=64``. This will cause free to actually free
memory allocated in sizes of more than 64 bytes. With this set, memory usage
will climb high, then fall when closing windows, but not fall all the way back.
The remaining used memory can be investigated using valgrind again, and it will
come from arenas in the GPU drivers and the per thread arenas glibc's malloc
maintains. These too allocate memory in large blocks and dont release it back
maintains. These too allocate memory in large blocks and don't release it back
to the OS immediately.
Why does kitty sometimes start slowly on my Linux system?
-------------------------------------------------------------------------------------------
@@ -427,4 +437,4 @@ The correct command will depend on your situation and hardware.
:file:`libEGL_mesa.so` and ignore :file:`libEGL_nvidia.so` also available on the
system, which will wake the NVIDIA card during device enumeration.
``MESA_LOADER_DRIVER_OVERRIDE`` also assures that Mesa won't offer any NVIDIA
card during enumeration, and will instead just use `/lib/dri/radeonsi_dri.so`.
card during enumeration, and will instead just use :file:`radeonsi_dri.so`.

10
docs/glossary.rst
View File

@@ -84,6 +84,12 @@ Variables that influence kitty behavior
is possible for the autodiscovery to fail; the default Wayland XKB mappings
are used in this case. See :pull:`3943` for details.
.. envvar:: SSH_ASKPASS
Specify the program for SSH to ask for passwords. When this is set, :doc:`ssh
kitten </kittens/ssh>` will use this environment variable by default. See
:opt:`askpass <kitten-ssh.askpass>` for details.
.. envvar:: KITTY_CLONE_SOURCE_CODE
Set this to some shell code that will be executed in the cloned window with
@@ -103,6 +109,10 @@ Variables that kitty sets when running child programs
This is only set on macOS. If the country and language from the macOS user
settings form an invalid locale, it will be set to :code:`en_US.UTF-8`.
.. envvar:: PATH
kitty prepends itself to the PATH of its own environment to ensure the
functions calling :program:`kitty` will work properly.
.. envvar:: KITTY_WINDOW_ID

56
docs/kittens/ssh.rst
View File

@@ -15,28 +15,27 @@ Truly convenient SSH
Automatic shell integration, file transfer and reuse of connections
The ssh kitten allows you to login easily to remote hosts, and automatically
setup the environment there to be as comfortable as your local shell. You
can specify environment variables to set on the remote host and
files to copy there, making your remote experience just like your
local shell. Additionally, it automatically sets up :ref:`shell_integration` on
the remote host and copies the kitty terminfo database there.
setup the environment there to be as comfortable as your local shell. You can
specify environment variables to set on the remote host and files to copy there,
making your remote experience just like your local shell. Additionally, it
automatically sets up :ref:`shell_integration` on the remote host and copies the
kitty terminfo database there.
The ssh kitten is a thin wrapper around the traditional `ssh <https://man.openbsd.org/ssh>`__
command line program and supports all the same options and arguments and configuration.
In interactive usage scenarios it is a drop in replacement for ``ssh``. To try it
out, simply run:
In interactive usage scenarios it is a drop in replacement for :program:`ssh`.
To try it out, simply run:
.. code-block:: sh
kitty +kitten ssh some-hostname-to-connect-to
You should end up at a shell prompt on the remote host, with shell
integration enabled. If you like it you can add an alias to it in your shell's
rc files:
You should end up at a shell prompt on the remote host, with shell integration
enabled. If you like it you can add an alias to it in your shell's rc files:
.. code-block:: sh
alias s=kitty +kitten ssh
alias s="kitty +kitten ssh"
So now you can just type ``s hostname`` to connect.
@@ -44,13 +43,12 @@ If you define a mapping in :file:`kitty.conf` such as::
map f1 new_window_with_cwd
Then, pressing :kbd:`F1` will open a new window automatically logged
into the same host using the ssh kitten, at the same directory.
Then, pressing :kbd:`F1` will open a new window automatically logged into the
same host using the ssh kitten, at the same directory.
The ssh kitten can be configured using the :file:`~/.config/kitty/ssh.conf`
file where you can specify environment variables to set on the remote host
and files to copy from the local to the remote host. Let's see a
quick example:
The ssh kitten can be configured using the :file:`~/.config/kitty/ssh.conf` file
where you can specify environment variables to set on the remote host and files
to copy from the local to the remote host. Let's see a quick example:
.. code-block:: conf
@@ -80,8 +78,9 @@ Additionally, you can pass config options on the command line:
The :code:`--kitten` argument can be specified multiple times, with directives
from :file:`ssh.conf`. These are merged with :file:`ssh.conf` as if they were
appended to the end of that file. They apply only to the host being SSHed to
by this invocation, so any :opt:`hostname <kitten-ssh.hostname>` directives are ignored.
appended to the end of that file. They apply only to the host being SSHed to by
this invocation, so any :opt:`hostname <kitten-ssh.hostname>` directives are
ignored.
.. warning::
@@ -98,8 +97,8 @@ A real world example
Suppose you often SSH into a production server, and you would like to setup
your shell and editor there using your custom settings. However, other people
could SSH in as well and you don't want to clobber their settings. Here is how
this could be achieved using the ssh kitten with zsh and vim as the shell and
editor, respectively:
this could be achieved using the ssh kitten with :program:`zsh` and
:program:`vim` as the shell and editor, respectively:
.. code-block:: conf
@@ -125,23 +124,24 @@ 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
integration <kitten-ssh.shell_integration>` enabled. The data is requested by
the kitten over the TTY with a random one time password. kitty reads the request
and if the password matches a password pre-stored in shared memory on the
localhost by the kitten, the transmission is allowed. If your OpenSSH version is
>= 8.4 then the data is transmitted instantly without any roundtrip delay.
localhost by the kitten, the transmission is allowed. If your local
`OpenSSH <https://www.openssh.com/>`__ version is >= 8.4 then the data is
transmitted instantly without any roundtrip delay.
.. note::
When connecting to BSD hosts, it is possible the bootstrap script will
fail or run slowly, because the default shells are crippled in various ways.
When connecting to BSD hosts, it is possible the bootstrap script will fail
or run slowly, because the default shells are crippled in various ways.
Your best bet is to install Python on the remote, make sure the login shell
is something POSIX sh compliant, and use :code:`python` as the :opt:`interpreter
<kitten-ssh.interpreter>` in :file:`ssh.conf`.
is something POSIX sh compliant, and use :code:`python` as the
:opt:`interpreter <kitten-ssh.interpreter>` in :file:`ssh.conf`.
.. include:: /generated/conf-kitten-ssh.rst

121
kittens/ssh/options/definition.py
View File

@@ -24,26 +24,26 @@ opt = definition.add_option
agr('bootstrap', 'Host bootstrap configuration') # {{{
opt('hostname', '*', option_type='hostname', long_text='''
The hostname that the following options apply to. A glob pattern to match multiple
hosts can be used. Multiple hostnames can also be specified separated by spaces.
The hostname can include an optional username in the form :code:`user@host`.
When not specified options apply to all hosts, until the
first hostname specification is found. Note that matching of hostname is done against
the name you specify on the command line to connect to the remote host.
If you wish to include the same basic configuration for many
different hosts, you can do so with the :ref:`include <include>` directive.
The hostname that the following options apply to. A glob pattern to match
multiple hosts can be used. Multiple hostnames can also be specified, separated
by spaces. The hostname can include an optional username in the form
:code:`user@host`. When not specified options apply to all hosts, until the
first hostname specification is found. Note that matching of hostname is done
against the name you specify on the command line to connect to the remote host.
If you wish to include the same basic configuration for many different hosts,
you can do so with the :ref:`include <include>` directive.
''')
opt('interpreter', 'sh', long_text='''
The interpreter to use on the remote host. Must be either a POSIX complaint shell
or a python executable. If the default sh is not available or broken, using
an alternate interpreter can be useful.
The interpreter to use on the remote host. Must be either a POSIX complaint
shell or a :program:`python` executable. If the default :program:`sh` is not
available or broken, using an alternate interpreter can be useful.
''')
opt('remote_dir', '.local/share/kitty-ssh-kitten', option_type='relative_dir', long_text='''
The location on the remote host where the files needed for this kitten
are installed. The location is relative to the HOME directory. Absolute paths or paths
that resolve to a location outside the HOME are not allowed.
The location on the remote host where the files needed for this kitten are
installed. The location is relative to the HOME directory. Absolute paths or
paths that resolve to a location outside the HOME are not allowed.
''')
opt('+copy', '', option_type='copy', add_to_default=False, long_text=f'''
@@ -51,8 +51,7 @@ opt('+copy', '', option_type='copy', add_to_default=False, long_text=f'''
copy .vimrc .zshrc .config/some-dir
If a file should be copied to some other destination on the remote host,
use :code:`--dest`::
Use :code:`--dest` to copy a file to some other destination on the remote host::
copy --dest some-other-name some-file
@@ -79,51 +78,54 @@ integration on a per-host basis.
''')
opt('login_shell', '', long_text='''
The login shell to execute on the remote host. By default, the remote user account's
login shell is used.
The login shell to execute on the remote host. By default, the remote user
account's login shell is used.
''')
opt('+env', '', option_type='env', add_to_default=False, long_text='''
Specify environment variables to set on the remote host. Note that
environment variables can refer to each other, so if you use::
env MYVAR1=a
env MYVAR2=$MYVAR1/$HOME/b
The value of MYVAR2 will be :code:`a/<path to home directory>/b`. Using
:code:`VAR=` will set it to the empty string and using just :code:`VAR`
will delete the variable from the child process' environment. The definitions
are processed alphabetically. The special value :code:`_kitty_copy_env_var_`
Specify the environment variables to be set on the remote host. Using the
name with an equal sign (e.g. :code:`env VAR=`) will set it to the empty string.
Specifying only the name (e.g. :code:`env VAR`) will remove the variable from
the remote shell environment. The special value :code:`_kitty_copy_env_var_`
will cause the value of the variable to be copied from the local environment.
The definitions are processed alphabetically. Note that environment variables
are expanded recursively, for example::
env VAR1=a
env VAR2=${HOME}/${VAR1}/b
The value of :code:`VAR2` will be :code:`<path to home directory>/a/b`.
''')
opt('cwd', '', long_text='''
The working directory on the remote host to change to. Env vars in this
value are expanded. The default is empty so no changing is done, which
usually means the home directory is used.
The working directory on the remote host to change to. Environment variables in
this value are expanded. The default is empty so no changing is done, which
usually means the HOME directory is used.
''')
opt('color_scheme', '', long_text='''
Specify a color scheme to use when connecting to the remote host. If the
color_scheme ends with :code:`.conf` it is assumed to be the name of a config
file to load from the kitty config directory, otherwise it is assumed to be the
name of a color theme to load via the themes kitten. Note that only colors
applying to the text/background are changed, other config settings in the .conf
files/themes are ignored.
Specify a color scheme to use when connecting to the remote host. If this option
ends with :code:`.conf`, it is assumed to be the name of a config file to load
from the kitty config directory, otherwise it is assumed to be the name of a
color theme to load via the :doc:`themes kitten </kittens/themes>`. Note that
only colors applying to the text/background are changed, other config settings
in the .conf files/themes are ignored.
''')
opt('remote_kitty', 'if-needed', choices=('if-needed', 'no', 'yes'), long_text='''
Make kitty available on the remote server. Useful to run kittens such as the
icat kitten to display images or the transfer file kitten to transfer files.
Only works if the remote server has an architecture for which pre-compiled
kitty binaries are available. Note that kitty is not actually copied to the
remote server, instead a small bootstrap script is copied which will download
and run kitty when kitty is first executed on the remote server. A value of
:code:`if-needed` means kitty is installed only if not already present in the
system-wide PATH. A value of :code:`yes` means that kitty is installed even if
already present, and the installed kitty takes precedence. Finally, :code:`no`
means no kitty is installed on the remote machine. The installed kitty
can be updated by running: :code:`kitty +update-kitty` on the remote machine.
Make :program:`kitty` available on the remote host. Useful to run kittens such
as the :doc:`icat kitten </kittens/icat>` to display images or the
:doc:`transfer file kitten </kittens/transfer>` to transfer files. Only works if
the remote host has an architecture for which :link:`pre-compiled kitty binaries
<https://github.com/kovidgoyal/kitty/releases>` are available. Note that kitty
is not actually copied to the remote host, instead a small bootstrap script is
copied which will download and run kitty when kitty is first executed on the
remote host. A value of :code:`if-needed` means kitty is installed only if not
already present in the system-wide PATH. A value of :code:`yes` means that kitty
is installed even if already present, and the installed kitty takes precedence.
Finally, :code:`no` means no kitty is installed on the remote host. The
installed kitty can be updated by running: :code:`kitty +update-kitty` on the
remote host.
''')
egr() # }}}
@@ -131,20 +133,21 @@ agr('ssh', 'SSH configuration') # {{{
opt('share_connections', 'yes', option_type='to_bool', long_text='''
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.
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.
''')
opt('askpass', 'unless-set', choices=('unless-set', 'ssh', 'native'), long_text='''
Control the program SSH uses to ask for passwords or confirmation of host keys
etc. The default is to use kitty's native askpass, unless the SSH_ASKPASS
environment variable is set. Set it to :code:`ssh` to not interfere with the
normal ssh askpass mechanism at all, which typically means that ssh will prompt
at the terminal. Set it to :code:`native` to always use kitty's native,
built-in askpass implementation. Note that not using the kitty askpass implementation
means that SSH might need to use the terminal before the connection is established
so the kitten cannot use the terminal to send data without an extra roundtrip,
adding to initial connection latency.
etc. The default is to use kitty's native :program:`askpass`, unless the
:envvar:`SSH_ASKPASS` environment variable is set. Set this option to
:code:`ssh` to not interfere with the normal ssh askpass mechanism at all, which
typically means that ssh will prompt at the terminal. Set it to :code:`native`
to always use kitty's native, built-in askpass implementation. Note that not
using the kitty askpass implementation means that SSH might need to use the
terminal before the connection is established, so the kitten cannot use the
terminal to send data without an extra roundtrip, adding to initial connection
latency.
''')
egr() # }}}

5
kitty/conf/types.py
View File

@@ -96,6 +96,10 @@ def remove_markup(text: str) -> str:
return re.sub(r':([a-zA-Z0-9]+):`(.+?)`', sub, text, flags=re.DOTALL)
def strip_inline_literal(text: str) -> str:
return re.sub(r'``([^`]+)``', r'`\1`', text, flags=re.DOTALL)
def iter_blocks(lines: Iterable[str]) -> Iterator[Tuple[List[str], int]]:
current_block: List[str] = []
prev_indent = 0
@@ -137,6 +141,7 @@ def wrapped_block(lines: Iterable[str], comment_symbol: str = '#: ') -> Iterator
def render_block(text: str, comment_symbol: str = '#: ') -> str:
text = remove_markup(text)
text = strip_inline_literal(text)
lines = text.splitlines()
return '\n'.join(wrapped_block(lines, comment_symbol))

1
kitty/launch.py
View File

@@ -575,6 +575,7 @@ class CloneCmd:
'CONDA_SHLVL', 'CONDA_PREFIX', 'CONDA_PROMPT_MODIFIER', 'CONDA_EXE', 'CONDA_PYTHON_EXE', '_CE_CONDA', '_CE_M',
# skip SSH environment variables
'SSH_CLIENT', 'SSH_CONNECTION', 'SSH_ORIGINAL_COMMAND', 'SSH_TTY', 'SSH2_TTY',
'SSH_TUNNEL', 'SSH_USER_AUTH', 'SSH_AUTH_SOCK',
} and not k.startswith((
# conda state env vars for multi-level virtual environments
'CONDA_PREFIX_',

67
kitty/options/definition.py
View File

@@ -34,7 +34,7 @@ and even specify special fonts for particular characters.
opt('font_family', 'monospace',
long_text='''
You can specify different fonts for the bold/italic/bold-italic variants.
To get a full list of supported fonts use the :code:`kitty +list-fonts` command.
To get a full list of supported fonts use the ``kitty +list-fonts`` command.
By default they are derived automatically, by the OSes font system. When
:opt:`bold_font` or :opt:`bold_italic_font` is set to :code:`auto` on macOS, the
priority of bold fonts is semi-bold, bold, heavy. Setting them manually is
@@ -114,8 +114,8 @@ opt('+symbol_map', 'U+E0A0-U+E0A3,U+E0C0-U+E0C7 PowerlineSymbols',
long_text='''
Map the specified Unicode codepoints to a particular font. Useful if you need
special rendering for some symbols, such as for Powerline. Avoids the need for
patched fonts. Each Unicode code point is specified in the form :code:`U+<code
point in hexadecimal>`. You can specify multiple code points, separated by
patched fonts. Each Unicode code point is specified in the form ``U+<code
point in hexadecimal>``. You can specify multiple code points, separated by
commas and ranges separated by hyphens. This option can be specified multiple
times. The syntax is::
@@ -134,7 +134,7 @@ aspect ratio. Using this option you can force kitty to restrict the specified
code points to render in the specified number of cells (defaulting to one cell).
This option can be specified multiple times. The syntax is::
narrow_symbols codepoints Optionally the number of cells
narrow_symbols codepoints [optionally the number of cells]
'''
)
@@ -181,7 +181,7 @@ feature in the italic font but not in the regular font.
On Linux, font features are first read from the FontConfig database and then
this option is applied, so they can be configured in a single, central place.
To get the PostScript name for a font, use :code:`kitty +list-fonts --psnames`:
To get the PostScript name for a font, use ``kitty +list-fonts --psnames``:
.. code-block:: sh
@@ -259,8 +259,8 @@ The cursor shape can be one of :code:`block`, :code:`beam`, :code:`underline`.
Note that when reloading the config this will be changed only if the cursor
shape has not been set by the program running in the terminal. This sets the
default cursor shape, applications running in the terminal can override it. In
particular, :ref:`shell_integration` in kitty sets the cursor shape to
:code:`beam` at shell prompts. You can avoid this by setting
particular, :ref:`shell integration <shell_integration>` in kitty sets the
cursor shape to :code:`beam` at shell prompts. You can avoid this by setting
:opt:`shell_integration` to :code:`no-cursor`.
'''
)
@@ -279,8 +279,8 @@ opt('cursor_blink_interval', '-1',
option_type='float', ctype='time',
long_text='''
The interval to blink the cursor (in seconds). Set to zero to disable blinking.
Negative values mean use system default. Note that numbers smaller
than :opt:`repaint_delay` will be limited to :opt:`repaint_delay`.
Negative values mean use system default. Note that the minimum interval will be
limited to :opt:`repaint_delay`.
'''
)
@@ -459,11 +459,11 @@ opt(
'paste_actions', 'quote-urls-at-prompt', option_type='paste_actions',
long_text='''
A comma separated list of actions to take when pasting text into the terminal.
Possibilities are:
The supported paste actions are:
:code:`quote-urls-at-prompt`:
If the text being pasted is a URL and the cursor is at a shell prompt,
automatically quote the URL (needs :ref:`shell_integration`).
automatically quote the URL (needs :opt:`shell_integration`).
:code:`confirm`:
Confirm the paste if bracketed paste mode is not active or there is more
a large amount of text being pasted.
@@ -479,7 +479,7 @@ opt('strip_trailing_spaces', 'never',
long_text='''
Remove spaces at the end of lines when copying to clipboard. A value of
:code:`smart` will do it when using normal selections, but not rectangle
selections. :code:`always` will always do it.
selections. A value of :code:`always` will always do it.
'''
)
@@ -586,7 +586,8 @@ mma('Click the link under the mouse or move the cursor',
First check for a selection and if one exists do nothing. Then check for a link
under the mouse cursor and if one exists, click it. Finally check if the click
happened at the current shell prompt and if so, move the cursor to the click
location. Note that this requires :doc:`shell-integration` to work.
location. Note that this requires :ref:`shell integration <shell_integration>`
to work.
'''
)
@@ -684,7 +685,7 @@ mma('Extend the current selection even when grabbed',
mma('Show clicked command output in pager',
'show_clicked_cmd_output_ungrabbed ctrl+shift+right press ungrabbed mouse_show_command_output',
long_text='Requires :ref:`shell_integration` to work.'
long_text='Requires :ref:`shell integration <shell_integration>` to work.'
)
egr() # }}}
egr() # }}}
@@ -952,7 +953,7 @@ Path to a logo image. Must be in PNG format. Relative paths are interpreted
relative to the kitty config directory. The logo is displayed in a corner of
every kitty window. The position is controlled by :opt:`window_logo_position`.
Individual windows can be configured to have different logos either using the
:ac:`launch` action or the :doc:`remote-control` facility.
:ac:`launch` action or the :doc:`remote control <remote-control>` facility.
'''
)
@@ -1161,9 +1162,9 @@ formatting machinery, so you can use, for instance,
:code:`{layout_name[:2].upper()}` to show only the first two letters of the
layout name, upper-cased. If you want to style the text, you can use styling
directives, for example:
:code:`{fmt.fg.red}red{fmt.fg.tab}normal{fmt.bg._00FF00}greenbg{fmt.bg.tab}`.
``{fmt.fg.red}red{fmt.fg.tab}normal{fmt.bg._00FF00}greenbg{fmt.bg.tab}``.
Similarly, for bold and italic:
:code:`{fmt.bold}bold{fmt.nobold}normal{fmt.italic}italic{fmt.noitalic}`.
``{fmt.bold}bold{fmt.nobold}normal{fmt.italic}italic{fmt.noitalic}``.
Note that for backward compatibility, if :code:`{bell_symbol}` or
:code:`{activity_symbol}` are not present in the template, they are prepended to
it.
@@ -2646,8 +2647,8 @@ reads its startup rc files.
opt('editor', '.',
long_text='''
The terminal based text editor (such as :program:`vim` or :program:`nano`) to use
when editing the kitty config file or similar tasks.
The terminal based text editor (such as :program:`vim` or :program:`nano`) to
use when editing the kitty config file or similar tasks.
The default value of :code:`.` means to use the environment variables
:envvar:`VISUAL` and :envvar:`EDITOR` in that order. If these variables aren't
@@ -2835,7 +2836,7 @@ pager, etc. on supported shells. Set to :code:`disabled` to turn off shell
integration, completely. It is also possible to disable individual features, set
to a space separated list of these values: :code:`no-rc`, :code:`no-cursor`,
:code:`no-title`, :code:`no-cwd`, :code:`no-prompt-mark`, :code:`no-complete`.
See :ref:`shell_integration` for details.
See :ref:`Shell integration <shell_integration>` for details.
'''
)
@@ -2858,17 +2859,17 @@ Control what shell code is sourced when running :command:`clone-in-kitty`
in the newly cloned window. The supported strategies are:
:code:`venv`
Source the file :file:`$VIRTUAL_ENV/bin/activate` (this is used by the
Python stdlib venv module and allows cloning venvs automatically)
Source the file :file:`$VIRTUAL_ENV/bin/activate`. This is used by the
Python stdlib venv module and allows cloning venvs automatically.
:code:`conda`
Run :code:`conda activate $CONDA_DEFAULT_ENV` this supports the virtual envs
created by conda
Run :code:`conda activate $CONDA_DEFAULT_ENV`. This supports the virtual
environments created by :program:`conda`.
:code:`env_var`
Source the contents of the environment variable
:code:`KITTY_CLONE_SOURCE_CODE`
Execute the contents of the environment variable
:envvar:`KITTY_CLONE_SOURCE_CODE` with :code:`eval`.
:code:`path`
Source the file pointed to by the environment variable
:code:`KITTY_CLONE_SOURCE_PATH`
:envvar:`KITTY_CLONE_SOURCE_PATH`.
This option must be a comma separated list of the above values. This only
source the first valid one in the above order.
@@ -3262,8 +3263,8 @@ map('Scroll to previous shell prompt',
'scroll_to_previous_prompt kitty_mod+z scroll_to_prompt -1',
long_text='''
Use a parameter of :code:`0` for :ac:`scroll_to_prompt` to scroll to the last
jumped to or the last clicked position. Requires :ref:`shell_integration` to
work.
jumped to or the last clicked position. Requires :ref:`shell integration
<shell_integration>` to work.
'''
)
@@ -3306,7 +3307,7 @@ You can pipe the output of the last command run in the shell using the
To get the output of the first command on the screen, use :code:`@first_cmd_output_on_screen`.
To get the output of the last jumped to command, use :code:`@last_visited_cmd_output`.
Requires :ref:`shell_integration` to work.
Requires :ref:`shell integration <shell_integration>` to work.
'''
)
egr() # }}}
@@ -3686,7 +3687,7 @@ map('Insert selected line',
'insert_selected_line kitty_mod+p>l kitten hints --type line --program -',
long_text='''
Select a line of text and insert it into the terminal. Useful for the output of
things like: :code:`ls -1`.
things like: ``ls -1``.
'''
)
@@ -3715,7 +3716,7 @@ map('Open the selected hyperlink',
'open_selected_hyperlink kitty_mod+p>y kitten hints --type hyperlink',
long_text='''
Select a :term:`hyperlink <hyperlinks>` (i.e. a URL that has been marked as such
by the terminal program, for example, by :code:`ls --hyperlink=auto`).
by the terminal program, for example, by ``ls --hyperlink=auto``).
'''
)
egr('''
@@ -3877,7 +3878,7 @@ This will send "Special text" when you press the :kbd:`Ctrl+Alt+A` key
combination. The text to be sent is a python string literal so you can use
escapes like :code:`\\x1b` to send control codes or :code:`\\u21fb` to send
Unicode characters (or you can just input the Unicode characters directly as
UTF-8 text). You can use :code:`kitty +kitten show_key` to get the key escape
UTF-8 text). You can use ``kitty +kitten show_key`` to get the key escape
codes you want to emulate.
The first argument to :code:`send_text` is the keyboard modes in which to