KittyPatch/kitty
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Docs: Improve the documentation for kittens

Browse Source 
Add more text roles and links.
Add an example that broadcasts only to other windows in the current tab.
Initial capitalization of the key names in the kbd text role.
Add Python type hints for custom kittens.
Note about hyperlink support for ls on macOS.
Add description text for show_key.
This commit is contained in:
pagedown 2022-04-27 15:58:20 +08:00
parent 627c79ffbb
commit 510022c3c1
No known key found for this signature in database
GPG Key ID: E921CF18AC8FF6EB
29 changed files with 374 additions and 336 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/conf.rst
View File

@ -19,8 +19,8 @@ You can also display the current configuration by pressing :sc:`debug_config`
|kitty| looks for a config file in the OS config directories (usually |kitty| looks for a config file in the OS config directories (usually
:file:`~/.config/kitty/kitty.conf`) but you can pass a specific path via the :file:`~/.config/kitty/kitty.conf`) but you can pass a specific path via the
:option:`kitty --config` option or use the ``KITTY_CONFIG_DIRECTORY`` :option:`kitty --config` option or use the :envvar:`KITTY_CONFIG_DIRECTORY`
environment variable. See the :option:`kitty --config` option for full details. environment variable. See :option:`kitty --config` for full details.
Comments can be added to the config file as lines starting with the ``#`` Comments can be added to the config file as lines starting with the ``#``
character. This works only if the ``#`` character is the first character character. This works only if the ``#`` character is the first character

5
docs/glossary.rst
View File

@ -37,7 +37,8 @@ Glossary
hyperlinks hyperlinks
Terminals can have hyperlinks, just like the internet. In kitty you can Terminals can have hyperlinks, just like the internet. In kitty you can
:doc:`control exactly what happens <open_actions>` when clicking on a :doc:`control exactly what happens <open_actions>` when clicking on a
hyperlink, based on the type of link and its URL. hyperlink, based on the type of link and its URL. See also `Hyperlinks in terminal
emulators <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`__.
.. _env_vars: .. _env_vars:
@ -109,11 +110,13 @@ Variables that kitty sets when running child programs
This is only set on macOS. If the country and language from the macOS user 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`. settings form an invalid locale, it will be set to :code:`en_US.UTF-8`.
.. envvar:: PATH .. envvar:: PATH
kitty prepends itself to the PATH of its own environment to ensure the kitty prepends itself to the PATH of its own environment to ensure the
functions calling :program:`kitty` will work properly. functions calling :program:`kitty` will work properly.
.. envvar:: KITTY_WINDOW_ID .. envvar:: KITTY_WINDOW_ID
An integer that is the id for the kitty :term:`window` the program is running in. An integer that is the id for the kitty :term:`window` the program is running in.

15
docs/kittens/broadcast.rst
View File

@ -3,18 +3,21 @@ broadcast
*Type text in all kitty windows simultaneously* *Type text in all kitty windows simultaneously*
The ``broadcast`` kitten can be used to type text simultaneously in The ``broadcast`` kitten can be used to type text simultaneously in all
all kitty windows (or a subset as desired). :term:`kitty windows <window>` (or a subset as desired).
To use it, simply create a mapping in :file:`kitty.conf` such as:: To use it, simply create a mapping in :file:`kitty.conf` such as::
map F1 launch --allow-remote-control kitty +kitten broadcast map f1 launch --allow-remote-control kitty +kitten broadcast
Then press the :kbd:`F1` key and whatever you type in the newly created widow Then press the :kbd:`F1` key and whatever you type in the newly created window
will be sent to all kitty windows. will be sent to all kitty windows.
You can use the options described below to control which windows You can use the options described below to control which windows are selected.
are selected.
For example, only broadcast to other windows in the current tab::
map f1 launch --allow-remote-control kitty +kitten broadcast --match state:parent_active
.. program:: kitty +kitten broadcast .. program:: kitty +kitten broadcast

105
docs/kittens/custom.rst
View File

@ -1,21 +1,20 @@
Custom kittens Custom kittens
================= =================
You can easily create your own kittens to extend kitty. They are just You can easily create your own kittens to extend kitty. They are just terminal
terminal programs written in Python. When launching a kitten, kitty will programs written in Python. When launching a kitten, kitty will open an overlay
open an overlay window over the current window and optionally pass the window over the current window and optionally pass the contents of the current
contents of the current window/scrollback to the kitten over its :file:`STDIN`. window/scrollback to the kitten over its :file:`STDIN`. The kitten can then
The kitten can then perform whatever actions it likes, just as a normal perform whatever actions it likes, just as a normal terminal program. After
terminal program. After execution of the kitten is complete, it has access execution of the kitten is complete, it has access to the running kitty instance
to the running kitty instance so it can perform arbitrary actions so it can perform arbitrary actions such as closing windows, pasting text, etc.
such as closing windows, pasting text, etc.
Let's see a simple example of creating a kitten. It will ask the user for some Let's see a simple example of creating a kitten. It will ask the user for some
input and paste it into the terminal window. input and paste it into the terminal window.
Create a file in the kitty config folder, :file:`~/.config/kitty/mykitten.py` Create a file in the kitty config directory, :file:`~/.config/kitty/mykitten.py`
(you might need to adjust the path to wherever the kitty config folder is on (you might need to adjust the path to wherever the :ref:`kitty config directory
your machine). <confloc>` is on your machine).
.. code-block:: python .. code-block:: python
@ -43,11 +42,12 @@ Now in :file:`kitty.conf` add the lines::
map ctrl+k kitten mykitten.py map ctrl+k kitten mykitten.py
Start kitty and press :kbd:`ctrl+k` and you should see the kitten running. Start kitty and press :kbd:`Ctrl+K` and you should see the kitten running.
The best way to develop your own kittens is to modify one of the built in The best way to develop your own kittens is to modify one of the built-in
kittens. Look in the kittens sub-directory of the kitty source code for those. kittens. Look in the `kittens sub-directory
Or see below for a list of :ref:`third-party kittens <external_kittens>`, <https://github.com/kovidgoyal/kitty/tree/master/kittens>`__ of the kitty source
that other kitty users have created. code for those. Or see below for a list of :ref:`third-party kittens
<external_kittens>`, that other kitty users have created.
Passing arguments to kittens Passing arguments to kittens
@ -60,36 +60,40 @@ You can pass arguments to kittens by defining them in the map directive in
These will be available as the ``args`` parameter in the ``main()`` and These will be available as the ``args`` parameter in the ``main()`` and
``handle_result()`` functions. Note also that the current working directory ``handle_result()`` functions. Note also that the current working directory
of the kitten is set to the working directory of whatever program is of the kitten is set to the working directory of whatever program is running in
running in the active kitty window. The special argument ``@selection`` the active kitty window. The special argument ``@selection`` is replaced by the
is replaced by the currently selected text in the active kitty window. currently selected text in the active kitty window.
Passing the contents of the screen to the kitten Passing the contents of the screen to the kitten
--------------------------------------------------- ---------------------------------------------------
If you would like your kitten to have access to the contents of the screen If you would like your kitten to have access to the contents of the screen
and/or the scrollback buffer, you just need to add an annotation to the ``handle_result()`` and/or the scrollback buffer, you just need to add an annotation to the
function, telling kitty what kind of input your kitten would like. For example: ``handle_result()`` function, telling kitty what kind of input your kitten would
like. For example:
.. code-block:: py .. code-block:: py
from typing import List
from kitty.boss import Boss
# in main, STDIN is for the kitten process and will contain # in main, STDIN is for the kitten process and will contain
# the contents of the screen # the contents of the screen
def main(args): def main(args: List[str]) -> str:
return sys.stdin.read() return sys.stdin.read()
# in handle_result, STDIN is for the kitty process itself, rather # in handle_result, STDIN is for the kitty process itself, rather
# than the kitten process and should not be read from. # than the kitten process and should not be read from.
from kittens.tui.handler import result_handler from kittens.tui.handler import result_handler
@result_handler(type_of_input='text') @result_handler(type_of_input='text')
def handle_result(args, stdin_data, target_window_id, boss): def handle_result(args: List[str], stdin_data: str, target_window_id: int, boss: Boss) -> None:
pass pass
This will send the plain text of the active window to the kitten's This will send the plain text of the active window to the kitten's
:file:`STDIN`. There are many other types of input you can ask for, :file:`STDIN`. There are many other types of input you can ask for, described in
described in the table below: the table below:
.. table:: Types of input to kittens .. table:: Types of input to kittens
:align: left :align: left
@ -121,31 +125,35 @@ and ``first_output`` gives the output of the first command currently on screen.
These can also be combined with ``screen`` and ``ansi`` for formatting. These can also be combined with ``screen`` and ``ansi`` for formatting.
.. note:: .. note::
For the types based on the output of a command, For the types based on the output of a command, :ref:`shell_integration` is
:ref:`shell_integration` is required. required.
Using kittens to script kitty, without any terminal UI Using kittens to script kitty, without any terminal UI
----------------------------------------------------------- -----------------------------------------------------------
If you would like your kitten to script kitty, without bothering to write a If you would like your kitten to script kitty, without bothering to write a
terminal program, you can tell the kittens system to run the terminal program, you can tell the kittens system to run the ``handle_result()``
``handle_result()`` function without first running the ``main()`` function. function without first running the ``main()`` function.
For example, here is a kitten that "zooms/unzooms" the current terminal window For example, here is a kitten that "zooms in/zooms out" the current terminal
by switching to the stack layout or back to the previous layout. This is window by switching to the stack layout or back to the previous layout. This is
equivalent to the builtin :ac:`toggle_layout` action. equivalent to the builtin :ac:`toggle_layout` action.
Create a file in the kitty config folder, :file:`~/.config/kitty/zoom_toggle.py` Create a Python file in the :ref:`kitty config directory <confloc>`,
:file:`~/.config/kitty/zoom_toggle.py`
.. code-block:: py .. code-block:: py
def main(args): from typing import List
from kitty.boss import Boss
def main(args: List[str]) -> str:
pass pass
from kittens.tui.handler import result_handler from kittens.tui.handler import result_handler
@result_handler(no_ui=True) @result_handler(no_ui=True)
def handle_result(args, answer, target_window_id, boss): def handle_result(args: List[str], answer: str, target_window_id: int, boss: Boss) -> None:
tab = boss.active_tab tab = boss.active_tab
if tab is not None: if tab is not None:
if tab.current_layout.name == 'stack': if tab.current_layout.name == 'stack':
@ -154,7 +162,7 @@ Create a file in the kitty config folder, :file:`~/.config/kitty/zoom_toggle.py`
tab.goto_layout('stack') tab.goto_layout('stack')
Now in kitty.conf add:: Now in :file:`kitty.conf` add::
map f11 kitten zoom_toggle.py map f11 kitten zoom_toggle.py
@ -165,7 +173,7 @@ layout, by simply adding the line::
boss.toggle_fullscreen() boss.toggle_fullscreen()
To the ``handle_result()`` function, above. to the ``handle_result()`` function, above.
.. _send_mouse_event: .. _send_mouse_event:
@ -173,7 +181,7 @@ To the ``handle_result()`` function, above.
Sending mouse events Sending mouse events
-------------------- --------------------
If the program running in a window is receiving mouse events you can simulate If the program running in a window is receiving mouse events, you can simulate
those using:: those using::
from kitty.fast_data_types import send_mouse_event from kitty.fast_data_types import send_mouse_event
@ -200,15 +208,15 @@ that type, and will return ``True`` if it sent the event, and ``False`` if not.
Debugging kittens Debugging kittens
-------------------- --------------------
The part of the kitten that runs in ``main()`` is just a normal program and The part of the kitten that runs in ``main()`` is just a normal program and the
the output of print statements will be visible in the kitten window. Or output of print statements will be visible in the kitten window. Or alternately,
alternately, you can use:: you can use::
from kittens.tui.loop import debug from kittens.tui.loop import debug
debug('whatever') debug('whatever')
The ``debug()`` function is just like ``print()`` except that the output The ``debug()`` function is just like ``print()`` except that the output will
will appear in the ``STDOUT`` of the kitty process inside which the kitten is appear in the ``STDOUT`` of the kitty process inside which the kitten is
running. running.
The ``handle_result()`` part of the kitten runs inside the kitty process. The ``handle_result()`` part of the kitten runs inside the kitty process.
@ -216,12 +224,13 @@ The output of print statements will go to the ``STDOUT`` of the kitty process.
So if you run kitty from another kitty instance, the output will be visible So if you run kitty from another kitty instance, the output will be visible
in the first kitty instance. in the first kitty instance.
Adding options to kittens Adding options to kittens
---------------------------- ----------------------------
If you would like to use kitty's config framework to make your kittens If you would like to use kitty's config framework to make your kittens
configurable, you will need some boilerplate. In the directory configurable, you will need some boilerplate. Put the following files in the
of your kitten make the following files. directory of your kitten.
:file:`kitten_options_definition.py` :file:`kitten_options_definition.py`
@ -311,8 +320,9 @@ You can parse and read the options in your kitten using the following code:
opts.config_overrides = overrides opts.config_overrides = overrides
return opts return opts
See the code for the builtin diff kitten for examples of creating more options See `the code <https://github.com/kovidgoyal/kitty/tree/master/kittens/diff>`__
and keyboard shortcuts. for the builtin :doc:`diff kitten </kittens/diff>` for examples of creating more
options and keyboard shortcuts.
.. _external_kittens: .. _external_kittens:
@ -320,7 +330,8 @@ Kittens created by kitty users
--------------------------------------------- ---------------------------------------------
`vim-kitty-navigator <https://github.com/knubie/vim-kitty-navigator>`_ `vim-kitty-navigator <https://github.com/knubie/vim-kitty-navigator>`_
Allows you to navigate seamlessly between vim and kitty splits using a consistent set of hotkeys. Allows you to navigate seamlessly between vim and kitty splits using a
consistent set of hotkeys.
`smart-scroll <https://github.com/yurikhan/kitty-smart-scroll>`_ `smart-scroll <https://github.com/yurikhan/kitty-smart-scroll>`_
Makes the kitty scroll bindings work in full screen applications Makes the kitty scroll bindings work in full screen applications

49
docs/kittens/diff.rst
View File

@ -12,8 +12,8 @@ Major Features
* Displays diffs side-by-side in the kitty terminal * Displays diffs side-by-side in the kitty terminal
* Does syntax highlighting of the displayed diffs, asynchronously, for maximum * Does syntax highlighting of the displayed diffs, asynchronously, for
speed maximum speed
* Displays images as well as text diffs, even over SSH * Displays images as well as text diffs, even over SSH
@ -31,11 +31,11 @@ Major Features
Installation Installation
--------------- ---------------
Simply :ref:`install kitty <quickstart>`. You also need Simply :ref:`install kitty <quickstart>`. You also need to have either the `git
to have either the `git <https://git-scm.com/>`_ program or the ``diff`` program <https://git-scm.com/>`__ program or the :program:`diff` program installed.
installed. Additionally, for syntax highlighting to work, Additionally, for syntax highlighting to work, `pygments
`pygments <https://pygments.org/>`_ must be installed (note that pygments is <https://pygments.org/>`__ must be installed (note that pygments is included in
included in the official kitty binary builds). the official kitty binary builds).
Usage Usage
@ -45,9 +45,10 @@ In the kitty terminal, run::
kitty +kitten diff file1 file2 kitty +kitten diff file1 file2
to see the diff between file1 and file2. to see the diff between :file:`file1` and :file:`file2`.
Create an alias in your shell's startup file to shorten the command, for example: Create an alias in your shell's startup file to shorten the command, for
example:
.. code-block:: sh .. code-block:: sh
@ -67,20 +68,20 @@ Keyboard controls
========================= =========================== ========================= ===========================
Action Shortcut Action Shortcut
========================= =========================== ========================= ===========================
Quit :kbd:`q`, :kbd:`ctrl+c`, :kbd:`Esc` Quit :kbd:`Q`, :kbd:`Ctrl+C`, :kbd:`Esc`
Scroll line up :kbd:`k`, :kbd:`Up` Scroll line up :kbd:`K`, :kbd:`Up`
Scroll line down :kbd:`j`, :kbd:`Down` Scroll line down :kbd:`J`, :kbd:`Down`
Scroll page up :kbd:`PgUp` Scroll page up :kbd:`PgUp`
Scroll page down :kbd:`PgDn` Scroll page down :kbd:`PgDn`
Scroll to top :kbd:`Home` Scroll to top :kbd:`Home`
Scroll to bottom :kbd:`End` Scroll to bottom :kbd:`End`
Scroll to next page :kbd:`Space`, :kbd:`PgDn` Scroll to next page :kbd:`Space`, :kbd:`PgDn`
Scroll to previous page :kbd:`PgUp` Scroll to previous page :kbd:`PgUp`
Scroll to next change :kbd:`n` Scroll to next change :kbd:`N`
Scroll to previous change :kbd:`p` Scroll to previous change :kbd:`P`
Increase lines of context :kbd:`+` Increase lines of context :kbd:`+`
Decrease lines of context :kbd:`-` Decrease lines of context :kbd:`-`
All lines of context :kbd:`a` All lines of context :kbd:`A`
Restore default context :kbd:`=` Restore default context :kbd:`=`
Search forwards :kbd:`/` Search forwards :kbd:`/`
Search backwards :kbd:`?` Search backwards :kbd:`?`
@ -93,7 +94,7 @@ Scroll to previous match :kbd:`<`, :kbd:`,`
Integrating with git Integrating with git
----------------------- -----------------------
Add the following to `~/.gitconfig`: Add the following to :file:`~/.gitconfig`:
.. code-block:: ini .. code-block:: ini
@ -119,24 +120,23 @@ Why does this work only in kitty?
---------------------------------------- ----------------------------------------
The diff kitten makes use of various features that are :doc:`kitty only The diff kitten makes use of various features that are :doc:`kitty only
</protocol-extensions>`, such as the :doc:`kitty graphics protocol </protocol-extensions>`, such as the :doc:`kitty graphics protocol
</graphics-protocol>`, the :doc:`extended keyboard protocol </graphics-protocol>`, the :doc:`extended keyboard protocol
</keyboard-protocol>`, etc. It also leverages terminal program </keyboard-protocol>`, etc. It also leverages terminal program infrastructure
infrastructure I created for all of kitty's other kittens to reduce the amount I created for all of kitty's other kittens to reduce the amount of code needed
of code needed (the entire implementation is under 2000 lines of code). (the entire implementation is under 2000 lines of code).
And fundamentally, it's kitty only because I wrote it for myself, and I am And fundamentally, it's kitty only because I wrote it for myself, and I am
highly unlikely to use any other terminals :) highly unlikely to use any other terminals :)
Configuration Configuration
------------------------ ------------------------
You can configure the colors used, keyboard shortcuts, the diff implementation, You can configure the colors used, keyboard shortcuts, the diff implementation,
the default lines of context, etc. by creating a :file:`diff.conf` file in the default lines of context, etc. by creating a :file:`diff.conf` file in your
your :ref:`kitty config folder <confloc>`. See below for the supported :ref:`kitty config folder <confloc>`. See below for the supported configuration
configuration directives. directives.
.. include:: /generated/conf-kitten-diff.rst .. include:: /generated/conf-kitten-diff.rst
@ -145,7 +145,6 @@ configuration directives.
.. include:: /generated/cli-kitten-diff.rst .. include:: /generated/cli-kitten-diff.rst
Sample diff.conf Sample diff.conf
----------------- -----------------

52
docs/kittens/hints.rst
View File

@ -1,9 +1,9 @@
Hints Hints
========== ==========
|kitty| has a *hints mode* to select and act on arbitrary text snippets currently |kitty| has a *hints mode* to select and act on arbitrary text snippets
visible on the screen. For example, you can press :sc:`open_url` currently visible on the screen. For example, you can press :sc:`open_url`
to choose any URL visible on the screen and then open it using your system to choose any URL visible on the screen and then open it using your default web
browser. browser.
.. figure:: ../screenshots/hints_mode.png .. figure:: ../screenshots/hints_mode.png
@ -13,25 +13,29 @@ browser.
URL hints mode URL hints mode
Similarly, you can press :sc:`insert_selected_path` to Similarly, you can press :sc:`insert_selected_path` to select anything that
select anything that looks like a path or filename and then insert it into the looks like a path or filename and then insert it into the terminal, very useful
terminal, very useful for picking files from the output of a ``git`` or ``ls`` command and for picking files from the output of a :program:`git` or :program:`ls` command
adding them to the command line for the next command. and adding them to the command line for the next command.
You can also press :sc:`goto_file_line` to select anything that looks You can also press :sc:`goto_file_line` to select anything that looks like a
like a path or filename followed by a colon and a line number and open path or filename followed by a colon and a line number and open the file in
the file in vim at the specified line number. The patterns and editor :program:`vim` at the specified line number. The patterns and editor to be used
to be used can be modified using options passed to the kitten. For example:: can be modified using options passed to the kitten. For example::
map ctrl+g kitten hints --type=linenum --linenum-action=tab nvim +{line} {path} map ctrl+g kitten hints --type=linenum --linenum-action=tab nvim +{line} {path}
will open the selected file in a new tab inside neovim when you press will open the selected file in a new tab inside `Neovim <https://neovim.io/>`__
:kbd:`ctrl+g`. when you press :kbd:`Ctrl+G`.
Pressing :sc:`open_selected_hyperlink` will open hyperlinks, i.e. a URL Pressing :sc:`open_selected_hyperlink` will open :term:`hyperlinks`, i.e. a URL
that has been marked as such by the program running in the terminal, that has been marked as such by the program running in the terminal,
for example, by ``ls --hyperlink=auto``. You can also :doc:`customize what actions are for example, by ``ls --hyperlink=auto``. If :program:`ls` comes with your OS
taken for different types of URLs <../open_actions>`. does not support hyperlink, you may need to install `GNU Coreutils
<https://www.gnu.org/software/coreutils/>`__.
You can also :doc:`customize what actions are taken for different types of URLs
<../open_actions>`.
.. note:: If there are more hints than letters, hints will use multiple .. note:: If there are more hints than letters, hints will use multiple
letters. In this case, when you press the first letter, only hints letters. In this case, when you press the first letter, only hints
@ -50,11 +54,10 @@ Completely customizing the matching and actions of the kitten
The hints kitten supports writing simple python scripts that can be used to The hints kitten supports writing simple python scripts that can be used to
completely customize how it finds matches and what happens when a match is completely customize how it finds matches and what happens when a match is
selected. This allows the hints kitten to provide the user interface, while selected. This allows the hints kitten to provide the user interface, while you
you can provide the logic for finding matches and performing actions on them. can provide the logic for finding matches and performing actions on them. This
This is best illustrated with an example. Create the file is best illustrated with an example. Create the file :file:`custom-hints.py` in
:file:`custom-hints.py` in the kitty config directory with the following the :ref:`kitty config directory <confloc>` with the following contents:
contents:
.. code-block:: python .. code-block:: python
@ -98,9 +101,10 @@ look it up in the Google dictionary.
.. note:: .. note::
To avoid having to specify the same command line options on every invocation, To avoid having to specify the same command line options on every
you can use the :opt:`action_alias` option in :file:`kitty.conf`, creating aliases invocation, you can use the :opt:`action_alias` option in
that have common sets of options. For example:: :file:`kitty.conf`, creating aliases that have common sets of options.
For example::
action_alias myhints kitten hints --alphabet qfjdkslaureitywovmcxzpq1234567890 action_alias myhints kitten hints --alphabet qfjdkslaureitywovmcxzpq1234567890
map f1 myhints --customize-processing custom-hints.py map f1 myhints --customize-processing custom-hints.py

44
docs/kittens/hyperlinked_grep.rst
View File

@ -1,11 +1,10 @@
Hyperlinked grep Hyperlinked grep
================= =================
This kitten allows you to search your files using `ripgrep This kitten allows you to search your files using `ripgrep
<https://github.com/BurntSushi/ripgrep>`_ and open the results <https://github.com/BurntSushi/ripgrep>`__ and open the results directly in your
directly in your favorite editor in the terminal, at the line containing favorite editor in the terminal, at the line containing the search result,
the search result, simply by clicking on the result you want. simply by clicking on the result you want.
.. versionadded:: 0.19.0 .. versionadded:: 0.19.0
@ -25,19 +24,19 @@ following contents:
mime text/* mime text/*
action launch --type=overlay ${EDITOR} ${FILE_PATH} action launch --type=overlay ${EDITOR} ${FILE_PATH}
Now, run a search with:: Now, run a search with::
kitty +kitten hyperlinked_grep something kitty +kitten hyperlinked_grep something
Hold down the :kbd:`ctrl+shift` keys and click on any of the Hold down the :kbd:`Ctrl+Shift` keys and click on any of the result lines, to
result lines, to open the file in vim at the matching line. If open the file in :program:`vim` at the matching line. If you use some editor
you use some editor other than vim, you should adjust the other than :program:`vim`, you should adjust the :file:`open-actions.conf` file
:file:`open-actions.conf` file accordingly. accordingly.
Finally, add an alias to your shell's rc files to invoke the kitten as ``hg``:: Finally, add an alias to your shell's rc files to invoke the kitten as
:command:`hg`::
alias hg='kitty +kitten hyperlinked_grep' alias hg="kitty +kitten hyperlinked_grep"
You can now run searches with:: You can now run searches with::
@ -45,13 +44,13 @@ You can now run searches with::
hg some-search-term hg some-search-term
If you want to enable completion, for the kitten, you can delegate completion If you want to enable completion, for the kitten, you can delegate completion
to rg. How to do that varies based on the shell: to :program:`rg`. How to do that varies based on the shell:
.. tab:: zsh .. tab:: zsh
Instead of using an alias create a simple wrapper script named Instead of using an alias, create a simple wrapper script named
:file:`hg` somewhere in your ``PATH``: :program:`hg` somewhere in your :envvar:`PATH`:
.. code-block:: sh .. code-block:: sh
@ -64,22 +63,23 @@ to rg. How to do that varies based on the shell:
.. tab:: fish .. tab:: fish
You can combine both the aliasing/wrapping and pointing fish You can combine both the aliasing/wrapping and pointing fish to ripgrep's
to rg's autocompletion with a fish "wrapper" function in your :file:`config.fish`: autocompletion with a fish wrapper function in your :file:`config.fish`
or :file:`~/.config/fish/functions/hg.fish`:
.. code-block:: sh .. code-block:: fish
function hg --wraps rg; kitty +kitten hyperlinked_grep $argv; end function hg --wraps rg; kitty +kitten hyperlinked_grep $argv; end
To learn more about kitty's powerful framework for customizing URL click To learn more about kitty's powerful framework for customizing URL click
actions, :doc:`see here </open_actions>`. actions, see :doc:`here </open_actions>`.
Hopefully, someday this functionality will make it into some `upstream grep Hopefully, someday this functionality will make it into some `upstream grep
<https://github.com/BurntSushi/ripgrep/issues/665>`_ <https://github.com/BurntSushi/ripgrep/issues/665>`__ program directly removing
program directly removing the need for this kitten. the need for this kitten.
.. note:: .. note::
While you can pass any of ripgrep's comand line options to the kitten and While you can pass any of ripgrep's comand line options to the kitten and
they will be forwarded to rg, do not use options that change the output they will be forwarded to :program:`rg`, do not use options that change the
formatting as the kitten works by parsing the output from ripgrep. output formatting as the kitten works by parsing the output from ripgrep.

35
docs/kittens/icat.rst
View File

@ -9,8 +9,8 @@ terminal. Using it is as simple as::
kitty +kitten icat image.jpeg kitty +kitten icat image.jpeg
It supports all image types supported by `ImageMagick It supports all image types supported by `ImageMagick
<https://www.imagemagick.org>`_. It even works over SSH. For details, see <https://www.imagemagick.org>`__. It even works over SSH. For details, see the
the :doc:`kitty graphics protocol </graphics-protocol>`. :doc:`kitty graphics protocol </graphics-protocol>`.
You might want to create an alias in your shell's configuration files:: You might want to create an alias in your shell's configuration files::
@ -20,14 +20,14 @@ Then you can simply use ``icat image.png`` to view images.
.. note:: .. note::
`ImageMagick <https://www.imagemagick.org>`_ must be installed for ``icat`` to `ImageMagick <https://www.imagemagick.org>`__ must be installed for icat
work. kitten to work.
.. note:: .. note::
kitty's image display protocol may not work when used within a terminal kitty's image display protocol may not work when used within a terminal
multiplexer such as ``screen`` or ``tmux``, depending on whether the multiplexer such as :program:`screen` or :program:`tmux`, depending on
multiplexer has added support for it or not. whether the multiplexer has added support for it or not.
.. program:: kitty +kitten icat .. program:: kitty +kitten icat
@ -35,18 +35,19 @@ Then you can simply use ``icat image.png`` to view images.
The ``icat`` kitten has various command line arguments to allow it to be used The ``icat`` kitten has various command line arguments to allow it to be used
from inside other programs to display images. In particular, :option:`--place`, from inside other programs to display images. In particular, :option:`--place`,
:option:`--detect-support`, :option:`--silent` and :option:`--print-window-size`. :option:`--detect-support`, :option:`--silent` and
:option:`--print-window-size`.
If you are trying to integrate icat into a complex program like a file If you are trying to integrate icat into a complex program like a file manager
manager or editor, there are a few things to keep in mind. icat works by or editor, there are a few things to keep in mind. icat works by communicating
communicating over the TTY device, it both writes to and reads from the TTY. over the TTY device, it both writes to and reads from the TTY. So it is
So it is imperative that while it is running the host program does not do imperative that while it is running the host program does not do any TTY I/O.
any TTY I/O. Any key presses or other input from the user on the TTY device Any key presses or other input from the user on the TTY device will be
will be discarded. At a minimum, you should use the :option:`--silent` and discarded. At a minimum, you should use the :option:`--silent` and
:option:`--transfer-mode` command line arguments. To be :option:`--transfer-mode` command line arguments. To be really robust you should
really robust you should consider writing proper support for the consider writing proper support for the :doc:`kitty graphics protocol
:doc:`../graphics-protocol` in the program instead. Nowadays there are many </graphics-protocol>` in the program instead. Nowadays there are many libraries
libraries that have support for it. that have support for it.
.. include:: /generated/cli-kitten-icat.rst .. include:: /generated/cli-kitten-icat.rst

8
docs/kittens/panel.rst
View File

@ -4,8 +4,8 @@ Draw a GPU accelerated dock panel on your desktop
.. highlight:: sh .. highlight:: sh
You can use this kitten to draw a GPU accelerated panel on the edge You can use this kitten to draw a GPU accelerated panel on the edge of your
of your screen, that shows the output from an arbitrary terminal program. screen, that shows the output from an arbitrary terminal program.
It is useful for showing status information or notifications on your desktop It is useful for showing status information or notifications on your desktop
using terminal programs instead of GUI toolkits. using terminal programs instead of GUI toolkits.
@ -32,8 +32,8 @@ Using this kitten is simple, for example::
kitty +kitten panel sh -c 'printf "\n\n\nHello, world."; sleep 5s' kitty +kitten panel sh -c 'printf "\n\n\nHello, world."; sleep 5s'
This will show ``Hello, world.`` at the top edge of your screen for five This will show ``Hello, world.`` at the top edge of your screen for five
seconds. Here the terminal program we are running is ``sh`` with a script to seconds. Here the terminal program we are running is :program:`sh` with a script
print out ``Hello, world!``. You can make the terminal program as complex as to print out ``Hello, world!``. You can make the terminal program as complex as
you like, as demonstrated in the screenshot above. you like, as demonstrated in the screenshot above.

14
docs/kittens/query_terminal.rst
View File

@ -1,18 +1,18 @@
Query terminal Query terminal
================= =================
Used to query kitty from terminal programs about version, values of various This kitten is used to query |kitty| from terminal programs about version, values
runtime options controlling its features, etc. of various runtime options controlling its features, etc.
The querying is done using the (*semi*) standard XTGETTCAP escape sequence The querying is done using the (*semi*) standard XTGETTCAP escape sequence
pioneered by XTerm, so it works over SSH as well. The downside is that it pioneered by XTerm, so it works over SSH as well. The downside is that it is
is slow, since it requires a roundtrip to the terminal emulator and back. slow, since it requires a roundtrip to the terminal emulator and back.
If you want to do some of the same querying in your terminal program without If you want to do some of the same querying in your terminal program without
depending on the kitten, you can do so, by processing the same escape codes. depending on the kitten, you can do so, by processing the same escape codes.
Search `this page <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>`_ Search `this page <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>`__
for *XTGETTCAP* to see the syntax for the escape code and read the source for *XTGETTCAP* to see the syntax for the escape code and read the source of
of this kitten to find the values of the keys for the various queries. this kitten to find the values of the keys for the various queries.
.. include:: ../generated/cli-kitten-query_terminal.rst .. include:: ../generated/cli-kitten-query_terminal.rst

16
docs/kittens/remote_file.rst
View File

@ -1,12 +1,12 @@
Remote files Remote files
============== ==============
|kitty| has the ability to easily *Edit*, *Open* or *Download* files |kitty| has the ability to easily *Edit*, *Open* or *Download* files from a
from a computer into which you are SSHed. In your SSH session run:: computer into which you are SSHed. In your SSH session run::
ls --hyperlink=auto ls --hyperlink=auto
Then hold down :kbd:`ctrl+shift` and click the name of the file. Then hold down :kbd:`Ctrl+Shift` and click the name of the file.
.. figure:: ../screenshots/remote_file.png .. figure:: ../screenshots/remote_file.png
:alt: Remote file actions :alt: Remote file actions
@ -19,8 +19,8 @@ Then hold down :kbd:`ctrl+shift` and click the name of the file.
to *Edit* it in which case kitty will download it and open it locally in your to *Edit* it in which case kitty will download it and open it locally in your
:envvar:`EDITOR`. As you make changes to the file, they are automatically :envvar:`EDITOR`. As you make changes to the file, they are automatically
transferred to the remote computer. Note that this happens without needing transferred to the remote computer. Note that this happens without needing
to install *any* special software on the server, beyond ``ls`` that supports to install *any* special software on the server, beyond :program:`ls` that
hyperlinks. supports hyperlinks.
.. seealso:: See the :doc:`transfer` kitten .. seealso:: See the :doc:`transfer` kitten
@ -33,9 +33,9 @@ hyperlinks.
:doc:`transfer` kitten for such situations. :doc:`transfer` kitten for such situations.
.. note:: .. note::
If you have not setup automatic password-less SSH access, then, when If you have not setup automatic password-less SSH access, then, when editing
editing starts you will be asked to enter your password just once, starts you will be asked to enter your password just once, thereafter the SSH
thereafter the SSH connection will be re-used. connection will be re-used.
Similarly, you can choose to save the file to the local computer or download Similarly, you can choose to save the file to the local computer or download
and open it in its default file handler. and open it in its default file handler.

35
docs/kittens/themes.rst
View File

@ -1,8 +1,8 @@
Changing kitty colors Changing kitty colors
======================== ========================
The themes kitten allows you to easily change color themes, from a collection The themes kitten allows you to easily change color themes, from a collection of
of almost two hundred pre-built themes available at `kitty-themes over two hundred pre-built themes available at `kitty-themes
<https://github.com/kovidgoyal/kitty-themes>`_. To use it, simply run:: <https://github.com/kovidgoyal/kitty-themes>`_. To use it, simply run::
kitty +kitten themes kitty +kitten themes
@ -12,9 +12,9 @@ of almost two hundred pre-built themes available at `kitty-themes
:alt: The themes kitten in action :alt: The themes kitten in action
:width: 600 :width: 600
The kitten allows you to pick a theme, with live previews of the colors. You The kitten allows you to pick a theme, with live previews of the colors. You can
can choose between light and dark themes and search by theme name by just choose between light and dark themes and search by theme name by just typing a
typing a few characters from the name. few characters from the name.
The kitten maintains a list of recently used themes to allow quick switching. The kitten maintains a list of recently used themes to allow quick switching.
@ -24,14 +24,15 @@ If you want to restore the colors to default, you can do so by choosing the
.. versionadded:: 0.23.0 .. versionadded:: 0.23.0
The themes kitten The themes kitten
How it works How it works
---------------- ----------------
A theme in kitty is just a :file:`.conf` file containing kitty settings. A theme in kitty is just a :file:`.conf` file containing kitty settings.
When you select a theme, the kitten simply copies the :file:`.conf` file When you select a theme, the kitten simply copies the :file:`.conf` file
to :file:`~/.config/kitty/current-theme.conf` and adds an include for to :file:`~/.config/kitty/current-theme.conf` and adds an include for
:file:`current-theme.conf` to :file:`kitty.conf`. It also comments out :file:`current-theme.conf` to :file:`kitty.conf`. It also comments out any
any existing color settings in :file:`kitty.conf` so they do not interfere. existing color settings in :file:`kitty.conf` so they do not interfere.
Once that's done, the kitten sends kitty a signal to make it reload its config. Once that's done, the kitten sends kitty a signal to make it reload its config.
@ -39,9 +40,9 @@ Using your own themes
----------------------- -----------------------
You can also create your own themes as :file:`.conf` files. Put them in the You can also create your own themes as :file:`.conf` files. Put them in the
:file:`themes` sub-directory of the kitty config directory, usually, :file:`themes` sub-directory of the :ref:`kitty config directory <confloc>`,
:file:`~/.config/kitty/themes` and the kitten will automatically add them to usually, :file:`~/.config/kitty/themes`. The kitten will automatically add them
the list of themes. You can use this to modify the builtin themes, by giving to the list of themes. You can use this to modify the builtin themes, by giving
the conf file the name :file:`Some theme name.conf` to override the builtin the conf file the name :file:`Some theme name.conf` to override the builtin
theme of that name. Note that after doing so you have to run the kitten and theme of that name. Note that after doing so you have to run the kitten and
choose that theme once for your changes to be applied. choose that theme once for your changes to be applied.
@ -52,13 +53,13 @@ Contributing new themes
If you wish to contribute a new theme to the kitty theme repository, start by If you wish to contribute a new theme to the kitty theme repository, start by
going to the `kitty-themes <https://github.com/kovidgoyal/kitty-themes>`__ going to the `kitty-themes <https://github.com/kovidgoyal/kitty-themes>`__
repository. `Fork it repository. `Fork it
<https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_, and use the <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`__, and use the
file :download:`template.conf file :download:`template.conf
<https://github.com/kovidgoyal/kitty-themes/raw/master/template.conf>` as a <https://github.com/kovidgoyal/kitty-themes/raw/master/template.conf>` as a
template when creating your theme. Once you are satisfied with how it looks, template when creating your theme. Once you are satisfied with how it looks,
`submit a pull request `submit a pull request
<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_ <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`__
to have your theme merged into the `kitty-themes to have your theme merged into the `kitty-themes
<https://github.com/kovidgoyal/kitty-themes>`__ repository, which will make it <https://github.com/kovidgoyal/kitty-themes>`__ repository, which will make it
available in this kitten automatically. available in this kitten automatically.
@ -67,12 +68,12 @@ available in this kitten automatically.
Changing the theme non-interactively Changing the theme non-interactively
--------------------------------------- ---------------------------------------
You can specify the theme name as an argument when invoking the kitten You can specify the theme name as an argument when invoking the kitten to have
to have it change to that theme instantly. For example:: it change to that theme instantly. For example::
kitty +kitten themes --reload-in=all Dimmed Monokai kitty +kitten themes --reload-in=all Dimmed Monokai
Will change the theme to ``Dimmed Monokai`` in all running kitty Will change the theme to ``Dimmed Monokai`` in all running kitty instances. See
instances. See below for more details on non-interactive operation. below for more details on non-interactive operation.
.. include:: ../generated/cli-kitten-themes.rst .. include:: ../generated/cli-kitten-themes.rst

44
docs/kittens/transfer.rst
View File

@ -14,16 +14,16 @@ etc. Anywhere you have a terminal device, you can transfer files.
:alt: The transfer kitten at work :alt: The transfer kitten at work
This kitten supports transferring entire directory trees, preserving soft and This kitten supports transferring entire directory trees, preserving soft and
hard links, file permissions, times, etc. It even supports the rsync_ hard links, file permissions, times, etc. It even supports the rsync_ protocol
protocol to transfer only changes to large files. to transfer only changes to large files.
.. seealso:: See the :doc:`remote_file` kitten .. seealso:: See the :doc:`remote_file` kitten
.. note:: .. note::
This kitten (which practically means kitty) must be installed on the other This kitten (which practically means kitty) must be installed on the other
machine as well. If that is not possible you can use the :doc:`remote_file` machine as well. If that is not possible you can use the :doc:`remote_file`
kitten instead. Or write your own script to use the underlying :doc:`file transfer kitten instead. Or write your own script to use the underlying
protocol </file-transfer-protocol>`. :doc:`file transfer protocol </file-transfer-protocol>`.
.. versionadded:: 0.24.0 .. versionadded:: 0.24.0
@ -32,7 +32,8 @@ Basic usage
--------------- ---------------
In what follows, the *local computer* is the computer running this kitten and In what follows, the *local computer* is the computer running this kitten and
the *remote computer* is the computer connected to the other end of the TTY pipe. the *remote computer* is the computer connected to the other end of the TTY
pipe.
To send a file from the local computer to the remote computer, simply run:: To send a file from the local computer to the remote computer, simply run::
@ -42,7 +43,7 @@ You will be prompted by kitty for confirmation on allowing the transfer, and if
you grant permission, the file will be copied. you grant permission, the file will be copied.
Similarly, to get a file from the remote computer to the local computer, use Similarly, to get a file from the remote computer to the local computer, use
the :option:`kitty +kitten transfer --direction` option:: the :option:`--direction <kitty +kitten transfer --direction>` option::
kitty +kitten transfer --direction=receive /path/to/remote/file /path/to/destination/on/local/computer kitty +kitten transfer --direction=receive /path/to/remote/file /path/to/destination/on/local/computer
@ -58,25 +59,25 @@ the fact that you are copying multiple things) it is good practice to always
use a trailing slash when the destination is supposed to be a directory. use a trailing slash when the destination is supposed to be a directory.
Also, when transferring multiple files/directories it is a good idea to Also, when transferring multiple files/directories it is a good idea to
use the :option:`kitty +kitten transfer --confirm-paths` option which will give use the :option:`--confirm-paths <kitty +kitten transfer --confirm-paths>`
you an opportunity to review and confirm the files that will be touched. option which will give you an opportunity to review and confirm the files that
will be touched.
Avoiding the confirmation prompt Avoiding the confirmation prompt
------------------------------------ ------------------------------------
Normally, when you start a file transfer kitty will prompt you for Normally, when you start a file transfer kitty will prompt you for confirmation.
confirmation. This is to ensure that hostile programs running on a remote This is to ensure that hostile programs running on a remote machine cannot
machine cannot read/write files on your computer without your permission. read/write files on your computer without your permission. If the remote machine
If the remote machine is trusted and the connection between your computer is trusted and the connection between your computer and the remote machine is
and the remote machine is secure, then you can disable the confirmation prompt secure, then you can disable the confirmation prompt by:
by:
#. Setting the :opt:`file_transfer_confirmation_bypass` option to some #. Setting the :opt:`file_transfer_confirmation_bypass` option to some password.
password.
#. When invoking the kitten use the :option:`kitty +kitten transfer --permissions-bypass` #. When invoking the kitten use the :option:`--permissions-bypass
to supply the password you set in step one. <kitty +kitten transfer --permissions-bypass>` to supply the password you set
in step one.
.. warning:: Using a password to bypass confirmation means any software running .. warning:: Using a password to bypass confirmation means any software running
on the remote machine could potentially learn that password and use it to on the remote machine could potentially learn that password and use it to
@ -89,9 +90,10 @@ Delta transfers
----------------------------------- -----------------------------------
This kitten has the ability to use the rsync_ protocol to only transfer the This kitten has the ability to use the rsync_ protocol to only transfer the
differences between files. To turn it on use the :option:`kitty +kitten differences between files. To turn it on use the :option:`--transmit-deltas
transfer --transmit-deltas` option. Note that this will actually be slower when <kitty +kitten transfer --transmit-deltas>` option. Note that this will actually
transferring small files because of round trip overhead, so use with care. be slower when transferring small files because of round trip overhead, so use
with care.
.. include:: ../generated/cli-kitten-transfer.rst .. include:: ../generated/cli-kitten-transfer.rst

28
docs/kittens/unicode_input.rst
View File

@ -1,27 +1,29 @@
Unicode input Unicode input
================ ================
You can input unicode characters by name, hex code, recently used and even an editable favorites list. You can input Unicode characters by name, hex code, recently used and even an
Press :sc:`input_unicode_character` to start the unicode input widget, shown below. editable favorites list. Press :sc:`input_unicode_character` to start the
unicode input kitten, shown below.
.. figure:: ../screenshots/unicode.png .. figure:: ../screenshots/unicode.png
:alt: A screenshot of the unicode input widget :alt: A screenshot of the unicode input kitten
:align: center :align: center
:width: 100% :width: 100%
A screenshot of the unicode input widget A screenshot of the unicode input kitten
In :guilabel:`Code` mode, you enter a unicode character by typing in the hex code for the In :guilabel:`Code` mode, you enter a Unicode character by typing in the hex
character and pressing enter, for example, type in ``2716`` and press enter to get code for the character and pressing :kbd:`Enter`. For example, type in ``2716``
✖. You can also choose a character from the list of recently used characters by and press :kbd:`Enter` to get ``✖``. You can also choose a character from the
typing a leading period and then the two character index and pressing Enter. list of recently used characters by typing a leading period ``.`` and then the
The up and down arrow keys can be used to choose the previous and next unicode two character index and pressing :kbd:`Enter`.
symbol respectively. The :kbd:`Up` and :kbd:`Down` arrow keys can be used to choose the previous and
next Unicode symbol respectively.
In :guilabel:`Name` mode you instead type words from the character name and use In :guilabel:`Name` mode you instead type words from the character name and use
the arrow keys/tab to select the character from the displayed matches. You can the :kbd:`ArrowKeys` / :kbd:`Tab` to select the character from the displayed
also type a space followed by a period and the index for the match if you don't matches. You can also type a space followed by a period and the index for the
like to use arrow keys. match if you don't like to use arrow keys.
You can switch between modes using either the keys :kbd:`F1` ... :kbd:`F4` or You can switch between modes using either the keys :kbd:`F1` ... :kbd:`F4` or
:kbd:`Ctrl+1` ... :kbd:`Ctrl+4` or by pressing :kbd:`Ctrl+[` and :kbd:`Ctrl+]` :kbd:`Ctrl+1` ... :kbd:`Ctrl+4` or by pressing :kbd:`Ctrl+[` and :kbd:`Ctrl+]`

4
docs/kittens_intro.rst
View File

@ -34,7 +34,7 @@ Some prominent kittens:
:doc:`Unicode Input <kittens/unicode_input>` :doc:`Unicode Input <kittens/unicode_input>`
Easily input arbitrary unicode characters in |kitty| by name or hex code. Easily input arbitrary Unicode characters in |kitty| by name or hex code.
:doc:`Hints <kittens/hints>` :doc:`Hints <kittens/hints>`
@ -53,7 +53,7 @@ Some prominent kittens:
:doc:`Hyperlinked grep <kittens/hyperlinked_grep>` :doc:`Hyperlinked grep <kittens/hyperlinked_grep>`
Search your files using `ripgrep <https://github.com/BurntSushi/ripgrep>`_ Search your files using `ripgrep <https://github.com/BurntSushi/ripgrep>`__
and open the results directly in your favorite editor in the terminal, and open the results directly in your favorite editor in the terminal,
at the line containing the search result, simply by clicking on the result you want. at the line containing the search result, simply by clicking on the result you want.

41
docs/marks.rst
View File

@ -9,12 +9,12 @@ running programs or similar. Lets start with a few examples:
Examples Examples
---------- ----------
Suppose we want to be able to highlight the word ERROR in the current window. Suppose we want to be able to highlight the word :code:`ERROR` in the current
Add the following to :file:`kitty.conf`:: window. Add the following to :file:`kitty.conf`::
map f1 toggle_marker text 1 ERROR map f1 toggle_marker text 1 ERROR
Now when you press :kbd:`F1` all instances of the word :code:`ERROR` will be Now when you press :kbd:`F1`, all instances of the word :code:`ERROR` will be
highlighted. To turn off the highlighting, press :kbd:`F1` again. highlighted. To turn off the highlighting, press :kbd:`F1` again.
If you want to make it case-insensitive, use:: If you want to make it case-insensitive, use::
@ -39,25 +39,24 @@ can control the colors used for these groups in :file:`kitty.conf` with::
.. note:: .. note::
For performance reasons, matching is done per line only, and only when that line is For performance reasons, matching is done per line only, and only when that
altered in any way. So you cannot match text that stretches across multiple line is altered in any way. So you cannot match text that stretches across
lines. multiple lines.
Creating markers dynamically Creating markers dynamically
--------------------------------- ---------------------------------
If you want to create markers dynamically rather than pre-defining them in If you want to create markers dynamically rather than pre-defining them in
:file:`kitty.conf` you can do so as follows:: :file:`kitty.conf`, you can do so as follows::
map f1 create_marker map f1 create_marker
map f2 remove_marker map f2 remove_marker
Then pressing :kbd:`F1` will allow you to enter the marker definition and set Then pressing :kbd:`F1` will allow you to enter the marker definition and set
it and pressing :kbd:`F2` will remove the marker. ``create_marker`` accepts it and pressing :kbd:`F2` will remove the marker. ``create_marker`` accepts
the same syntax as ``toggle_marker`` above. Note that while creating the same syntax as ``toggle_marker`` above. Note that while creating markers,
markers, the prompt has history so you can easily re-use previous marker the prompt has history so you can easily re-use previous marker expressions.
expressions.
You can also use the facilities for :doc:`remote-control` to dynamically You can also use the facilities for :doc:`remote-control` to dynamically
add/remove markers. add/remove markers.
@ -66,14 +65,15 @@ add/remove markers.
Scrolling to marks Scrolling to marks
-------------------- --------------------
kitty has an action to scroll to the next line that contains a mark. You can kitty has an action :ac:`scroll_to_mark` to scroll to the next line that
use it by mapping it to some shortcut in :file:`kitty.conf`:: contains a mark. You can use it by mapping it to some shortcut in
:file:`kitty.conf`::
map ctrl+p scroll_to_mark prev map ctrl+p scroll_to_mark prev
map ctrl+n scroll_to_mark next map ctrl+n scroll_to_mark next
Then pressing :kbd:`ctrl+p` will scroll to the first line in the scrollback Then pressing :kbd:`Ctrl+P` will scroll to the first line in the scrollback
buffer above the current top line that contains a mark. Pressing :kbd:`ctrl+n` buffer above the current top line that contains a mark. Pressing :kbd:`Ctrl+N`
will scroll to show the first line below the current last line that contains will scroll to show the first line below the current last line that contains
a mark. If you wish to jump to a mark of a specific type, you can add that to a mark. If you wish to jump to a mark of a specific type, you can add that to
the mapping:: the mapping::
@ -86,7 +86,7 @@ Which will scroll only to marks of type 1.
The full syntax for creating marks The full syntax for creating marks
------------------------------------- -------------------------------------
The syntax of the :code:`toggle_marker` command is:: The syntax of the :ac:`toggle_marker` action is::
toggle_marker <marker-type> <specification> toggle_marker <marker-type> <specification>
@ -94,16 +94,16 @@ Here :code:`marker-type` is one of:
* :code:`text` - simple substring matching * :code:`text` - simple substring matching
* :code:`itext` - case-insensitive substring matching * :code:`itext` - case-insensitive substring matching
* :code:`regex` - A python regular expression * :code:`regex` - A Python regular expression
* :code:`iregex` - A case-insensitive python regular expression * :code:`iregex` - A case-insensitive Python regular expression
* :code:`function` - An arbitrary function defined in a python file, see :ref:`marker_funcs`. * :code:`function` - An arbitrary function defined in a Python file, see :ref:`marker_funcs`.
.. _marker_funcs: .. _marker_funcs:
Arbitrary marker functions Arbitrary marker functions
----------------------------- -----------------------------
You can create your own marker functions. Create a python file named You can create your own marker functions. Create a Python file named
:file:`mymarker.py` and in it create a :code:`marker` function. This :file:`mymarker.py` and in it create a :code:`marker` function. This
function receives the text of the line as input and must yield three numbers, function receives the text of the line as input and must yield three numbers,
the starting character position, the ending character position and the mark the starting character position, the ending character position and the mark
@ -122,6 +122,7 @@ Save this file somewhere and in :file:`kitty.conf`, use::
map f1 toggle_marker function /path/to/mymarker.py map f1 toggle_marker function /path/to/mymarker.py
If you save the file in the kitty config directory, you can use:: If you save the file in the :ref:`kitty config directory <confloc>`, you can
use::
map f1 toggle_marker function mymarker.py map f1 toggle_marker function mymarker.py

52
docs/open_actions.rst
View File

@ -1,15 +1,14 @@
Scripting the mouse click Scripting the mouse click
====================================================== ======================================================
|kitty| has support for `terminal hyperlinks |kitty| has support for :term:`terminal hyperlinks <hyperlinks>`. These are
<https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`_. These generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
are generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``, :ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on
:ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on these these hyperlinks in |kitty|.
hyperlinks in |kitty|.
You can tell kitty to take arbitrarily many, complex actions You can tell kitty to take arbitrarily many, complex actions when a link is
when a link is clicked. Let us illustrate with some examples, first. Create clicked. Let us illustrate with some examples, first. Create the file
the file :file:`~/.config/kitty/open-actions.conf` with the following: :file:`~/.config/kitty/open-actions.conf` with the following:
.. code:: conf .. code:: conf
@ -22,6 +21,13 @@ Now, run ``ls --hyperlink=auto`` in kitty and click on the filename of an
image, holding down :kbd:`ctrl+shift`. It will be opened over the current image, holding down :kbd:`ctrl+shift`. It will be opened over the current
window. Press any key to close it. window. Press any key to close it.
.. note::
The :program:`ls` comes with macOS does not support hyperlink, you need to
install `GNU Coreutils <https://www.gnu.org/software/coreutils/>`__. If you
install it via `Homebrew <https://formulae.brew.sh/formula/coreutils>`__, it
will be :program:`gls`.
Each entry in :file:`open-actions.conf` consists of one or more Each entry in :file:`open-actions.conf` consists of one or more
:ref:`matching_criteria`, such as ``protocol`` and ``mime`` and one or more :ref:`matching_criteria`, such as ``protocol`` and ``mime`` and one or more
``action`` entries. In the example above kitty uses the :doc:`launch <launch>` ``action`` entries. In the example above kitty uses the :doc:`launch <launch>`
@ -29,8 +35,8 @@ action which can be used to run external programs. Entries are separated by
blank lines. blank lines.
Actions are very powerful, anything that you can map to a key combination in Actions are very powerful, anything that you can map to a key combination in
`kitty.conf` can be used as an action. You can specify more than one action per :file:`kitty.conf` can be used as an action. You can specify more than one
entry if you like, for example: action per entry if you like, for example:
.. code:: conf .. code:: conf
@ -60,7 +66,7 @@ some special variables, documented below:
.. note:: .. note::
You can use the :opt:`action_alias` option just as in kitty.conf to You can use the :opt:`action_alias` option just as in :file:`kitty.conf` to
define aliases for frequently used actions. define aliases for frequently used actions.
@ -77,7 +83,7 @@ lines. The various available criteria are:
``protocol`` ``protocol``
A comma separated list of protocols, for example: ``http, https``. If A comma separated list of protocols, for example: ``http, https``. If
absent, there is no constraint on protocol absent, there is no constraint on protocol.
``url`` ``url``
A regular expression that must match against the entire (unquoted) URL A regular expression that must match against the entire (unquoted) URL
@ -88,11 +94,12 @@ lines. The various available criteria are:
``mime`` ``mime``
A comma separated list of MIME types, for example: ``text/*, image/*, A comma separated list of MIME types, for example: ``text/*, image/*,
application/pdf``. You can add MIME types to kitty by creating the application/pdf``. You can add MIME types to kitty by creating a file named
:file:`mime.types` in the kitty configuration directory. Useful if your :file:`mime.types` in the :ref:`kitty configuration directory <confloc>`.
system MIME database does not have definitions you need. This file is Useful if your system MIME database does not have definitions you need. This
in the standard format of one definition per line, like: ``text/plain rst file is in the standard format of one definition per line, like:
md``. Note that the MIME type for directories is ``inode/directory``. ``text/plain rst md``. Note that the MIME type for directories is
``inode/directory``.
``ext`` ``ext``
A comma separated list of file extensions, for example: ``jpeg, tar.gz`` A comma separated list of file extensions, for example: ``jpeg, tar.gz``
@ -116,9 +123,10 @@ URLs onto the kitty dock icon to open them with kitty. The default actions are:
These actions can also be executed from the command line by running:: These actions can also be executed from the command line by running::
open -a kitty.app file_or_url ... (on macOS only) kitty +open file_or_url another_url ...
or
kitty +open file_or_url ... # macOS only
open -a kitty.app file_or_url another_url ...
Since macOS lacks an official interface to set default URL scheme handlers, Since macOS lacks an official interface to set default URL scheme handlers,
kitty has a command you can use for it. The first argument for is the URL kitty has a command you can use for it. The first argument for is the URL
@ -133,8 +141,8 @@ defaults to kitty, if not specified. For example:
kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; import sys; cocoa_set_url_handler(*sys.argv[1:]); print("OK")' xyz someapp.bundle.identifier kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; import sys; cocoa_set_url_handler(*sys.argv[1:]); print("OK")' xyz someapp.bundle.identifier
You can customize these actions by creating a :file:`launch-actions.conf` file You can customize these actions by creating a :file:`launch-actions.conf` file
in the kitty config directory, just like in the :ref:`kitty config directory <confloc>`, just like the
the :file:`open-actions.conf` file above. For example: :file:`open-actions.conf` file above. For example:
.. code:: conf .. code:: conf

18
kittens/ask/main.py
View File

@ -92,17 +92,17 @@ be used for completions and via the browse history readline bindings.
--choice -c --choice -c
type=list type=list
dest=choices dest=choices
A choice for the choices type. Every choice has the syntax: letter:text Where A choice for the choices type. Can be specified multiple times. Every choice has
letter is the accelerator key and text is the corresponding text. There can be the syntax: ``letter[;color]:text``. Where :italic:`letter` is the accelerator key
an optional color specification after the letter to indicate what color it should and :italic:`text` is the corresponding text. There can be an optional color
be. specification after the letter to indicate what color it should be.
For example: y:Yes and n;red:No For example: :code:`y:Yes` and :code:`n;red:No`
--default -d --default -d
A default choice or text. If unspecified, it is "y" for :code:`yesno`, the first choice A default choice or text. If unspecified, it is :code:`y` for the type
for :code:`choices` and empty for others. The default choice is selected when the user :code:`yesno`, the first choice for :code:`choices` and empty for others types.
presses the Enter key. The default choice is selected when the user presses the :kbd:`Enter` key.
--prompt -p --prompt -p
@ -406,7 +406,7 @@ def main(args: List[str]) -> Response:
except SystemExit as e: except SystemExit as e:
if e.code != 0: if e.code != 0:
print(e.args[0]) print(e.args[0])
input('Press enter to quit...') input('Press Enter to quit')
raise SystemExit(e.code) raise SystemExit(e.code)
if cli_opts.type in ('yesno', 'choices'): if cli_opts.type in ('yesno', 'choices'):

2
kittens/broadcast/main.py
View File

@ -99,7 +99,7 @@ class Broadcast(Handler):
OPTIONS = (MATCH_WINDOW_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--match-tab -t')).format OPTIONS = (MATCH_WINDOW_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--match-tab -t')).format
help_text = 'Broadcast typed text to all kitty windows. By default text is sent to all windows, unless one of the matching options is specified' help_text = 'Broadcast typed text to kitty windows. By default text is sent to all windows, unless one of the matching options is specified'
usage = '[initial text to send ...]' usage = '[initial text to send ...]'

6
kittens/diff/main.py
View File

@ -571,8 +571,8 @@ OPTIONS = partial('''\
--context --context
type=int type=int
default=-1 default=-1
Number of lines of context to show between changes. Negative values Number of lines of context to show between changes. Negative values use the
use the number set in diff.conf number set in :file:`diff.conf`.
--config --config
@ -599,7 +599,7 @@ class ShowWarning:
showwarning = ShowWarning() showwarning = ShowWarning()
help_text = 'Show a side-by-side diff of the specified files/directories. You can also use ssh:hostname:remote-file-path to diff remote files.' help_text = 'Show a side-by-side diff of the specified files/directories. You can also use :italic:`ssh:hostname:remote-file-path` to diff remote files.'
usage = 'file_or_directory_left file_or_directory_right' usage = 'file_or_directory_left file_or_directory_right'

6
kittens/diff/options/definition.py
View File

@ -24,8 +24,8 @@ agr('diff', 'Diffing')
opt('syntax_aliases', 'pyj:py pyi:py recipe:py', opt('syntax_aliases', 'pyj:py pyi:py recipe:py',
option_type='syntax_aliases', option_type='syntax_aliases',
long_text=''' long_text='''
File extension aliases for syntax highlight For example, to syntax highlight File extension aliases for syntax highlight. For example, to syntax highlight
:file:`file.xyz` as :file:`file.abc` use a setting of :code:`xyz:abc` :file:`file.xyz` as :file:`file.abc` use a setting of :code:`xyz:abc`.
''' '''
) )
@ -38,7 +38,7 @@ opt('diff_cmd', 'auto',
long_text=''' long_text='''
The diff command to use. Must contain the placeholder :code:`_CONTEXT_` which The diff command to use. Must contain the placeholder :code:`_CONTEXT_` which
will be replaced by the number of lines of context. The default is to search the will be replaced by the number of lines of context. The default is to search the
system for either git or diff and use that, if found. system for either :program:`git` or :program:`diff` and use that, if found.
''' '''
) )

47
kittens/icat/main.py
View File

@ -42,24 +42,24 @@ Horizontal alignment for the displayed image.
--place --place
Choose where on the screen to display the image. The image will Choose where on the screen to display the image. The image will be scaled to fit
be scaled to fit into the specified rectangle. The syntax for into the specified rectangle. The syntax for specifying rectangles is
specifying rectangles is <:italic:`width`>x<:italic:`height`>@<:italic:`left`>x<:italic:`top`>. <:italic:`width`>x<:italic:`height`>@<:italic:`left`>x<:italic:`top`>.
All measurements are in cells (i.e. cursor positions) with the All measurements are in cells (i.e. cursor positions) with the origin
origin :italic:`(0, 0)` at the top-left corner of the screen. :italic:`(0, 0)` at the top-left corner of the screen.
--scale-up --scale-up
type=bool-set type=bool-set
When used in combination with :option:`--place` it will cause images that When used in combination with :option:`--place` it will cause images that are
are smaller than the specified area to be scaled up to use as much smaller than the specified area to be scaled up to use as much of the specified
of the specified area as possible. area as possible.
--background --background
default=none default=none
Specify a background color, this will cause transparent images to be composited on Specify a background color, this will cause transparent images to be composited
top of the specified color. on top of the specified color.
--mirror --mirror
@ -79,17 +79,18 @@ type=choices
choices=detect,file,stream choices=detect,file,stream
default=detect default=detect
Which mechanism to use to transfer images to the terminal. The default is to Which mechanism to use to transfer images to the terminal. The default is to
auto-detect. :italic:`file` means to use a temporary file and :italic:`stream` means to auto-detect. :italic:`file` means to use a temporary file and :italic:`stream`
send the data via terminal escape codes. Note that if you use the :italic:`file` means to send the data via terminal escape codes. Note that if you use the
transfer mode and you are connecting over a remote session then image display :italic:`file` transfer mode and you are connecting over a remote session then
will not work. image display will not work.
--detect-support --detect-support
type=bool-set type=bool-set
Detect support for image display in the terminal. If not supported, will exit Detect support for image display in the terminal. If not supported, will exit
with exit code 1, otherwise will exit with code 0 and print the supported with exit code 1, otherwise will exit with code 0 and print the supported
transfer mode to stderr, which can be used with the :option:`--transfer-mode` option. transfer mode to stderr, which can be used with the :option:`--transfer-mode`
option.
--detection-timeout --detection-timeout
@ -101,17 +102,17 @@ detecting image display support.
--print-window-size --print-window-size
type=bool-set type=bool-set
Print out the window size as :italic:`widthxheight` (in pixels) and quit. This is a Print out the window size as <:italic:`width`>x<:italic:`height`> (in pixels) and quit. This is a
convenience method to query the window size if using :code:`kitty +kitten icat` from a convenience method to query the window size if using :code:`kitty +kitten icat`
scripting language that cannot make termios calls. from a scripting language that cannot make termios calls.
--stdin --stdin
type=choices type=choices
choices=detect,yes,no choices=detect,yes,no
default=detect default=detect
Read image data from stdin. The default is to do it automatically, when STDIN is not a terminal, Read image data from STDIN. The default is to do it automatically, when STDIN is
but you can turn it off or on explicitly, if needed. not a terminal, but you can turn it off or on explicitly, if needed.
--silent --silent
@ -121,9 +122,9 @@ Do not print out anything to STDOUT during operation.
--z-index -z --z-index -z
default=0 default=0
Z-index of the image. When negative, text will be displayed on top of the image. Use Z-index of the image. When negative, text will be displayed on top of the image.
a double minus for values under the threshold for drawing images under cell background Use a double minus for values under the threshold for drawing images under cell
colors. For example, :code:`--1` evaluates as -1,073,741,825. background colors. For example, :code:`--1` evaluates as -1,073,741,825.
--loop -l --loop -l

32
kittens/query_terminal/main.py
View File

@ -66,7 +66,7 @@ def query(cls: Type[Query]) -> Type[Query]:
class TerminalName(Query): class TerminalName(Query):
name: str = 'name' name: str = 'name'
override_query_name: str = 'name' override_query_name: str = 'name'
help_text: str = f'Terminal name ({names[0]})' help_text: str = f'Terminal name (e.g. :code:`{names[0]}`)'
@staticmethod @staticmethod
def get_result(opts: Options) -> str: def get_result(opts: Options) -> str:
@ -76,7 +76,7 @@ class TerminalName(Query):
@query @query
class TerminalVersion(Query): class TerminalVersion(Query):
name: str = 'version' name: str = 'version'
help_text: str = 'Terminal version, for e.g.: 0.19.2' help_text: str = f'Terminal version (e.g. :code:`{str_version}`)'
@staticmethod @staticmethod
def get_result(opts: Options) -> str: def get_result(opts: Options) -> str:
@ -86,7 +86,7 @@ class TerminalVersion(Query):
@query @query
class AllowHyperlinks(Query): class AllowHyperlinks(Query):
name: str = 'allow_hyperlinks' name: str = 'allow_hyperlinks'
help_text: str = 'The :opt:`setting <allow_hyperlinks>` for allowing hyperlinks can be yes, no or ask' help_text: str = 'The :opt:`setting <allow_hyperlinks>` for allowing hyperlinks can be :code:`yes`, :code:`no` or :code:`ask`'
@staticmethod @staticmethod
def get_result(opts: Options) -> str: def get_result(opts: Options) -> str:
@ -154,7 +154,7 @@ class FontSize(Query):
@query @query
class ClipboardControl(Query): class ClipboardControl(Query):
name: str = 'clipboard_control' name: str = 'clipboard_control'
help_text: str = 'The :opt:`setting <clipboard_control>` for allowing reads/writes to/from the clipboard' help_text: str = 'The config option :opt:`clipboard_control` in :file:`kitty.conf` for allowing reads/writes to/from the clipboard'
@staticmethod @staticmethod
def get_result(opts: Options) -> str: def get_result(opts: Options) -> str:
@ -200,30 +200,28 @@ querying it.
help_text = '''\ help_text = '''\
Query the terminal this kitten is run in for various Query the terminal this kitten is run in for various capabilities. This sends
capabilities. This sends escape codes to the terminal escape codes to the terminal and based on its response prints out data about
and based on its response prints out data about supported supported capabilities. Note that this is a blocking operation, since it has to
capabilities. Note that this is a blocking operation, since wait for a response from the terminal. You can control the maximum wait time via
it has to wait for a response from the terminal. You can control the :code:`--wait-for` option.
the maximum wait time via the ``--wait-for`` option.
The output is lines of the form:: The output is lines of the form::
query: data :italic:`query`: :italic:`data`
If a particular query is unsupported by the running kitty version, If a particular query is unsupported by the running kitty version, the data will
the data will be blank. be blank.
Note that when calling this from another program, be very Note that when calling this from another program, be very careful not to perform
careful not to perform any I/O on the terminal device any I/O on the terminal device until thos kitten exits.
until the kitten exits.
Available queries are: Available queries are:
{} {}
'''.format('\n'.join( '''.format('\n'.join(
f'``{name}``\n {c.help_text}\n' for name, c in all_queries.items())) f':code:`{name}`:\n {c.help_text}\n' for name, c in all_queries.items()))
usage = '[query1 query2 ...]' usage = '[query1 query2 ...]'

6
kittens/remote_file/main.py
View File

@ -55,7 +55,7 @@ The data used to connect over ssh.
def show_error(msg: str) -> None: def show_error(msg: str) -> None:
print(styled(msg, fg='red')) print(styled(msg, fg='red'))
print() print()
print('Press any key to exit...') print('Press any key to quit')
sys.stdout.flush() sys.stdout.flush()
with raw_mode(): with raw_mode():
while True: while True:
@ -208,7 +208,7 @@ def main(args: List[str]) -> Result:
except SystemExit as e: except SystemExit as e:
if e.code != 0: if e.code != 0:
print(e.args[0]) print(e.args[0])
input('Press enter to quit...') input('Press Enter to quit')
raise SystemExit(e.code) raise SystemExit(e.code)
try: try:
@ -236,7 +236,7 @@ def save_as(conn_data: SSHConnectionData, remote_path: str, cli_opts: RemoteFile
last_used_path = tempfile.gettempdir() last_used_path = tempfile.gettempdir()
last_used_file = os.path.join(last_used_path, os.path.basename(remote_path)) last_used_file = os.path.join(last_used_path, os.path.basename(remote_path))
print( print(
'Where do you wish to save the file? Leaving it blank will save it as:', 'Where do you want to save the file? Leaving it blank will save it as:',
styled(last_used_file, fg='yellow') styled(last_used_file, fg='yellow')
) )
print('Relative paths will be resolved from:', styled(os.getcwd(), fg_intense=True, bold=True)) print('Relative paths will be resolved from:', styled(os.getcwd(), fg_intense=True, bold=True))

2
kittens/runner.py
View File

@ -175,4 +175,4 @@ def main() -> None:
print('Unhandled exception running kitten:') print('Unhandled exception running kitten:')
import traceback import traceback
traceback.print_exc() traceback.print_exc()
input('Press Enter to quit...') input('Press Enter to quit')

8
kittens/show_key/main.py
View File

@ -57,13 +57,15 @@ OPTIONS = r'''
default=normal default=normal
type=choices type=choices
choices=normal,application,kitty,unchanged choices=normal,application,kitty,unchanged
The keyboard mode to use when showing keys. "normal" mode is with DECCKM reset and "application" mode is with The keyboard mode to use when showing keys. :code:`normal` mode is with DECCKM
DECCKM set. "kitty" is the full kitty extended keyboard protocol. reset and :code:`application` mode is with DECCKM set. :code:`kitty` is the full
kitty extended keyboard protocol.
'''.format '''.format
help_text = 'Show the codes generated by the terminal for key presses in various keyboard modes'
def main(args: List[str]) -> None: def main(args: List[str]) -> None:
cli_opts, items = parse_args(args[1:], OPTIONS, '', '', 'kitty +kitten show_key', result_class=ShowKeyCLIOptions) cli_opts, items = parse_args(args[1:], OPTIONS, '', help_text, 'kitty +kitten show_key', result_class=ShowKeyCLIOptions)
if cli_opts.key_mode == 'kitty': if cli_opts.key_mode == 'kitty':
from .kitty_mode import main as kitty_main from .kitty_mode import main as kitty_main
return kitty_main() return kitty_main()

26
kittens/transfer/main.py
View File

@ -35,26 +35,28 @@ destination path on the receiving computer.
--permissions-bypass -p --permissions-bypass -p
The password to use to skip the transfer confirmation popup in kitty. Must match the The password to use to skip the transfer confirmation popup in kitty. Must match
password set for the :opt:`file_transfer_confirmation_bypass` option in kitty.conf. Note that the password set for the :opt:`file_transfer_confirmation_bypass` option in
leading and trailing whitespace is removed from the password. A password starting with :file:`kitty.conf`. Note that leading and trailing whitespace is removed from
., / or ~ characters is assumed to be a file name to read the password from. A value the password. A password starting with :code:`.`, :code:`/` or :code:`~`
of - means read the password from STDIN. A password that is purely a number less than 256 characters is assumed to be a file name to read the password from. A value of
is assumed to be the number of a file descriptor from which to read the actual password. :code:`-` means read the password from STDIN. A password that is purely a number
less than 256 is assumed to be the number of a file descriptor from which to
read the actual password.
--confirm-paths -c --confirm-paths -c
type=bool-set type=bool-set
Before actually transferring files, show a mapping of local file names to remote file names Before actually transferring files, show a mapping of local file names to remote
and ask for confirmation. file names and ask for confirmation.
--transmit-deltas -x --transmit-deltas -x
type=bool-set type=bool-set
If a file on the receiving side already exists, use the rsync algorithm to update it to match If a file on the receiving side already exists, use the rsync algorithm to
the file on the sending side, potentially saving lots of bandwidth and also automatically resuming update it to match the file on the sending side, potentially saving lots of
partial transfers. Note that this will actually degrade performance on fast links with small bandwidth and also automatically resuming partial transfers. Note that this will
files, so use with care. actually degrade performance on fast links with small files, so use with care.
''' '''

4
kittens/unicode_input/main.py
View File

@ -546,7 +546,7 @@ class UnicodeInput(Handler):
self.refresh() self.refresh()
help_text = 'Input a unicode character' help_text = 'Input a Unicode character'
usage = '' usage = ''
OPTIONS = ''' OPTIONS = '''
--emoji-variation --emoji-variation
@ -554,7 +554,7 @@ type=choices
default=none default=none
choices=none,graphic,text choices=none,graphic,text
Whether to use the textual or the graphical form for emoji. By default the Whether to use the textual or the graphical form for emoji. By default the
default form specified in the unicode standard for the symbol is used. default form specified in the Unicode standard for the symbol is used.
'''.format '''.format

2
kitty/shell.py
View File

@ -252,5 +252,5 @@ def main(global_opts: RCOptions) -> None:
real_main(global_opts) real_main(global_opts)
except Exception: except Exception:
traceback.print_exc() traceback.print_exc()
input('Press enter to quit...') input('Press Enter to quit')
raise SystemExit(1) raise SystemExit(1)