From 7282f1f6841d249477b2de2a2ae68db291dd5dad Mon Sep 17 00:00:00 2001 From: pagedown Date: Mon, 25 Apr 2022 15:36:37 +0800 Subject: [PATCH 1/4] Docs: Improve ssh kitten documentation Add more text roles. Put the env example at the end. The alias syntax of fish and bash requires quotation marks. Document `SSH_ASKPASS` in the glossary. --- docs/glossary.rst | 6 ++ docs/kittens/ssh.rst | 56 +++++++------- kittens/ssh/options/definition.py | 121 +++++++++++++++--------------- 3 files changed, 96 insertions(+), 87 deletions(-) diff --git a/docs/glossary.rst b/docs/glossary.rst index 33cb2c7cd..a77d6fac8 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -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 ` will use this environment variable by default. See + :opt:`askpass ` for details. + .. envvar:: KITTY_CLONE_SOURCE_CODE Set this to some shell code that will be executed in the cloned window with diff --git a/docs/kittens/ssh.rst b/docs/kittens/ssh.rst index 453f9c4d7..254ef0de4 100644 --- a/docs/kittens/ssh.rst +++ b/docs/kittens/ssh.rst @@ -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 `__ 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 ` 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 ` 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 ` Python) bootstrap script on the remote host using an :opt:`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 ` and sets the :opt:`environment variables ` before finally launching the :opt:`login shell ` with :opt:`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 `__ 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 - ` in :file:`ssh.conf`. + is something POSIX sh compliant, and use :code:`python` as the + :opt:`interpreter ` in :file:`ssh.conf`. .. include:: /generated/conf-kitten-ssh.rst diff --git a/kittens/ssh/options/definition.py b/kittens/ssh/options/definition.py index 7abdabb03..fd093a93a 100644 --- a/kittens/ssh/options/definition.py +++ b/kittens/ssh/options/definition.py @@ -24,26 +24,26 @@ 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 ` 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 ` 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 @@ 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 @@ ''') 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//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:`/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 `. 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 ` to display images or the +:doc:`transfer file kitten ` to transfer files. Only works if +the remote host has an architecture for which :link:`pre-compiled kitty binaries +` 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 @@ 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() # }}} From 7bace19aed6ea3108173b50d8387510e2f88480d Mon Sep 17 00:00:00 2001 From: pagedown Date: Mon, 25 Apr 2022 15:36:43 +0800 Subject: [PATCH 2/4] clone-in-kitty: Skip more SSH env vars to use the correct values --- kitty/launch.py | 1 + 1 file changed, 1 insertion(+) diff --git a/kitty/launch.py b/kitty/launch.py index 5bf50f37f..2beaf77a6 100644 --- a/kitty/launch.py +++ b/kitty/launch.py @@ -575,6 +575,7 @@ def parse_message(self, msg: str) -> None: '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_', From 97a568a40530c9dd2541472fa52f094170e5a453 Mon Sep 17 00:00:00 2001 From: pagedown Date: Mon, 25 Apr 2022 15:36:51 +0800 Subject: [PATCH 3/4] Docs: Improve the FAQ Add more text roles and links. Document `PATH` in the glossary. --- docs/faq.rst | 190 ++++++++++++++++++++++++---------------------- docs/glossary.rst | 4 + 2 files changed, 104 insertions(+), 90 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index f0e64f253..f8d94203f 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -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 ` for why |kitty| does not support background color erase. +See :doc:`here ` 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 ` 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 ` 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 ` 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 ` setting for the :doc:`ssh kitten `. Additionally, You can use the -`OSC terminal escape codes `_ +`OSC terminal escape codes `__ 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 `_ +examples. See `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:`/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 `__). 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 + `__ 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 + `__). 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 ` 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 -`_. +`__. -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 `, :doc:`desktop notifications +`, :doc:`extended keyboard support +`, 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 +`__. 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`. diff --git a/docs/glossary.rst b/docs/glossary.rst index a77d6fac8..4c978a99e 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -109,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 From c4710bf9cb7087fcd1bc549103e6904f53d2158a Mon Sep 17 00:00:00 2001 From: pagedown Date: Mon, 25 Apr 2022 15:36:57 +0800 Subject: [PATCH 4/4] Docs: Add text to the ref text role and minor tweaks The text will be used when generating the commented configuration file. Use inline literal to quote codes with spaces, as the `code` text role will be removed when the commented configuration is generated, making it indistinguishable from normal text. --- kitty/conf/types.py | 5 +++ kitty/options/definition.py | 67 +++++++++++++++++++------------------ 2 files changed, 39 insertions(+), 33 deletions(-) diff --git a/kitty/conf/types.py b/kitty/conf/types.py index 0836709a2..beebe555d 100644 --- a/kitty/conf/types.py +++ b/kitty/conf/types.py @@ -96,6 +96,10 @@ def sub(m: 'Match[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)) diff --git a/kitty/options/definition.py b/kitty/options/definition.py index b1025abe3..6fb1dd2ae 100644 --- a/kitty/options/definition.py +++ b/kitty/options/definition.py @@ -34,7 +34,7 @@ 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 @@ 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+`. You can specify multiple code points, separated by +patched fonts. Each Unicode code point is specified in the form ``U+``. 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 @@ 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 @@ 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 @@ 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 ` 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 @@ 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 @@ '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 @@ 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 @@ 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 ` +to work. ''' ) @@ -684,7 +685,7 @@ 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 ` to work.' ) egr() # }}} egr() # }}} @@ -952,7 +953,7 @@ 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 ` facility. ''' ) @@ -1161,9 +1162,9 @@ :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 @@ 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 @@ 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 ` for details. ''' ) @@ -2858,17 +2859,17 @@ 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 @@ '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 +` to work. ''' ) @@ -3306,7 +3307,7 @@ 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 ` to work. ''' ) egr() # }}} @@ -3686,7 +3687,7 @@ '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 @@ 'open_selected_hyperlink kitty_mod+p>y kitten hints --type hyperlink', long_text=''' Select a :term:`hyperlink ` (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 @@ 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