mirror of
https://github.com/kovidgoyal/kitty
synced 2026-07-18 22:44:50 +02:00
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
@@ -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+]`
|
||||
|
||||
Reference in New Issue
Block a user