kovidgoyal/kitty
1
1
Fork 0
mirror of https://github.com/kovidgoyal/kitty.git synced 2024-11-14 01:20:31 +03:00
Code Issues Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Kovid Goyal 2022-04-29 07:11:40 +05:30
commit 443f36ebc7
No known key found for this signature in database
GPG Key ID: 06BC317B515ACE7C
37 changed files with 229 additions and 215 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/kittens/broadcast.rst
View File

@ -17,7 +17,7 @@ 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
map f1 launch --allow-remote-control kitty +kitten broadcast --match-tab state:focused
.. program:: kitty +kitten broadcast

135
docs/remote-control.rst
View File

@ -4,9 +4,12 @@ Control kitty from scripts
.. highlight:: sh
|kitty| can be controlled from scripts or the shell prompt. You can open new
windows, send arbitrary text input to any window, name windows and tabs, etc.
windows, send arbitrary text input to any window, change the title of windows
and tabs, etc.
Let's walk through a few examples of controlling |kitty|.
Tutorial
------------
@ -21,43 +24,44 @@ Now, in the new |kitty| window, enter the command::
kitty @ launch --title Output --keep-focus cat
This will open a new window, running the ``cat`` program that will appear next
to the current window.
This will open a new window, running the :program:`cat` program that will appear
next to the current window.
Let's send some text to this new window::
kitty @ send-text --match cmdline:cat Hello, World
This will make ``Hello, World`` show up in the window running the ``cat`` program.
The :option:`kitty @ send-text --match` option is very powerful, it allows selecting windows by their
titles, the command line of the program running in the window, the working
directory of the program running in the window, etc. See ``kitty @ send-text
--help`` for details.
This will make ``Hello, World`` show up in the window running the :program:`cat`
program. The :option:`kitty @ send-text --match` option is very powerful, it
allows selecting windows by their titles, the command line of the program
running in the window, the working directory of the program running in the
window, etc. See :ref:`kitty @ send-text --help <at_send-text>` for details.
More usefully, you can pipe the output of a command running in one window to
another window, for example::
ls | kitty @ send-text --match title:Output --stdin
ls | kitty @ send-text --match title:^Output --stdin
This will show the output of ls in the output window instead of the current
window. You can use this technique to, for example, show the output of running
``make`` in your editor in a different window. The possibilities are endless.
This will show the output of :program:`ls` in the output window instead of the
current window. You can use this technique to, for example, show the output of
running :program:`make` in your editor in a different window. The possibilities
are endless.
You can even have things you type show up in a different window. Run::
kitty @ send-text --match title:Output --stdin
kitty @ send-text --match title:^Output --stdin
And type some text, it will show up in the output window, instead of the current
window. Type ``Ctrl+D`` when you are ready to stop.
window. Type :kbd:`Ctrl+D` when you are ready to stop.
Now, let's open a new tab::
kitty @ launch --type=tab --tab-title "My Tab" --keep-focus bash
This will open a new tab running the bash shell with the title "My Tab".
We can change the title of the tab with::
We can change the title of the tab to "New Title" with::
kitty @ set-tab-title --match title:My New Title
kitty @ set-tab-title --match title:^My New Title
Let's change the title of the current tab::
@ -65,79 +69,83 @@ Let's change the title of the current tab::
Now lets switch to the newly opened tab::
kitty @ focus-tab --match title:New
kitty @ focus-tab --match title:^New
Similarly, to focus the previously opened output window (which will also switch
back to the old tab, automatically)::
kitty @ focus-window --match title:Output
kitty @ focus-window --match title:^Output
You can get a listing of available tabs and windows, by running::
kitty @ ls
This outputs a tree of data in JSON format. The top level of the tree is all
operating system kitty windows. Each OS window has an id and a list of tabs.
Each tab has its own id, a title and a list of windows. Each window has an id,
title, current working directory, process id (PID) and command-line of the
process running in the window. You can use this information with :option:`kitty @ focus-window --match`
to control individual windows.
:term:`OS windows <os_window>`. Each OS window has an id and a list of
:term:`tabs <tab>`. Each tab has its own id, a title and a list of :term:`kitty
windows <window>`. Each window has an id, title, current working directory,
process id (PID) and command-line of the process running in the window. You can
use this information with :option:`kitty @ focus-window --match` to control
individual windows.
As you can see, it is very easy to control |kitty| using the
``kitty @`` messaging system. This tutorial touches only the
surface of what is possible. See ``kitty @ --help`` for more details.
As you can see, it is very easy to control |kitty| using the ``kitty @``
messaging system. This tutorial touches only the surface of what is possible.
See ``kitty @ --help`` for more details.
Note that in the example's above, ``kitty @`` messaging works only when run inside a |kitty| window,
not anywhere. But, within a |kitty| window it even works over SSH. If you want to control
|kitty| from programs/scripts not running inside a |kitty| window, you have to implement a couple of
extra steps. First start |kitty| as::
Note that in the example's above, ``kitty @`` messaging works only when run
inside a |kitty| window, not anywhere. But, within a |kitty| window it even
works over SSH. If you want to control |kitty| from programs/scripts not running
inside a |kitty| window, you have to implement a couple of extra steps. First
start |kitty| as::
kitty -o allow_remote_control=yes --listen-on unix:/tmp/mykitty
The :option:`kitty --listen-on` option tells |kitty| to listen for control messages at the
specified path. See ``kitty --help`` for details. Now you can control this
instance of |kitty| using the :option:`kitty @ --to` command line argument to ``kitty @``. For example::
The :option:`kitty --listen-on` option tells |kitty| to listen for control
messages at the specified UNIX-domain socket. See ``kitty --help`` for details.
Now you can control this instance of |kitty| using the :option:`kitty @ --to`
command line argument to ``kitty @``. For example::
kitty @ --to unix:/tmp/mykitty ls
Note that if all you want to do is run a single |kitty| "daemon" and have subsequent
|kitty| invocations appear as new top-level windows, you can use the simpler :option:`kitty --single-instance`
option, see ``kitty --help`` for that.
Note that if all you want to do is run a single |kitty| "daemon" and have
subsequent |kitty| invocations appear as new top-level windows, you can use the
simpler :option:`kitty --single-instance` option, see ``kitty --help`` for that.
The builtin kitty shell
--------------------------
You can explore the |kitty| command language more easily using the builtin |kitty|
shell. Run ``kitty @`` with no arguments and you will be dropped into the |kitty|
shell with completion for |kitty| command names and options.
You can explore the |kitty| command language more easily using the builtin
|kitty| shell. Run ``kitty @`` with no arguments and you will be dropped into
the |kitty| shell with completion for |kitty| command names and options.
You can even open the |kitty| shell inside a running |kitty| using a simple
keyboard shortcut (:sc:`kitty_shell` by default).
.. note:: This has the added advantage that you don't need to use
``allow_remote_control`` to make it work.
:opt:`allow_remote_control` to make it work.
Allowing only some windows to control kitty
----------------------------------------------
If you do not want to allow all programs running in |kitty| to control it, you can selectively
enable remote control for only some |kitty| windows. Simply create a shortcut
such as::
If you do not want to allow all programs running in |kitty| to control it, you
can selectively enable remote control for only some |kitty| windows. Simply
create a shortcut such as::
map ctrl+k launch --allow-remote-control some_program
Then programs running in windows created with that shortcut can use ``kitty @``
to control kitty. Note that any program with the right level of permissions can
still write to the pipes of any other program on the same computer and
therefore can control |kitty|. It can, however, be useful to block programs
running on other computers (for example, over ssh) or as other users.
still write to the pipes of any other program on the same computer and therefore
can control |kitty|. It can, however, be useful to block programs running on
other computers (for example, over SSH) or as other users.
.. note:: You dont need ``allow_remote_control`` to make this work as it is
.. note:: You don't need :opt:`allow_remote_control` to make this work as it is
limited to only programs running in that specific window. Be careful with
what programs you run in such windows, since they can effectively control
kitty, as if you were running with ``allow_remote_control`` turned on.
kitty, as if you were running with :opt:`allow_remote_control` turned on.
.. _rc_mapping:
@ -148,15 +156,15 @@ Mapping key presses to remote control commands
If you wish to trigger a remote control command easily with just a keypress,
you can map it in :file:`kitty.conf`. For example::
map F1 remote_control set-spacing margin=30
map f1 remote_control set-spacing margin=30
Then pressing the :kbd:`F1` key will set the active window margins to 30.
The syntax for what follows :code:`remote_control` is exactly the same
Then pressing the :kbd:`F1` key will set the active window margins to
:code:`30`. The syntax for what follows :ac:`remote_control` is exactly the same
as the syntax for what follows :code:`kitty @` above.
.. note:: You do not need ``allow_remote_control`` to use these mappings,
as they are not actual remote programs, but are simply a way to resuse
the remote control infrastructure via keybings.
.. note:: You do not need :opt:`allow_remote_control` to use these mappings,
as they are not actual remote programs, but are simply a way to resuse the
remote control infrastructure via keybings.
Broadcasting what you type to all kitty windows
@ -166,17 +174,17 @@ As a simple illustration of the power of remote control, lets
have what we type sent to all open kitty windows. To do that define the
following mapping in :file:`kitty.conf`::
map F1 launch --allow-remote-control kitty +kitten broadcast
map f1 launch --allow-remote-control kitty +kitten broadcast
Now press, F1 and start typing, what you type will be sent to all windows,
Now press :kbd:`F1` and start typing, what you type will be sent to all windows,
live, as you type it.
The remote control protocol
-----------------------------------------------
If you wish to develop your own client to talk to |kitty|, you
can use the :doc:`protocol specification <rc_protocol>`.
If you wish to develop your own client to talk to |kitty|, you can use the
:doc:`remote control protocol specification <rc_protocol>`.
.. _search_syntax:
@ -184,12 +192,13 @@ can use the :doc:`protocol specification <rc_protocol>`.
Matching windows and tabs
----------------------------
Many remote control operations operate on windows or tabs. To select these,
the :code:`--match` option is often used. This allows matching using various
Many remote control operations operate on windows or tabs. To select these, the
:code:`--match` option is often used. This allows matching using various
sophisticated criteria such as title, ids, cmdlines, etc. These criteria are
expressions of the form :code:`field:query`. Where field is the field against
which to match and query is the expression to match. They can be further
combined using Boolean operators, best illustrated with some examples::
expressions of the form :code:`field:query`. Where :italic:`field` is the field
against which to match and :italic:`query` is the expression to match. They can
be further combined using Boolean operators, best illustrated with some
examples::
title:"My special window" or id:43
title:bash and env:USER=kovid

2
kittens/clipboard/main.py
View File

@ -57,7 +57,7 @@ OPTIONS = r'''
default=False
type=bool-set
Output the current contents of the clipboard to STDOUT. Note that by default
kitty will prompt you asking to allow access to the clipboard. Can be controlled
kitty will prompt for permission to access the clipboard. Can be controlled
by :opt:`clipboard_control`.

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

@ -37,8 +37,9 @@ opt('num_context_lines', '3',
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 :program:`git` or :program:`diff` and use that, if found.
will be replaced by the number of lines of context. The default special value
:code:`auto` is to search the system for either :program:`git` or
:program:`diff` and use that, if found.
'''
)

8
kittens/query_terminal/main.py
View File

@ -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 :code:`yes`, :code:`no` or :code:`ask`'
help_text: str = 'The config option :opt:`allow_hyperlinks` in :file:`kitty.conf` for allowing hyperlinks can be :code:`yes`, :code:`no` or :code:`ask`'
@staticmethod
def get_result(opts: Options) -> str:
@ -208,10 +208,10 @@ the :code:`--wait-for` option.
The output is lines of the form::
:italic:`query`: :italic:`data`
query: data
If a particular query is unsupported by the running kitty version, the data will
be blank.
If a particular :italic:`query` is unsupported by the running kitty version, the
:italic:`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 thos kitten exits.

74
kitty/rc/base.py
View File

@ -75,46 +75,50 @@ ArgsType = List[str]
MATCH_WINDOW_OPTION = '''\
--match -m
The window to match. Match specifications are of the form:
:italic:`field:regexp`. Where field can be one of:
:code:`id`, :code:`title`, :code:`pid`, :code:`cwd`, :code:`cmdline`,
:code:`num`, :code:`env`, :code:`state` and :code:`recent`.
You can use the :italic:`ls` command to get a list of windows. Expressions can
be :ref:`combined using Boolean operators <search_syntax>`. Note that for
numeric fields such as :code:`id`, :code:`pid`, :code:`recent` and :code:`num` the expression is interpreted as a number,
not a regular expression. The field :code:`num` refers to the window position in the current tab,
starting from zero and counting clockwise (this is the same as the order in which the
windows are reported by the :italic:`ls` command). The window id of the current window
is available as the KITTY_WINDOW_ID environment variable. The field :code:`recent` refers to recently
active windows in the currently active tab, with zero being the currently active window, one being the previously active
window and so on. When using the :italic:`env` field
to match on environment variables you can specify only the environment variable name or a name
and value, for example, :italic:`env:MY_ENV_VAR=2`. The field :code:`state` matches
on the state of the window. Supported states are:
The window to match. Match specifications are of the form: :italic:`field:query`.
Where :italic:`field` can be one of: :code:`id`, :code:`title`, :code:`pid`, :code:`cwd`, :code:`cmdline`, :code:`num`,
:code:`env`, :code:`state` and :code:`recent`.
:italic:`query` is the expression to match. Expressions can be either a number or a regular expression, and can be
:ref:`combined using Boolean operators <search_syntax>`.
Note that for numeric fields: :code:`id`, :code:`pid`, :code:`num` and :code:`recent`, the expression is interpreted as
a number, not a regular expression.
The field :code:`num` refers to the window position in the current tab, starting from zero and counting clockwise (this
is the same as the order in which the windows are reported by the :italic:`ls` command).
The window id of the current window is available as the :envvar:`KITTY_WINDOW_ID` environment variable.
The field :code:`recent` refers to recently active windows in the currently active tab, with zero being the currently
active window, one being the previously active window and so on.
When using the :code:`env` field to match on environment variables, you can specify only the environment variable name
or a name and value, for example, :italic:`env:MY_ENV_VAR=2`.
The field :code:`state` matches on the state of the window. Supported states are:
:code:`active`, :code:`focused`, :code:`needs_attention`, :code:`parent_active` and :code:`parent_focused`.
Active windows are windows that are the active window in their parent tab. There is only one focused window
and it is the window to which keyboard events are delivered.
Active windows are the windows that are active in their parent tab. There is only one focused window and it is the
window to which keyboard events are delivered.
Note that you can use the :ref:`kitty @ ls <at_ls>` command to get a list of windows.
'''
MATCH_TAB_OPTION = '''\
--match -m
The tab to match. Match specifications are of the form:
:italic:`field:regexp`. Where field can be one of:
:code:`id`, :code:`index`, :code:`title`, :code:`window_id`,
:code:`window_title`, :code:`pid`, :code:`cwd`, :code:`env`, :code:`cmdline` and :code:`recent`.
You can use the :italic:`ls` command to get a list of tabs. Expressions can
be :ref:`combined using Boolean operators <search_syntax>`. Note that for
numeric fields such as :code:`id`, :code:`recent`, :code:`index` or :code:`pid` the expression
is interpreted as a number, not a regular expression. When using :code:`title` or :code:`id`, first a matching tab is
looked for and if not found a matching window is looked for, and the tab
for that window is used. You can also use :code:`window_id` and :code:`window_title` to match
the tab that contains the window with the specified id or title. The :code:`index` number
is used to match the nth tab in the currently active OS window. The :code:`recent` number
matches recently active tabs in the currently active OS window, with zero being the currently
active tab, one the previously active tab and so on. The field :code:`state` matches
on the state of the tab. Supported states are:
The tab to match. Match specifications are of the form: :italic:`field:query`.
Where :italic:`field` can be one of: :code:`id`, :code:`index`, :code:`title`, :code:`window_id`, :code:`window_title`,
:code:`pid`, :code:`cwd`, :code:`cmdline` :code:`env`, :code:`state` and :code:`recent`.
:italic:`query` is the expression to match. Expressions can be either a number or a regular expression, and can be
:ref:`combined using Boolean operators <search_syntax>`.
Note that for numeric fields: :code:`id`, :code:`index`, :code:`window_id`, :code:`pid` and :code:`recent`, the
expression is interpreted as a number, not a regular expression.
When using :code:`title` or :code:`id`, first a matching tab is looked for, and if not found a matching window is looked
for, and the tab for that window is used.
You can also use :code:`window_id` and :code:`window_title` to match the tab that contains the window with the specified
id or title.
The :code:`index` number is used to match the nth tab in the currently active OS window.
The :code:`recent` number matches recently active tabs in the currently active OS window, with zero being the currently
active tab, one the previously active tab and so on.
When using the :code:`env` field to match on environment variables, you can specify only the environment variable name
or a name and value, for example, :italic:`env:MY_ENV_VAR=2`. Tabs containing any window with the specified environment
variables are matched.
The field :code:`state` matches on the state of the tab. Supported states are:
:code:`active`, :code:`focused`, :code:`needs_attention`, :code:`parent_active` and :code:`parent_focused`.
Active tabs are tabs that are the active tab in their parent OS Window. There is only one focused tab
Active tabs are the tabs that are active in their parent OS window. There is only one focused tab
and it is the tab to which keyboard events are delivered.
Note that you can use the :ref:`kitty @ ls <at_ls>` command to get a list of tabs.
'''
@ -259,7 +263,7 @@ def command_for_name(cmd_name: str) -> RemoteCommand:
try:
m = import_module(f'kitty.rc.{cmd_name}')
except ImportError:
raise KeyError(f'{cmd_name} is not a known kitty remote control command')
raise KeyError(f'Unknown kitty remote control command: {cmd_name}')
return cast(RemoteCommand, getattr(m, cmd_name))

9
kitty/rc/close_tab.py
View File

@ -20,17 +20,18 @@ class CloseTab(RemoteCommand):
self: Boolean indicating whether to close the tab of the window the command is run in
'''
short_desc = 'Close the specified tab(s)'
short_desc = 'Close the specified tabs'
desc = '''\
Close an arbitrary set of tabs. The :code:`--match` option can be used to specify complex sets of tabs to close. For example, to close
all non-focused tabs in the currently focused OS window, use:
Close an arbitrary set of tabs. The :code:`--match` option can be used to
specify complex sets of tabs to close. For example, to close all non-focused
tabs in the currently focused OS window, use:
kitty @ close-tab --match "not state:focused and state:parent_focused"
'''
options_spec = MATCH_TAB_OPTION + '''\n
--self
type=bool-set
If specified close the tab of the window this command is run in, rather than the active tab.
Close the tab of the window this command is run in, rather than the active tab.
'''
argspec = ''

4
kitty/rc/close_window.py
View File

@ -19,11 +19,11 @@ class CloseWindow(RemoteCommand):
self: Boolean indicating whether to close the window the command is run in
'''
short_desc = 'Close the specified window(s)'
short_desc = 'Close the specified windows'
options_spec = MATCH_WINDOW_OPTION + '''\n
--self
type=bool-set
If specified close the window this command is run in, rather than the active window.
Close the window this command is run in, rather than the active window.
'''
argspec = ''

2
kitty/rc/create_marker.py
View File

@ -30,7 +30,7 @@ class CreateMarker(RemoteCommand):
options_spec = MATCH_WINDOW_OPTION + '''\n
--self
type=bool-set
If specified apply marker to the window this command is run in, rather than the active window.
Apply marker to the window this command is run in, rather than the active window.
'''
argspec = 'MARKER SPECIFICATION'

10
kitty/rc/detach_tab.py
View File

@ -16,19 +16,19 @@ class DetachTab(RemoteCommand):
'''
match: Which tab to detach
target_tab: Which OS Window that containing the target tab to move the detached tab to
target_tab: Which tab to move the detached tab to the OS window it is run in
self: Boolean indicating whether to detach the tab the command is run in
'''
short_desc = 'Detach a tab and place it in a different/new OS Window'
short_desc = 'Detach the specified tabs and place them in a different/new OS window'
desc = (
'Detach the specified tab and either move it into a new OS window'
' or add it to the OS Window containing the tab specified by :option:`kitty @ detach-tab --target-tab`'
'Detach the specified tabs and either move them into a new OS window'
' or add them to the OS window containing the tab specified by :option:`kitty @ detach-tab --target-tab`'
)
options_spec = MATCH_TAB_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--target-tab -t') + '''\n
--self
type=bool-set
If specified detach the tab this command is run in, rather than the active tab.
Detach the tab this command is run in, rather than the active tab.
'''
argspec = ''

10
kitty/rc/detach_window.py
View File

@ -21,18 +21,18 @@ class DetachWindow(RemoteCommand):
self: Boolean indicating whether to detach the window the command is run in
'''
short_desc = 'Detach a window and place it in a different/new tab'
short_desc = 'Detach the specified windows and place them in a different/new tab'
desc = (
'Detach the specified window and either move it into a new tab, a new OS window'
' or add it to the specified tab. Use the special value :code:`new` for :option:`kitty @ detach-window --target-tab`'
' to move to a new tab. If no target tab is specified the window is moved to a new OS window.'
'Detach the specified windows and either move them into a new tab, a new OS window'
' or add them to the specified tab. Use the special value :code:`new` for :option:`kitty @ detach-window --target-tab`'
' to move to a new tab. If no target tab is specified the windows are moved to a new OS window.'
)
options_spec = MATCH_WINDOW_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--target-tab -t') + '''Use the special value :code:`new` to move to a new tab.
--self
type=bool-set
If specified detach the window this command is run in, rather than the active window.
Detach the window this command is run in, rather than the active window.
'''
argspec = ''

4
kitty/rc/disable_ligatures.py
View File

@ -24,8 +24,8 @@ class DisableLigatures(RemoteCommand):
short_desc = 'Control ligature rendering'
desc = (
'Control ligature rendering for the specified windows/tabs (defaults to active window). The STRATEGY'
' can be one of: never, always, cursor'
'Control ligature rendering for the specified windows/tabs (defaults to active window). The :italic:`STRATEGY`'
' can be one of: :code:`never`, :code:`always`, :code:`cursor`.'
)
options_spec = '''\
--all -a

6
kitty/rc/env.py
View File

@ -12,13 +12,13 @@ from .base import (
class Env(RemoteCommand):
'''
env+: dictionary of environment variables to values. Empty values cause the variable to be deleted.
env+: Dictionary of environment variables to values. Empty values cause the variable to be removed.
'''
short_desc = 'Change environment variables seen by future children'
desc = (
'Change the environment variables seen by processing in newly launched windows.'
' Similar to the :opt:`env` option in kitty.conf, but affects running kitty instances.'
'Change the environment variables that will be seen in newly launched windows.'
' Similar to the :opt:`env` option in :file:`kitty.conf`, but affects running kitty instances.'
' Empty values cause the environment variable to be removed.'
)
argspec = 'env_var1=val env_var2=val ...'

2
kitty/rc/get_colors.py
View File

@ -26,7 +26,7 @@ class GetColors(RemoteCommand):
short_desc = 'Get terminal colors'
desc = (
'Get the terminal colors for the specified window (defaults to active window).'
' Colors will be output to stdout in the same syntax as used for kitty.conf'
' Colors will be output to stdout in the same syntax as used for :file:`kitty.conf`.'
)
options_spec = '''\
--configured -c

18
kitty/rc/get_text.py
View File

@ -23,7 +23,7 @@ class GetText(RemoteCommand):
cursor: Boolean, if True send cursor position/style as ANSI codes
wrap_markers: Boolean, if True add wrap markers to output
clear_selection: Boolean, if True clear the selection in the matched window
self: Boolean, if True use window command was run in
self: Boolean, if True use window the command was run in
'''
short_desc = 'Get text from the specified window'
@ -42,8 +42,8 @@ requires :ref:`shell_integration` to be enabled.
--ansi
type=bool-set
By default, only plain text is returned. If you specify this flag, the text will
include the formatting escape codes for colors/bold/italic/etc.
By default, only plain text is returned. With this flag, the text will
include the ANSI formatting escape codes for colors, bold, italic, etc.
--add-cursor
@ -57,13 +57,13 @@ Add carriage returns at every line wrap location (where long lines are wrapped a
screen edges).
--clear-selection
Clear the selection in the matched window, if any.
--self
type=bool-set
If specified get text from the window this command is run in, rather than the active window.
--clear-selection
Clear the selection in the matched window, if any
Get text from the window this command is run in, rather than the active window.
'''
argspec = ''
@ -72,10 +72,10 @@ Clear the selection in the matched window, if any
'match': opts.match,
'extent': opts.extent,
'ansi': opts.ansi,
'self': opts.self,
'cursor': opts.add_cursor,
'wrap_markers': opts.add_wrap_markers,
'clear_selection': opts.clear_selection,
'self': opts.self,
}
def response_from_kitty(self, boss: Boss, window: Optional[Window], payload_get: PayloadGetType) -> ResponseType:

4
kitty/rc/goto_layout.py
View File

@ -26,8 +26,8 @@ class GotoLayout(RemoteCommand):
short_desc = 'Set the window layout'
desc = (
'Set the window layout in the specified tab (or the active tab if not specified).'
' You can use special match value :italic:`all` to set the layout in all tabs.'
'Set the window layout in the specified tabs (or the active tab if not specified).'
' You can use special match value :code:`all` to set the layout in all tabs.'
)
options_spec = MATCH_TAB_OPTION
argspec = 'LAYOUT_NAME'

8
kitty/rc/kitten.py
View File

@ -22,11 +22,11 @@ class Kitten(RemoteCommand):
short_desc = 'Run a kitten'
desc = (
'Run a kitten over the specified window (active window by default).'
'Run a kitten over the specified windows (active window by default).'
' The :italic:`kitten_name` can be either the name of a builtin kitten'
' or the path to a python file containing a custom kitten. If a relative path'
' is used it is searched for in the kitty config directory. If the kitten is a'
' no_ui kitten and its handle response method returns a string or boolean, this'
' or the path to a Python file containing a custom kitten. If a relative path'
' is used it is searched for in the :ref:`kitty config directory <confloc>`. If the kitten is a'
' :italic:`no_ui` kitten and its handle response method returns a string or boolean, this'
' is printed out to stdout.'
)
options_spec = MATCH_WINDOW_OPTION

2
kitty/rc/last_used_layout.py
View File

@ -21,7 +21,7 @@ class LastUsedLayout(RemoteCommand):
short_desc = 'Switch to the last used layout'
desc = (
'Switch to the last used window layout in the specified tab (or the active tab if not specified).'
'Switch to the last used window layout in the specified tabs (or the active tab if not specified).'
)
options_spec = '''\
--all -a

4
kitty/rc/ls.py
View File

@ -17,7 +17,7 @@ if TYPE_CHECKING:
class LS(RemoteCommand):
'''
all_env_vars: Whether to send all environment variables for ever window rather than just differing ones
all_env_vars: Whether to send all environment variables for every window rather than just differing ones
'''
short_desc = 'List all tabs/windows'
@ -33,7 +33,7 @@ class LS(RemoteCommand):
options_spec = '''\
--all-env-vars
type=bool-set
Show all environment variables in output not just differing ones.
Show all environment variables in output, not just differing ones.
'''
argspec = ''

6
kitty/rc/new_window.py
View File

@ -50,7 +50,7 @@ the working directory for the kitty process you are talking to is.
--keep-focus --dont-take-focus
type=bool-set
Keep the current window focused instead of switching to the newly opened window
Keep the current window focused instead of switching to the newly opened window.
--window-type
@ -61,11 +61,11 @@ What kind of window to open. A kitty window or a top-level OS window.
--new-tab
type=bool-set
Open a new tab
Open a new tab.
--tab-title
When using :option:`kitty @ new-window --new-tab` set the title of the tab.
Set the title of the tab, when open a new tab.
--no-response

2
kitty/rc/remove_marker.py
View File

@ -24,7 +24,7 @@ class RemoveMarker(RemoteCommand):
options_spec = MATCH_WINDOW_OPTION + '''\n
--self
type=bool-set
If specified apply marker to the window this command is run in, rather than the active window.
Apply marker to the window this command is run in, rather than the active window.
'''
argspec = ''

8
kitty/rc/resize_os_window.py
View File

@ -23,9 +23,9 @@ class ResizeOSWindow(RemoteCommand):
height: Integer indicating desired window height
'''
short_desc = 'Resize the specified OS Window'
short_desc = 'Resize the specified OS Windows'
desc = (
'Resize the specified OS Window.'
'Resize the specified OS Windows.'
' Note that some window managers/environments do not allow applications to resize'
' their windows, for example, tiling window managers.'
)
@ -39,7 +39,7 @@ The action to perform.
--unit
default=cells
choices=cells,pixels
The unit in which to interpret specified sizes
The unit in which to interpret specified sizes.
--width
@ -62,7 +62,7 @@ instead of absolute sizes.
--self
type=bool-set
If specified resize the window this command is run in, rather than the active window.
Resize the window this command is run in, rather than the active window.
--no-response

12
kitty/rc/resize_window.py
View File

@ -20,9 +20,9 @@ class ResizeWindow(RemoteCommand):
axis: One of :code:`horizontal, vertical` or :code:`reset`
'''
short_desc = 'Resize the specified window'
short_desc = 'Resize the specified windows'
desc = (
'Resize the specified window in the current layout.'
'Resize the specified windows in the current layout.'
' Note that not all layouts can resize all windows in all directions.'
)
options_spec = MATCH_WINDOW_OPTION + '''\n
@ -36,15 +36,15 @@ The number of cells to change the size by, can be negative to decrease the size.
type=choices
choices=horizontal,vertical,reset
default=horizontal
The axis along which to resize. If :italic:`horizontal`,
The axis along which to resize. If :code:`horizontal`,
it will make the window wider or narrower by the specified increment.
If :italic:`vertical`, it will make the window taller or shorter by the specified increment.
The special value :italic:`reset` will reset the layout to its default configuration.
If :code:`vertical`, it will make the window taller or shorter by the specified increment.
The special value :code:`reset` will reset the layout to its default configuration.
--self
type=bool-set
If specified resize the window this command is run in, rather than the active window.
Resize the window this command is run in, rather than the active window.
'''
argspec = ''
string_return_is_error = True

10
kitty/rc/scroll_window.py
View File

@ -23,12 +23,12 @@ class ScrollWindow(RemoteCommand):
match: The window to scroll
'''
short_desc = 'Scroll the specified window'
short_desc = 'Scroll the specified windows'
desc = (
'Scroll the specified window, if no window is specified, scroll the window this command is run inside.'
' SCROLL_AMOUNT can be either the keywords :code:`start` or :code:`end` or an'
' argument of the form <number>[unit][+-]. For example, 30 will scroll down 30 lines and 2p- will'
' scroll up 2 pages. 3u will *unscroll* by 3 lines, which means that 3 lines will move from the'
'Scroll the specified windows, if no window is specified, scroll the window this command is run inside.'
' :italic:`SCROLL_AMOUNT` can be either the keywords :code:`start` or :code:`end` or an'
' argument of the form <number>[unit][+-]. For example, :code:`30` will scroll down 30 lines and :code:`2p-`'
' will scroll up 2 pages. :code:`3u` will *unscroll* by 3 lines, which means that 3 lines will move from the'
' scrollback buffer onto the top of the screen.'
)
argspec = 'SCROLL_AMOUNT'

10
kitty/rc/select_window.py
View File

@ -39,23 +39,23 @@ The time in seconds to wait for the user to select a window.
--self
type=bool-set
If specified the tab containing the window this command is run in is used
Select window from the tab containing the window this command is run in,
instead of the active tab.
--title
A title that will be displayed to the user to describe what this selection is for
A title that will be displayed to the user to describe what this selection is for.
--exclude-active
type=bool-set
Exclude the currently active window from the list of windows to pick
Exclude the currently active window from the list of windows to pick.
--reactivate-prev-tab
type=bool-set
When the selection is finished, the tab in the same os window that was activated
before the selection will be reactivated. The last activated os window will also
When the selection is finished, the tab in the same OS window that was activated
before the selection will be reactivated. The last activated OS window will also
be refocused.
'''
is_asynchronous = True

6
kitty/rc/send_text.py
View File

@ -74,8 +74,8 @@ class SendText(RemoteCommand):
short_desc = 'Send arbitrary text to specified windows'
desc = (
'Send arbitrary text to specified windows. The text follows Python'
' escaping rules. So you can use escapes like :italic:`\\x1b` to send control codes'
' and :italic:`\\u21fa` to send unicode characters. If you use the :option:`kitty @ send-text --match` option'
' escaping rules. So you can use escapes like :code:`\\x1b` to send control codes'
' and :code:`\\u21fa` to send unicode characters. If you use the :option:`kitty @ send-text --match` option'
' the text will be sent to all matched windows. By default, text is sent to'
' only the currently active window.'
)
@ -88,7 +88,7 @@ Match all windows.
--stdin
type=bool-set
Read the text to be sent from :italic:`stdin`. Note that in this case the text is sent as is,
not interpreted for escapes. If stdin is a terminal, you can press Ctrl-D to end reading.
not interpreted for escapes. If stdin is a terminal, you can press :kbd:`Ctrl-D` to end reading.
--from-file

6
kitty/rc/set_background_image.py
View File

@ -29,10 +29,10 @@ class SetBackgroundImage(RemoteCommand):
configured: Boolean indicating if the configured value should be changed
'''
short_desc = 'Set the background_image'
short_desc = 'Set the background image'
desc = (
'Set the background image for the specified OS windows. You must specify the path to a PNG image that'
' will be used as the background. If you specify the special value "none" then any existing image will'
' will be used as the background. If you specify the special value :code:`none` then any existing image will'
' be removed.'
)
options_spec = '''\
@ -50,7 +50,7 @@ Change the configured background image which is used for new OS windows.
--layout
type=choices
choices=tiled,scaled,mirror-tiled,clamped,configured
How the image should be displayed. The value of configured will use the configured value.
How the image should be displayed. A value of :code:`configured` will use the configured value.
--no-response

8
kitty/rc/set_background_opacity.py
View File

@ -23,17 +23,17 @@ class SetBackgroundOpacity(RemoteCommand):
all: Boolean indicating operate on all windows
'''
short_desc = 'Set the background_opacity'
short_desc = 'Set the background opacity'
desc = (
'Set the background opacity for the specified windows. This will only work if you have turned on'
' :opt:`dynamic_background_opacity` in :file:`kitty.conf`. The background opacity affects all kitty windows in a'
' single os_window. For example: kitty @ set-background-opacity 0.5'
' single OS window. For example: :code:`kitty @ set-background-opacity 0.5`'
)
options_spec = '''\
--all -a
type=bool-set
By default, colors are only changed for the currently active window. This option will
cause colors to be changed in all windows.
By default, background opacity are only changed for the currently active window. This option will
cause background opacity to be changed in all windows.
''' + '\n\n' + MATCH_WINDOW_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--match-tab -t')
argspec = 'OPACITY'

4
kitty/rc/set_colors.py
View File

@ -67,8 +67,8 @@ class SetColors(RemoteCommand):
desc = (
'Set the terminal colors for the specified windows/tabs (defaults to active window).'
' You can either specify the path to a conf file'
' (in the same format as kitty.conf) to read the colors from or you can specify individual colors,'
' for example: kitty @ set-colors foreground=red background=white'
' (in the same format as :file:`kitty.conf`) to read the colors from or you can specify individual colors,'
' for example: :code:`kitty @ set-colors foreground=red background=white`'
)
options_spec = '''\
--all -a

8
kitty/rc/set_enabled_layouts.py
View File

@ -28,11 +28,11 @@ class SetEnabledLayouts(RemoteCommand):
configured: Boolean indicating whether to change the configured value
'''
short_desc = 'Set the enabled layouts in a tab'
short_desc = 'Set the enabled layouts in tabs'
desc = (
'Set the enabled layouts in the specified tab (or the active tab if not specified).'
' You can use special match value :italic:`all` to set the layout in all tabs. If the'
' current layout of the tab is not included in the enabled layouts its layout is changed'
'Set the enabled layouts in the specified tabs (or the active tab if not specified).'
' You can use special match value :code:`all` to set the enabled layouts in all tabs. If the'
' current layout of the tab is not included in the enabled layouts, its layout is changed'
' to the first enabled layout.'
)
options_spec = MATCH_TAB_OPTION + '''\n\n

2
kitty/rc/set_font_size.py
View File

@ -25,7 +25,7 @@ class SetFontSize(RemoteCommand):
' that in kitty all sub-windows in the same OS window'
' must have the same font size. A value of zero'
' resets the font size to default. Prefixing the value'
' with a + or - increments the font size by the specified'
' with a :code:`+` or :code:`-` increments the font size by the specified'
' amount.'
)
argspec = 'FONT_SIZE'

20
kitty/rc/set_spacing.py
View File

@ -41,30 +41,30 @@ class SetSpacing(RemoteCommand):
'''
settings+: An object mapping margins/paddings using canonical form {'margin-top': 50, 'padding-left': null} etc
match_window: Window to change colors in
match_tab: Tab to change colors in
all: Boolean indicating change colors everywhere or not
configured: Boolean indicating whether to change the configured colors. Must be True if reset is True
match_window: Window to change paddings and margins in
match_tab: Tab to change paddings and margins in
all: Boolean indicating change paddings and margins everywhere or not
configured: Boolean indicating whether to change the configured paddings and margins. Must be True if reset is True
'''
short_desc = 'Set window padding and margins'
short_desc = 'Set window paddings and margins'
desc = (
'Set the padding and margins for the specified windows (defaults to active window).'
' For example: margin=20 or padding-left=10 or margin-h=30. The shorthand form sets'
'Set the paddings and margins for the specified windows (defaults to active window).'
' For example: :code:`margin=20` or :code:`padding-left=10` or :code:`margin-h=30`. The shorthand form sets'
' all values, the :code:`*-h` and :code:`*-v` variants set horizontal and vertical values.'
' The special value "default" resets to using the default value.'
' The special value :code:`default` resets to using the default value.'
' If you specify a tab rather than a window, all windows in that tab are affected.'
)
options_spec = '''\
--all -a
type=bool-set
By default, settings are only changed for the currently active window. This option will
cause colors to be changed in all windows.
cause paddings and margins to be changed in all windows.
--configured -c
type=bool-set
Also change the configured padding and margins (i.e. the settings kitty will use for new
Also change the configured paddings and margins (i.e. the settings kitty will use for new
windows).
''' + '\n\n' + MATCH_WINDOW_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--match-tab -t')
argspec = 'MARGIN_OR_PADDING ...'

4
kitty/rc/set_tab_color.py
View File

@ -43,7 +43,7 @@ class SetTabColor(RemoteCommand):
self: Boolean indicating whether to use the tab of the window the command is run in
'''
short_desc = 'Change the color of the specified tab(s) in the tab bar'
short_desc = 'Change the color of the specified tabs in the tab bar'
desc = f'''
{short_desc}
@ -55,7 +55,7 @@ the keyword NONE to revert to using the default colors.
options_spec = MATCH_TAB_OPTION + '''\n
--self
type=bool-set
If specified close the tab this command is run in, rather than the active tab.
Close the tab this command is run in, rather than the active tab.
'''
argspec = 'COLORS'

2
kitty/rc/set_tab_title.py
View File

@ -22,7 +22,7 @@ class SetTabTitle(RemoteCommand):
short_desc = 'Set the tab title'
desc = (
'Set the title for the specified tab(s). If you use the :option:`kitty @ set-tab-title --match` option'
'Set the title for the specified tabs. If you use the :option:`kitty @ set-tab-title --match` option'
' the title will be set for all matched tabs. By default, only the tab'
' in which the command is run is affected. If you do not specify a title, the'
' title of the currently active window in the tab is used.'

8
kitty/rc/set_window_logo.py
View File

@ -22,9 +22,9 @@ if TYPE_CHECKING:
class SetWindowLogo(RemoteCommand):
'''
data+: Chunk of at most 512 bytes of PNG data, base64 encoded. Must send an empty chunk to indicate end of image. \
Or the special value - to indicate image must be removed.
Or the special value :code:`-` to indicate image must be removed.
position: The logo position as a string, empty string means default
alpha: The logo alpha between 0 and 1. -1 means use default
alpha: The logo alpha between :code:`0` and :code:`1`. :code:`-1` means use default
match: Which window to change the logo in
self: Boolean indicating whether to act on the window the command is run in
'''
@ -32,14 +32,14 @@ class SetWindowLogo(RemoteCommand):
short_desc = 'Set the window logo'
desc = (
'Set the logo image for the specified windows. You must specify the path to a PNG image that'
' will be used as the logo. If you specify the special value "none" then any existing logo will'
' will be used as the logo. If you specify the special value :code:`none` then any existing logo will'
' be removed.'
)
options_spec = MATCH_WINDOW_OPTION + '''\n
--self
type=bool-set
If specified act on the window this command is run in, rather than the active window.
Act on the window this command is run in, rather than the active window.
--position

7
kitty/rc/set_window_title.py
View File

@ -22,7 +22,7 @@ class SetWindowTitle(RemoteCommand):
short_desc = 'Set the window title'
desc = (
'Set the title for the specified window(s). If you use the :option:`kitty @ set-window-title --match` option'
'Set the title for the specified windows. If you use the :option:`kitty @ set-window-title --match` option'
' the title will be set for all matched windows. By default, only the window'
' in which the command is run is affected. If you do not specify a title, the'
' last title set by the child process running in the window will be used.'
@ -30,9 +30,8 @@ class SetWindowTitle(RemoteCommand):
options_spec = '''\
--temporary
type=bool-set
By default, if you use :italic:`set-window-title` the title will be permanently changed
and programs running in the window will not be able to change it again. If you
want to allow other programs to change it afterwards, use this option.
By default, the title will be permanently changed and programs running in the window will not be able to change it
again. If you want to allow other programs to change it afterwards, use this option.
''' + '\n\n' + MATCH_WINDOW_OPTION
argspec = '[TITLE ...]'

12
kitty/rc/signal_child.py
View File

@ -15,18 +15,18 @@ if TYPE_CHECKING:
class SignalChild(RemoteCommand):
'''
signals: The signals, a list of names, such as SIGTERM, SIGKILL, SIGUSR1, etc.
match: Which windows to change the title in
signals: The signals, a list of names, such as :code:`SIGTERM`, :code:`SIGKILL`, :code:`SIGUSR1`, etc.
match: Which windows to send the signals to
'''
short_desc = 'Send a signal to the foreground process in the specified window'
short_desc = 'Send a signal to the foreground process in the specified windows'
desc = (
'Send one or more signals to the foreground process in the specified window(s).'
'Send one or more signals to the foreground process in the specified windows.'
' If you use the :option:`kitty @ signal-child --match` option'
' the signal will be sent for all matched windows. By default, only the active'
' window is affected. If you do not specify any signals, :code:`SIGINT` is sent by default.'
' You can also map this to a keystroke in kitty.conf, for example::\n\n'
' map F1 signal_child SIGTERM'
' You can also map this to a shortcut in :file:`kitty.conf`, for example::\n\n'
' map f1 signal_child SIGTERM'
)
options_spec = '''\
''' + '\n\n' + MATCH_WINDOW_OPTION