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

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

Browse Source
This commit is contained in:
Kovid Goyal
2022-04-27 20:18:39 +05:30
parent 627c79ffbb 510022c3c1
commit 2c1edb9611
29 changed files with 374 additions and 336 deletions
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
:file:`~/.config/kitty/kitty.conf`) but you can pass a specific path via the
:option:`kitty --config` option or use the ``KITTY_CONFIG_DIRECTORY``
environment variable. See the :option:`kitty --config` option for full details.
:option:`kitty --config` option or use the :envvar:`KITTY_CONFIG_DIRECTORY`
environment variable. See :option:`kitty --config` for full details.
Comments can be added to the config file as lines starting with the ``#``
character. This works only if the ``#`` character is the first character

5
docs/glossary.rst
View File

@@ -37,7 +37,8 @@ Glossary
hyperlinks
Terminals can have hyperlinks, just like the internet. In kitty you can
: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:
@@ -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
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
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*
The ``broadcast`` kitten can be used to type text simultaneously in
all kitty windows (or a subset as desired).
The ``broadcast`` kitten can be used to type text simultaneously in all
:term:`kitty windows <window>` (or a subset as desired).
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.
You can use the options described below to control which windows
are selected.
You can use the options described below to control which windows 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

105
docs/kittens/custom.rst
View File

@@ -1,21 +1,20 @@
Custom kittens
=================
You can easily create your own kittens to extend kitty. They are just
terminal programs written in Python. When launching a kitten, kitty will
open an overlay window over the current window and optionally pass the
contents of the current window/scrollback to the kitten over its :file:`STDIN`.
The kitten can then perform whatever actions it likes, just as a normal
terminal program. After execution of the kitten is complete, it has access
to the running kitty instance so it can perform arbitrary actions
such as closing windows, pasting text, etc.
You can easily create your own kittens to extend kitty. They are just terminal
programs written in Python. When launching a kitten, kitty will open an overlay
window over the current window and optionally pass the contents of the current
window/scrollback to the kitten over its :file:`STDIN`. The kitten can then
perform whatever actions it likes, just as a normal terminal program. After
execution of the kitten is complete, it has access to the running kitty instance
so it can perform arbitrary actions such as closing windows, pasting text, etc.
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.
Create a file in the kitty config folder, :file:`~/.config/kitty/mykitten.py`
(you might need to adjust the path to wherever the kitty config folder is on
your machine).
Create a file in the kitty config directory, :file:`~/.config/kitty/mykitten.py`
(you might need to adjust the path to wherever the :ref:`kitty config directory
<confloc>` is on your machine).
.. code-block:: python
@@ -43,11 +42,12 @@ Now in :file:`kitty.conf` add the lines::
map ctrl+k kitten mykitten.py
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
kittens. Look in the kittens sub-directory of the kitty source code for those.
Or see below for a list of :ref:`third-party kittens <external_kittens>`,
that other kitty users have created.
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
kittens. Look in the `kittens sub-directory
<https://github.com/kovidgoyal/kitty/tree/master/kittens>`__ of the kitty source
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
@@ -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
``handle_result()`` functions. Note also that the current working directory
of the kitten is set to the working directory of whatever program is
running in the active kitty window. The special argument ``@selection``
is replaced by the currently selected text in the active kitty window.
of the kitten is set to the working directory of whatever program is running in
the active kitty window. The special argument ``@selection`` is replaced by the
currently selected text in the active kitty window.
Passing the contents of the screen to the kitten
---------------------------------------------------
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()``
function, telling kitty what kind of input your kitten would like. For example:
and/or the scrollback buffer, you just need to add an annotation to the
``handle_result()`` function, telling kitty what kind of input your kitten would
like. For example:
.. code-block:: py
from typing import List
from kitty.boss import Boss
# in main, STDIN is for the kitten process and will contain
# the contents of the screen
def main(args):
def main(args: List[str]) -> str:
return sys.stdin.read()
# in handle_result, STDIN is for the kitty process itself, rather
# than the kitten process and should not be read from.
from kittens.tui.handler import result_handler
@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
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,
described in the table below:
:file:`STDIN`. There are many other types of input you can ask for, described in
the table below:
.. table:: Types of input to kittens
: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.
.. note::
For the types based on the output of a command,
:ref:`shell_integration` is required.
For the types based on the output of a command, :ref:`shell_integration` is
required.
Using kittens to script kitty, without any terminal UI
-----------------------------------------------------------
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
``handle_result()`` function without first running the ``main()`` function.
terminal program, you can tell the kittens system to run the ``handle_result()``
function without first running the ``main()`` function.
For example, here is a kitten that "zooms/unzooms" the current terminal window
by switching to the stack layout or back to the previous layout. This is
For example, here is a kitten that "zooms in/zooms out" the current terminal
window by switching to the stack layout or back to the previous layout. This is
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
def main(args):
from typing import List
from kitty.boss import Boss
def main(args: List[str]) -> str:
pass
from kittens.tui.handler import result_handler
@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
if tab is not None:
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')
Now in kitty.conf add::
Now in :file:`kitty.conf` add::
map f11 kitten zoom_toggle.py
@@ -165,7 +173,7 @@ layout, by simply adding the line::
boss.toggle_fullscreen()
To the ``handle_result()`` function, above.
to the ``handle_result()`` function, above.
.. _send_mouse_event:
@@ -173,7 +181,7 @@ To the ``handle_result()`` function, above.
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::
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
--------------------
The part of the kitten that runs in ``main()`` is just a normal program and
the output of print statements will be visible in the kitten window. Or
alternately, you can use::
The part of the kitten that runs in ``main()`` is just a normal program and the
output of print statements will be visible in the kitten window. Or alternately,
you can use::
from kittens.tui.loop import debug
debug('whatever')
The ``debug()`` function is just like ``print()`` except that the output
will appear in the ``STDOUT`` of the kitty process inside which the kitten is
The ``debug()`` function is just like ``print()`` except that the output will
appear in the ``STDOUT`` of the kitty process inside which the kitten is
running.
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
in the first kitty instance.
Adding options to kittens
----------------------------
If you would like to use kitty's config framework to make your kittens
configurable, you will need some boilerplate. In the directory
of your kitten make the following files.
configurable, you will need some boilerplate. Put the following files in the
directory of your kitten.
: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
return opts
See the code for the builtin diff kitten for examples of creating more options
and keyboard shortcuts.
See `the code <https://github.com/kovidgoyal/kitty/tree/master/kittens/diff>`__
for the builtin :doc:`diff kitten </kittens/diff>` for examples of creating more
options and keyboard shortcuts.
.. _external_kittens:
@@ -320,7 +330,8 @@ Kittens created by kitty users
---------------------------------------------
`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>`_
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
* Does syntax highlighting of the displayed diffs, asynchronously, for maximum
speed
* Does syntax highlighting of the displayed diffs, asynchronously, for
maximum speed
* Displays images as well as text diffs, even over SSH
@@ -31,11 +31,11 @@ Major Features
Installation
---------------
Simply :ref:`install kitty <quickstart>`. You also need
to have either the `git <https://git-scm.com/>`_ program or the ``diff`` program
installed. Additionally, for syntax highlighting to work,
`pygments <https://pygments.org/>`_ must be installed (note that pygments is
included in the official kitty binary builds).
Simply :ref:`install kitty <quickstart>`. You also need to have either the `git
<https://git-scm.com/>`__ program or the :program:`diff` program installed.
Additionally, for syntax highlighting to work, `pygments
<https://pygments.org/>`__ must be installed (note that pygments is included in
the official kitty binary builds).
Usage
@@ -45,9 +45,10 @@ In the kitty terminal, run::
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
@@ -67,20 +68,20 @@ Keyboard controls
========================= ===========================
Action Shortcut
========================= ===========================
Quit :kbd:`q`, :kbd:`ctrl+c`, :kbd:`Esc`
Scroll line up :kbd:`k`, :kbd:`Up`
Scroll line down :kbd:`j`, :kbd:`Down`
Quit :kbd:`Q`, :kbd:`Ctrl+C`, :kbd:`Esc`
Scroll line up :kbd:`K`, :kbd:`Up`
Scroll line down :kbd:`J`, :kbd:`Down`
Scroll page up :kbd:`PgUp`
Scroll page down :kbd:`PgDn`
Scroll to top :kbd:`Home`
Scroll to bottom :kbd:`End`
Scroll to next page :kbd:`Space`, :kbd:`PgDn`
Scroll to previous page :kbd:`PgUp`
Scroll to next change :kbd:`n`
Scroll to previous change :kbd:`p`
Scroll to next change :kbd:`N`
Scroll to previous change :kbd:`P`
Increase 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:`=`
Search forwards :kbd:`/`
Search backwards :kbd:`?`
@@ -93,7 +94,7 @@ Scroll to previous match :kbd:`<`, :kbd:`,`
Integrating with git
-----------------------
Add the following to `~/.gitconfig`:
Add the following to :file:`~/.gitconfig`:
.. 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
</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
</keyboard-protocol>`, etc. It also leverages terminal program
infrastructure I created for all of kitty's other kittens to reduce the amount
of code needed (the entire implementation is under 2000 lines of code).
</keyboard-protocol>`, etc. It also leverages terminal program infrastructure
I created for all of kitty's other kittens to reduce the amount of code needed
(the entire implementation is under 2000 lines of code).
And fundamentally, it's kitty only because I wrote it for myself, and I am
highly unlikely to use any other terminals :)
Configuration
------------------------
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
your :ref:`kitty config folder <confloc>`. See below for the supported
configuration directives.
the default lines of context, etc. by creating a :file:`diff.conf` file in your
:ref:`kitty config folder <confloc>`. See below for the supported configuration
directives.
.. include:: /generated/conf-kitten-diff.rst
@@ -145,7 +145,6 @@ configuration directives.
.. include:: /generated/cli-kitten-diff.rst
Sample diff.conf
-----------------

52
docs/kittens/hints.rst
View File

@@ -1,9 +1,9 @@
Hints
==========
|kitty| has a *hints mode* to select and act on arbitrary text snippets 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
|kitty| has a *hints mode* to select and act on arbitrary text snippets
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 default web
browser.
.. figure:: ../screenshots/hints_mode.png
@@ -13,25 +13,29 @@ browser.
URL hints mode
Similarly, you can press :sc:`insert_selected_path` to
select anything that looks like a path or filename and then insert it into the
terminal, very useful for picking files from the output of a ``git`` or ``ls`` command and
adding them to the command line for the next command.
Similarly, you can press :sc:`insert_selected_path` to select anything that
looks like a path or filename and then insert it into the terminal, very useful
for picking files from the output of a :program:`git` or :program:`ls` 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
like a path or filename followed by a colon and a line number and open
the file in vim at the specified line number. The patterns and editor
to be used can be modified using options passed to the kitten. For example::
You can also press :sc:`goto_file_line` to select anything that looks like a
path or filename followed by a colon and a line number and open the file in
:program:`vim` at the specified line number. The patterns and editor to be used
can be modified using options passed to the kitten. For example::
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
:kbd:`ctrl+g`.
will open the selected file in a new tab inside `Neovim <https://neovim.io/>`__
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,
for example, by ``ls --hyperlink=auto``. You can also :doc:`customize what actions are
taken for different types of URLs <../open_actions>`.
for example, by ``ls --hyperlink=auto``. If :program:`ls` comes with your OS
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
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
completely customize how it finds matches and what happens when a match is
selected. This allows the hints kitten to provide the user interface, while
you can provide the logic for finding matches and performing actions on them.
This is best illustrated with an example. Create the file
:file:`custom-hints.py` in the kitty config directory with the following
contents:
selected. This allows the hints kitten to provide the user interface, while you
can provide the logic for finding matches and performing actions on them. This
is best illustrated with an example. Create the file :file:`custom-hints.py` in
the :ref:`kitty config directory <confloc>` with the following contents:
.. code-block:: python
@@ -98,9 +101,10 @@ look it up in the Google dictionary.
.. note::
To avoid having to specify the same command line options on every invocation,
you can use the :opt:`action_alias` option in :file:`kitty.conf`, creating aliases
that have common sets of options. For example::
To avoid having to specify the same command line options on every
invocation, you can use the :opt:`action_alias` option in
:file:`kitty.conf`, creating aliases that have common sets of options.
For example::
action_alias myhints kitten hints --alphabet qfjdkslaureitywovmcxzpq1234567890
map f1 myhints --customize-processing custom-hints.py

44
docs/kittens/hyperlinked_grep.rst
View File

@@ -1,11 +1,10 @@
Hyperlinked grep
=================
This kitten allows you to search your files using `ripgrep
<https://github.com/BurntSushi/ripgrep>`_ and open the results
directly in your favorite editor in the terminal, at the line containing
the search result, simply by clicking on the result you want.
<https://github.com/BurntSushi/ripgrep>`__ and open the results directly in your
favorite editor in the terminal, at the line containing the search result,
simply by clicking on the result you want.
.. versionadded:: 0.19.0
@@ -25,19 +24,19 @@ following contents:
mime text/*
action launch --type=overlay ${EDITOR} ${FILE_PATH}
Now, run a search with::
kitty +kitten hyperlinked_grep something
Hold down the :kbd:`ctrl+shift` keys and click on any of the
result lines, to open the file in vim at the matching line. If
you use some editor other than vim, you should adjust the
:file:`open-actions.conf` file accordingly.
Hold down the :kbd:`Ctrl+Shift` keys and click on any of the result lines, to
open the file in :program:`vim` at the matching line. If you use some editor
other than :program:`vim`, you should adjust the :file:`open-actions.conf` file
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::
@@ -45,13 +44,13 @@ You can now run searches with::
hg some-search-term
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
Instead of using an alias create a simple wrapper script named
:file:`hg` somewhere in your ``PATH``:
Instead of using an alias, create a simple wrapper script named
:program:`hg` somewhere in your :envvar:`PATH`:
.. code-block:: sh
@@ -64,22 +63,23 @@ to rg. How to do that varies based on the shell:
.. tab:: fish
You can combine both the aliasing/wrapping and pointing fish
to rg's autocompletion with a fish "wrapper" function in your :file:`config.fish`:
You can combine both the aliasing/wrapping and pointing fish to ripgrep's
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
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
<https://github.com/BurntSushi/ripgrep/issues/665>`_
program directly removing the need for this kitten.
<https://github.com/BurntSushi/ripgrep/issues/665>`__ program directly removing
the need for this kitten.
.. note::
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
formatting as the kitten works by parsing the output from ripgrep.
they will be forwarded to :program:`rg`, do not use options that change the
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
It supports all image types supported by `ImageMagick
<https://www.imagemagick.org>`_. It even works over SSH. For details, see
the :doc:`kitty graphics protocol </graphics-protocol>`.
<https://www.imagemagick.org>`__. It even works over SSH. For details, see the
:doc:`kitty graphics protocol </graphics-protocol>`.
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::
`ImageMagick <https://www.imagemagick.org>`_ must be installed for ``icat`` to
work.
`ImageMagick <https://www.imagemagick.org>`__ must be installed for icat
kitten to work.
.. note::
kitty's image display protocol may not work when used within a terminal
multiplexer such as ``screen`` or ``tmux``, depending on whether the
multiplexer has added support for it or not.
multiplexer such as :program:`screen` or :program:`tmux`, depending on
whether the multiplexer has added support for it or not.
.. 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
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
manager or editor, there are a few things to keep in mind. icat works by
communicating over the TTY device, it both writes to and reads from the TTY.
So it is imperative that while it is running the host program does not do
any TTY I/O. Any key presses or other input from the user on the TTY device
will be discarded. At a minimum, you should use the :option:`--silent` and
:option:`--transfer-mode` command line arguments. To be
really robust you should consider writing proper support for the
:doc:`../graphics-protocol` in the program instead. Nowadays there are many
libraries that have support for it.
If you are trying to integrate icat into a complex program like a file manager
or editor, there are a few things to keep in mind. icat works by communicating
over the TTY device, it both writes to and reads from the TTY. So it is
imperative that while it is running the host program does not do any TTY I/O.
Any key presses or other input from the user on the TTY device will be
discarded. At a minimum, you should use the :option:`--silent` and
:option:`--transfer-mode` command line arguments. To be really robust you should
consider writing proper support for the :doc:`kitty graphics protocol
</graphics-protocol>` in the program instead. Nowadays there are many libraries
that have support for it.
.. 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
You can use this kitten to draw a GPU accelerated panel on the edge
of your screen, that shows the output from an arbitrary terminal program.
You can use this kitten to draw a GPU accelerated panel on the edge of your
screen, that shows the output from an arbitrary terminal program.
It is useful for showing status information or notifications on your desktop
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'
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
print out ``Hello, world!``. You can make the terminal program as complex as
seconds. Here the terminal program we are running is :program:`sh` with a script
to print out ``Hello, world!``. You can make the terminal program as complex as
you like, as demonstrated in the screenshot above.

14
docs/kittens/query_terminal.rst
View File

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

16
docs/kittens/remote_file.rst
View File

@@ -1,12 +1,12 @@
Remote files
==============
|kitty| has the ability to easily *Edit*, *Open* or *Download* files
from a computer into which you are SSHed. In your SSH session run::
|kitty| has the ability to easily *Edit*, *Open* or *Download* files from a
computer into which you are SSHed. In your SSH session run::
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
: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
:envvar:`EDITOR`. As you make changes to the file, they are automatically
transferred to the remote computer. Note that this happens without needing
to install *any* special software on the server, beyond ``ls`` that supports
hyperlinks.
to install *any* special software on the server, beyond :program:`ls` that
supports hyperlinks.
.. seealso:: See the :doc:`transfer` kitten
@@ -33,9 +33,9 @@ hyperlinks.
:doc:`transfer` kitten for such situations.
.. note::
If you have not setup automatic password-less SSH access, then, when
editing starts you will be asked to enter your password just once,
thereafter the SSH connection will be re-used.
If you have not setup automatic password-less SSH access, then, when editing
starts you will be asked to enter your password just once, thereafter the SSH
connection will be re-used.
Similarly, you can choose to save the file to the local computer or download
and open it in its default file handler.

35
docs/kittens/themes.rst
View File

@@ -1,8 +1,8 @@
Changing kitty colors
========================
The themes kitten allows you to easily change color themes, from a collection
of almost two hundred pre-built themes available at `kitty-themes
The themes kitten allows you to easily change color themes, from a collection of
over two hundred pre-built themes available at `kitty-themes
<https://github.com/kovidgoyal/kitty-themes>`_. To use it, simply run::
kitty +kitten themes
@@ -12,9 +12,9 @@ of almost two hundred pre-built themes available at `kitty-themes
:alt: The themes kitten in action
:width: 600
The kitten allows you to pick a theme, with live previews of the colors. You
can choose between light and dark themes and search by theme name by just
typing a few characters from the name.
The kitten allows you to pick a theme, with live previews of the colors. You can
choose between light and dark themes and search by theme name by just typing a
few characters from the name.
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
The themes kitten
How it works
----------------
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
to :file:`~/.config/kitty/current-theme.conf` and adds an include for
:file:`current-theme.conf` to :file:`kitty.conf`. It also comments out
any existing color settings in :file:`kitty.conf` so they do not interfere.
:file:`current-theme.conf` to :file:`kitty.conf`. It also comments out any
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.
@@ -39,9 +40,9 @@ Using your own themes
-----------------------
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:`~/.config/kitty/themes` and the kitten will automatically add them to
the list of themes. You can use this to modify the builtin themes, by giving
:file:`themes` sub-directory of the :ref:`kitty config directory <confloc>`,
usually, :file:`~/.config/kitty/themes`. The kitten will automatically add them
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
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.
@@ -52,13 +53,13 @@ Contributing new themes
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>`__
repository. `Fork it
<https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_, and use the
repository. `Fork it
<https://docs.github.com/en/get-started/quickstart/fork-a-repo>`__, and use the
file :download:`template.conf
<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,
`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
<https://github.com/kovidgoyal/kitty-themes>`__ repository, which will make it
available in this kitten automatically.
@@ -67,12 +68,12 @@ available in this kitten automatically.
Changing the theme non-interactively
---------------------------------------
You can specify the theme name as an argument when invoking the kitten
to have it change to that theme instantly. For example::
You can specify the theme name as an argument when invoking the kitten to have
it change to that theme instantly. For example::
kitty +kitten themes --reload-in=all Dimmed Monokai
Will change the theme to ``Dimmed Monokai`` in all running kitty
instances. See below for more details on non-interactive operation.
Will change the theme to ``Dimmed Monokai`` in all running kitty instances. See
below for more details on non-interactive operation.
.. 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
This kitten supports transferring entire directory trees, preserving soft and
hard links, file permissions, times, etc. It even supports the rsync_
protocol to transfer only changes to large files.
hard links, file permissions, times, etc. It even supports the rsync_ protocol
to transfer only changes to large files.
.. seealso:: See the :doc:`remote_file` kitten
.. note::
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`
kitten instead. Or write your own script to use the underlying :doc:`file transfer
protocol </file-transfer-protocol>`.
kitten instead. Or write your own script to use the underlying
:doc:`file transfer protocol </file-transfer-protocol>`.
.. versionadded:: 0.24.0
@@ -32,7 +32,8 @@ Basic usage
---------------
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::
@@ -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.
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
@@ -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.
Also, when transferring multiple files/directories it is a good idea to
use the :option:`kitty +kitten transfer --confirm-paths` option which will give
you an opportunity to review and confirm the files that will be touched.
use the :option:`--confirm-paths <kitty +kitten transfer --confirm-paths>`
option which will give you an opportunity to review and confirm the files that
will be touched.
Avoiding the confirmation prompt
------------------------------------
Normally, when you start a file transfer kitty will prompt you for
confirmation. This is to ensure that hostile programs running on a remote
machine cannot read/write files on your computer without your permission.
If the remote machine is trusted and the connection between your computer
and the remote machine is secure, then you can disable the confirmation prompt
by:
Normally, when you start a file transfer kitty will prompt you for confirmation.
This is to ensure that hostile programs running on a remote machine cannot
read/write files on your computer without your permission. If the remote machine
is trusted and the connection between your computer and the remote machine is
secure, then you can disable the confirmation prompt by:
#. Setting the :opt:`file_transfer_confirmation_bypass` option to some
password.
#. Setting the :opt:`file_transfer_confirmation_bypass` option to some password.
#. When invoking the kitten use the :option:`kitty +kitten transfer --permissions-bypass`
to supply the password you set in step one.
#. When invoking the kitten use the :option:`--permissions-bypass
<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
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
differences between files. To turn it on use the :option:`kitty +kitten
transfer --transmit-deltas` option. Note that this will actually be slower when
transferring small files because of round trip overhead, so use with care.
differences between files. To turn it on use the :option:`--transmit-deltas
<kitty +kitten transfer --transmit-deltas>` option. Note that this will actually
be slower when transferring small files because of round trip overhead, so use
with care.
.. include:: ../generated/cli-kitten-transfer.rst

28
docs/kittens/unicode_input.rst
View File

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

4
docs/kittens_intro.rst
View File

@@ -34,7 +34,7 @@ Some prominent kittens:
: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>`
@@ -53,7 +53,7 @@ Some prominent kittens:
: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,
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
----------
Suppose we want to be able to highlight the word ERROR in the current window.
Add the following to :file:`kitty.conf`::
Suppose we want to be able to highlight the word :code:`ERROR` in the current
window. Add the following to :file:`kitty.conf`::
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.
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::
For performance reasons, matching is done per line only, and only when that line is
altered in any way. So you cannot match text that stretches across multiple
lines.
For performance reasons, matching is done per line only, and only when that
line is altered in any way. So you cannot match text that stretches across
multiple lines.
Creating markers dynamically
---------------------------------
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 f2 remove_marker
Then pressing :kbd:`F1` will allow you to enter the marker definition and set
it and pressing :kbd:`F2` will remove the marker. ``create_marker`` accepts
the same syntax as ``toggle_marker`` above. Note that while creating
markers, the prompt has history so you can easily re-use previous marker
expressions.
the same syntax as ``toggle_marker`` above. Note that while creating markers,
the prompt has history so you can easily re-use previous marker expressions.
You can also use the facilities for :doc:`remote-control` to dynamically
add/remove markers.
@@ -66,14 +65,15 @@ add/remove markers.
Scrolling to marks
--------------------
kitty has an action to scroll to the next line that contains a mark. You can
use it by mapping it to some shortcut in :file:`kitty.conf`::
kitty has an action :ac:`scroll_to_mark` to scroll to the next line that
contains a mark. You can use it by mapping it to some shortcut in
:file:`kitty.conf`::
map ctrl+p scroll_to_mark prev
map ctrl+n scroll_to_mark next
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`
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`
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
the mapping::
@@ -86,7 +86,7 @@ Which will scroll only to marks of type 1.
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>
@@ -94,16 +94,16 @@ Here :code:`marker-type` is one of:
* :code:`text` - simple substring matching
* :code:`itext` - case-insensitive substring matching
* :code:`regex` - A python regular expression
* :code:`iregex` - A case-insensitive python regular expression
* :code:`function` - An arbitrary function defined in a python file, see :ref:`marker_funcs`.
* :code:`regex` - A Python regular expression
* :code:`iregex` - A case-insensitive Python regular expression
* :code:`function` - An arbitrary function defined in a Python file, see :ref:`marker_funcs`.
.. _marker_funcs:
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
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
@@ -122,6 +122,7 @@ Save this file somewhere and in :file:`kitty.conf`, use::
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

52
docs/open_actions.rst
View File

@@ -1,15 +1,14 @@
Scripting the mouse click
======================================================
|kitty| has support for `terminal hyperlinks
<https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`_. These
are generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
:ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on these
hyperlinks in |kitty|.
|kitty| has support for :term:`terminal hyperlinks <hyperlinks>`. These are
generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
:ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on
these hyperlinks in |kitty|.
You can tell kitty to take arbitrarily many, complex actions
when a link is clicked. Let us illustrate with some examples, first. Create
the file :file:`~/.config/kitty/open-actions.conf` with the following:
You can tell kitty to take arbitrarily many, complex actions when a link is
clicked. Let us illustrate with some examples, first. Create the file
:file:`~/.config/kitty/open-actions.conf` with the following:
.. 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
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
:ref:`matching_criteria`, such as ``protocol`` and ``mime`` and one or more
``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.
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
entry if you like, for example:
:file:`kitty.conf` can be used as an action. You can specify more than one
action per entry if you like, for example:
.. code:: conf
@@ -60,7 +66,7 @@ some special variables, documented below:
.. 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.
@@ -77,7 +83,7 @@ lines. The various available criteria are:
``protocol``
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``
A regular expression that must match against the entire (unquoted) URL
@@ -88,11 +94,12 @@ lines. The various available criteria are:
``mime``
A comma separated list of MIME types, for example: ``text/*, image/*,
application/pdf``. You can add MIME types to kitty by creating the
:file:`mime.types` in the kitty configuration directory. Useful if your
system MIME database does not have definitions you need. This file is
in the standard format of one definition per line, like: ``text/plain rst
md``. Note that the MIME type for directories is ``inode/directory``.
application/pdf``. You can add MIME types to kitty by creating a file named
:file:`mime.types` in the :ref:`kitty configuration directory <confloc>`.
Useful if your system MIME database does not have definitions you need. This
file is in the standard format of one definition per line, like:
``text/plain rst md``. Note that the MIME type for directories is
``inode/directory``.
``ext``
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::
open -a kitty.app file_or_url ... (on macOS only)
or
kitty +open file_or_url ...
kitty +open file_or_url another_url ...
# macOS only
open -a kitty.app file_or_url another_url ...
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
@@ -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
You can customize these actions by creating a :file:`launch-actions.conf` file
in the kitty config directory, just like
the :file:`open-actions.conf` file above. For example:
in the :ref:`kitty config directory <confloc>`, just like the
:file:`open-actions.conf` file above. For example:
.. 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
type=list
dest=choices
A choice for the choices type. Every choice has the syntax: letter:text Where
letter is the accelerator key and text is the corresponding text. There can be
an optional color specification after the letter to indicate what color it should
be.
For example: y:Yes and n;red:No
A choice for the choices type. Can be specified multiple times. Every choice has
the syntax: ``letter[;color]:text``. Where :italic:`letter` is the accelerator key
and :italic:`text` is the corresponding text. There can be an optional color
specification after the letter to indicate what color it should be.
For example: :code:`y:Yes` and :code:`n;red:No`
--default -d
A default choice or text. If unspecified, it is "y" for :code:`yesno`, the first choice
for :code:`choices` and empty for others. The default choice is selected when the user
presses the Enter key.
A default choice or text. If unspecified, it is :code:`y` for the type
:code:`yesno`, the first choice for :code:`choices` and empty for others types.
The default choice is selected when the user presses the :kbd:`Enter` key.
--prompt -p
@@ -406,7 +406,7 @@ def main(args: List[str]) -> Response:
except SystemExit as e:
if e.code != 0:
print(e.args[0])
input('Press enter to quit...')
input('Press Enter to quit')
raise SystemExit(e.code)
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
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 ...]'

6
kittens/diff/main.py
View File

@@ -571,8 +571,8 @@ OPTIONS = partial('''\
--context
type=int
default=-1
Number of lines of context to show between changes. Negative values
use the number set in diff.conf
Number of lines of context to show between changes. Negative values use the
number set in :file:`diff.conf`.
--config
@@ -599,7 +599,7 @@ class 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'

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

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

32
kittens/query_terminal/main.py
View File

@@ -66,7 +66,7 @@ def query(cls: Type[Query]) -> Type[Query]:
class TerminalName(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
def get_result(opts: Options) -> str:
@@ -76,7 +76,7 @@ class TerminalName(Query):
@query
class TerminalVersion(Query):
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
def get_result(opts: Options) -> str:
@@ -86,7 +86,7 @@ class TerminalVersion(Query):
@query
class AllowHyperlinks(Query):
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
def get_result(opts: Options) -> str:
@@ -154,7 +154,7 @@ class FontSize(Query):
@query
class ClipboardControl(Query):
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
def get_result(opts: Options) -> str:
@@ -200,30 +200,28 @@ querying it.
help_text = '''\
Query the terminal this kitten is run in for various
capabilities. This sends escape codes to the terminal
and based on its response prints out data about supported
capabilities. Note that this is a blocking operation, since
it has to wait for a response from the terminal. You can control
the maximum wait time via the ``--wait-for`` option.
Query the terminal this kitten is run in for various capabilities. This sends
escape codes to the terminal and based on its response prints out data about
supported capabilities. Note that this is a blocking operation, since it has to
wait for a response from the terminal. You can control the maximum wait time via
the :code:`--wait-for` option.
The output is lines of the form::
query: data
:italic:`query`: :italic:`data`
If a particular query is unsupported by the running kitty version,
the data will be blank.
If a particular query is unsupported by the running kitty version, the data will
be blank.
Note that when calling this from another program, be very
careful not to perform any I/O on the terminal device
until the kitten exits.
Note that when calling this from another program, be very careful not to perform
any I/O on the terminal device until thos kitten exits.
Available queries are:
{}
'''.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 ...]'

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:
print(styled(msg, fg='red'))
print()
print('Press any key to exit...')
print('Press any key to quit')
sys.stdout.flush()
with raw_mode():
while True:
@@ -208,7 +208,7 @@ def main(args: List[str]) -> Result:
except SystemExit as e:
if e.code != 0:
print(e.args[0])
input('Press enter to quit...')
input('Press Enter to quit')
raise SystemExit(e.code)
try:
@@ -236,7 +236,7 @@ def save_as(conn_data: SSHConnectionData, remote_path: str, cli_opts: RemoteFile
last_used_path = tempfile.gettempdir()
last_used_file = os.path.join(last_used_path, os.path.basename(remote_path))
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')
)
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:')
import traceback
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
type=choices
choices=normal,application,kitty,unchanged
The keyboard mode to use when showing keys. "normal" mode is with DECCKM reset and "application" mode is with
DECCKM set. "kitty" is the full kitty extended keyboard protocol.
The keyboard mode to use when showing keys. :code:`normal` mode is with DECCKM
reset and :code:`application` mode is with DECCKM set. :code:`kitty` is the full
kitty extended keyboard protocol.
'''.format
help_text = 'Show the codes generated by the terminal for key presses in various keyboard modes'
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':
from .kitty_mode import main as 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
The password to use to skip the transfer confirmation popup in kitty. Must match the
password set for the :opt:`file_transfer_confirmation_bypass` option in kitty.conf. Note that
leading and trailing whitespace is removed from the password. A password starting with
., / or ~ characters is assumed to be a file name to read the password from. A value
of - 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.
The password to use to skip the transfer confirmation popup in kitty. Must match
the password set for the :opt:`file_transfer_confirmation_bypass` option in
:file:`kitty.conf`. Note that leading and trailing whitespace is removed from
the password. A password starting with :code:`.`, :code:`/` or :code:`~`
characters is assumed to be a file name to read the password from. A value of
: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
type=bool-set
Before actually transferring files, show a mapping of local file names to remote file names
and ask for confirmation.
Before actually transferring files, show a mapping of local file names to remote
file names and ask for confirmation.
--transmit-deltas -x
type=bool-set
If a file on the receiving side already exists, use the rsync algorithm to update it to match
the file on the sending side, potentially saving lots of bandwidth and also automatically resuming
partial transfers. Note that this will actually degrade performance on fast links with small
files, so use with care.
If a file on the receiving side already exists, use the rsync algorithm to
update it to match the file on the sending side, potentially saving lots of
bandwidth and also automatically resuming partial transfers. Note that this will
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()
help_text = 'Input a unicode character'
help_text = 'Input a Unicode character'
usage = ''
OPTIONS = '''
--emoji-variation
@@ -554,7 +554,7 @@ type=choices
default=none
choices=none,graphic,text
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

2
kitty/shell.py
View File

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