Docs: Improve the documentation for kittens
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
parent
627c79ffbb
commit
510022c3c1
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
-----------------
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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+]`
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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'):
|
||||
|
||||
@ -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 ...]'
|
||||
|
||||
|
||||
|
||||
@ -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'
|
||||
|
||||
|
||||
|
||||
@ -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.
|
||||
'''
|
||||
)
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 ...]'
|
||||
|
||||
|
||||
|
||||
@ -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))
|
||||
|
||||
@ -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')
|
||||
|
||||
@ -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()
|
||||
|
||||
@ -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.
|
||||
'''
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user