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

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

Browse Source
This commit is contained in:
Kovid Goyal 2022-04-24 15:36:35 +05:30
commit 8239cb1b5a
No known key found for this signature in database
GPG Key ID: 06BC317B515ACE7C
6 changed files with 817 additions and 663 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
docs/glossary.rst
View File

@ -45,6 +45,7 @@ Environment variables
------------------------
Variables that influence kitty behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. envvar:: KITTY_CONFIG_DIRECTORY
@ -68,7 +69,6 @@ Variables that influence kitty behavior
The terminal editor (such as ``vi`` or ``nano``) kitty uses, when, for
instance, opening :file:`kitty.conf` in response to :sc:`edit_config_file`.
.. envvar:: EDITOR
Same as :envvar:`VISUAL`. Used if :envvar:`VISUAL` is not set.
@ -84,13 +84,24 @@ Variables that influence kitty behavior
is possible for the autodiscovery to fail; the default Wayland XKB mappings
are used in this case. See :pull:`3943` for details.
.. envvar:: KITTY_CLONE_SOURCE_CODE
Set this to some shell code that will be executed in the cloned window with
:code:`eval` when :ref:`clone-in-kitty <clone_shell>` is used.
.. envvar:: KITTY_CLONE_SOURCE_PATH
Set this to the path of a file that will be sourced in the cloned window when
:ref:`clone-in-kitty <clone_shell>` is used.
Variables that kitty sets when running child programs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. envvar:: LANG
This is set only on macOS, and only if the country and language from the
macOS user settings form a valid locale.
This is only set on macOS. If the country and language from the macOS user
settings form an invalid locale, it will be set to :code:`en_US.UTF-8`.
.. envvar:: KITTY_WINDOW_ID
@ -137,7 +148,7 @@ Variables that kitty sets when running child programs
Set when the :doc:`remote control <remote-control>` facility is enabled and
the a socket is used for control via :option:`kitty --listen-on` or :opt:`listen_on`.
Contains the path to the socket. Avoids needs to use :option:`kitty @ --to` when
Contains the path to the socket. Avoid the need to use :option:`kitty @ --to` when
issuing remote control commands.
@ -158,7 +169,7 @@ Variables that kitty sets when running child programs
.. envvar:: KITTY_COMMON_OPTS
Set with the values of some common kitty options when running
kittens, so kittens can use them without needing to load kitty.conf.
kittens, so kittens can use them without needing to load :file:`kitty.conf`.
.. envvar:: KITTY_SHELL_INTEGRATION

29
docs/shell-integration.rst
View File

@ -223,7 +223,7 @@ Clone the current shell into a new window
-----------------------------------------------
You can clone the current shell into a new kitty window by simply running the
:code:`clone-in-kitty` command, for example:
:command:`clone-in-kitty` command, for example:
.. code-block:: sh
@ -235,24 +235,27 @@ This will open a new window running a new shell instance but with all
environment variables and the current working directory copied. This even
works over SSH when using :doc:`kittens/ssh`.
The :file:`clone-in-kitty` command takes almost all the same arguments as the
The :command:`clone-in-kitty` command takes almost all the same arguments as the
:doc:`launch <launch>` command, so you can open a new tab instead or a new OS
window, etc. Arguments of launch that can cause code execution or that don't
make sense when cloning are ignored. Most prominently, the following options
are ignored: :option:`launch --allow-remote-control`, :option:`launch
--copy-cmdline`, :option:`launch --copy-env`, :option:`launch --stdin-source`,
:option:`launch --marker` and :option:`launch --watcher`.
make sense when cloning are ignored. Most prominently, the following options are
ignored: :option:`--allow-remote-control <launch --allow-remote-control>`,
:option:`--copy-cmdline <launch --copy-cmdline>`, :option:`--copy-env <launch
--copy-env>`, :option:`--stdin-source <launch --stdin-source>`,
:option:`--marker <launch --marker>` and :option:`--watcher <launch --watcher>`.
:file:`clone-in-kitty` can be configured to source arbitrary code in the
:command:`clone-in-kitty` can be configured to source arbitrary code in the
cloned window using environment variables. It will automatically clone virtual
environments created by the python venv module or conda. In addition, setting the
env var :file:`KITTY_CLONE_SOURCE_PATH` to the path of a file will cause
that file to be sourced in the cloned window. Similarly, setting
:file:`KITTY_CLONE_SOURCE_CODE` to some shell code will cause that code to be
run in the cloned window with :code:`eval`. This can be controlled by
environments created by the :link:`Python venv module
<https://docs.python.org/3/library/venv.html>` or :link:`Conda
<https://conda.io/>`. In addition, setting the
env var :envvar:`KITTY_CLONE_SOURCE_CODE` to some shell code will cause that
code to be run in the cloned window with :code:`eval`. Similarly, setting
:envvar:`KITTY_CLONE_SOURCE_PATH` to the path of a file will cause that file to
be sourced in the cloned window. This can be controlled by
:opt:`clone_source_strategies`.
:file:`clone-in-kitty` works by asking the shell to serialize its internal
:command:`clone-in-kitty` works by asking the shell to serialize its internal
state (mainly CWD and env vars) and this state is transmitted to kitty and
restored by the shell integration scripts in the cloned window.

92
kittens/hints/main.py
View File

@ -525,10 +525,10 @@ OPTIONS = r'''
--program
type=list
What program to use to open matched text. Defaults to the default open program
for the operating system. Use a value of :file:`-` to paste the match into the
terminal window instead. A value of :file:`@` will copy the match to the
clipboard. A value of :file:`*` will copy the match to the primary selection
(on systems that support primary selections). A value of :file:`default` will
for the operating system. Use a value of :code:`-` to paste the match into the
terminal window instead. A value of :code:`@` will copy the match to the
clipboard. A value of :code:`*` will copy the match to the primary selection
(on systems that support primary selections). A value of :code:`default` will
run the default open program. Can be specified multiple times to run multiple
programs.
@ -538,22 +538,22 @@ default=url
choices=url,regex,path,line,hash,word,linenum,hyperlink,ip
The type of text to search for. A value of :code:`linenum` is special, it looks
for error messages using the pattern specified with :option:`--regex`, which
must have the named groups, :code:`path` and :code:`line`. If not specified,
must have the named groups: :code:`path` and :code:`line`. If not specified,
will look for :code:`path:line`. The :option:`--linenum-action` option
controls where to display the selected error message, other options are ignored.
--regex
default={default_regex}
The regular expression to use when :option:`kitty +kitten hints --type`=regex.
The regular expression is in python syntax. If you specify a numbered group in
the regular expression only the group will be matched. This allow you to match
text ignoring a prefix/suffix, as needed. The default expression matches lines.
To match text over multiple lines you should prefix the regular expression with
The regular expression to use when option :option:`--type` is set to
:code:`regex`, in python syntax. If you specify a numbered group in the regular
expression, only the group will be matched. This allow you to match text
ignoring a prefix/suffix, as needed. The default expression matches lines. To
match text over multiple lines, you should prefix the regular expression with
:code:`(?ms)`, which turns on MULTILINE and DOTALL modes for the regex engine.
If you specify named groups and a :option:`kitty +kitten hints --program` then
the program will be passed arguments corresponding to each named group of
the form key=value.
If you specify named groups and a :option:`--program`, then the program will be
passed arguments corresponding to each named group of the form
:code:`key=value`.
--linenum-action
@ -565,22 +565,22 @@ window, :code:`window` a new kitty window, :code:`tab` a new tab,
:code:`os_window` a new OS window and :code:`background` run in the background.
The actual action is whatever arguments are provided to the kitten, for
example:
:code:`kitty + kitten hints --type=linenum --linenum-action=tab vim +{line} {path}`
:code:`kitty +kitten hints --type=linenum --linenum-action=tab vim +{line} {path}`
will open the matched path at the matched line number in vim in
a new kitty tab. Note that only when using :code:`self` are the special values for
:option:`kitty +kitten hints --program` to copy/paste the text respected.
a new kitty tab. Note that in order to use :option:`--program` to copy or paste
text, you need to use the special value :code:`self`.
--url-prefixes
default=default
Comma separated list of recognized URL prefixes. Defaults, to
the list of prefixes defined in kitty.conf.
Comma separated list of recognized URL prefixes. Defaults to the list of
prefixes defined by the :opt:`url_prefixes` option in :file:`kitty.conf`.
--word-characters
Characters to consider as part of a word. In addition, all characters marked as
alphanumeric in the unicode database will be considered as word characters.
Defaults to the select_by_word_characters setting from kitty.conf.
alphanumeric in the Unicode database will be considered as word characters.
Defaults to the :opt:`select_by_word_characters` option from :file:`kitty.conf`.
--minimum-match-length
@ -591,26 +591,26 @@ The minimum number of characters to consider a match.
--multiple
type=bool-set
Select multiple matches and perform the action on all of them together at the end.
In this mode, press :kbd:`Esc` to finish selecting.
Select multiple matches and perform the action on all of them together at the
end. In this mode, press :kbd:`Esc` to finish selecting.
--multiple-joiner
default=auto
String to use to join multiple selections when copying to the clipboard or
inserting into the terminal. The special strings: "space", "newline", "empty",
"json" and "auto" are interpreted as a space character, a newline an empty
joiner, a JSON serialized list and an automatic choice, based on the type of
text being selected. In addition, integers are interpreted as zero-based
indices into the list of selections. You can use 0 for the first selection and
-1 for the last.
String for joining multiple selections when copying to the clipboard or
inserting into the terminal. The special values are: :code:`space` - a space
character, :code:`newline` - a newline, :code:`empty` - an empty joiner,
:code:`json` - a JSON serialized list, :code:`auto` - an automatic choice, based
on the type of text being selected. In addition, integers are interpreted as
zero-based indices into the list of selections. You can use :code:`0` for the
first selection and :code:`-1` for the last.
--add-trailing-space
default=auto
choices=auto,always,never
Add trailing space after matched text. Defaults to auto, which adds the space
when used together with :option:`--multiple`.
Add trailing space after matched text. Defaults to :code:`auto`, which adds the
space when used together with :option:`--multiple`.
--hints-offset
@ -621,45 +621,47 @@ greater than or equal to zero are respected.
--alphabet
The list of characters to use for hints. The default is to use numbers and lowercase
English alphabets. Specify your preference as a string of characters. Note that
unless you specify the hints offset as zero the first match will be highlighted with
the second character you specify.
The list of characters to use for hints. The default is to use numbers and
lowercase English alphabets. Specify your preference as a string of characters.
Note that you need to specify the :option:`--hints-offset` as zero to use the
first character to highlight the first match, otherwise it will start with the
second character by default.
--ascending
type=bool-set
Have the hints increase from top to bottom instead of decreasing from top to bottom.
Make the hints increase from top to bottom, instead of decreasing from top to
bottom.
--hints-foreground-color
default=black
type=str
The foreground color for hints
The foreground color for hints.
--hints-background-color
default=green
type=str
The background color for hints
The background color for hints.
--hints-text-color
default=gray
type=str
The foreground color for text pointed to by the hints
The foreground color for text pointed to by the hints.
--customize-processing
Name of a python file in the kitty config directory which will be imported to provide
custom implementations for pattern finding and performing actions
on selected matches. See {hints_url}
for details. You can also specify absolute paths to load the script from elsewhere.
Name of a python file in the kitty config directory which will be imported to
provide custom implementations for pattern finding and performing actions
on selected matches. You can also specify absolute paths to load the script from
elsewhere. See {hints_url} for details.
--window-title
The window title for the hints window, default title is selected based on
the type of text being hinted.
The title for the hints window, default title is based on the type of text being
hinted.
'''.format(
default_regex=DEFAULT_REGEX,
line='{{line}}', path='{{path}}',

131
kitty/cli.py
View File

@ -28,26 +28,27 @@ class OptionDict(TypedDict):
CONFIG_HELP = '''\
Specify a path to the configuration file(s) to use. All configuration files are
merged onto the builtin {conf_name}.conf, overriding the builtin values. This option
can be specified multiple times to read multiple configuration files in
sequence, which are merged. Use the special value NONE to not load a config
file.
merged onto the builtin :file:`{conf_name}.conf`, overriding the builtin values.
This option can be specified multiple times to read multiple configuration files
in sequence, which are merged. Use the special value :code:`NONE` to not load
any config file.
If this option is not specified, config files are searched for in the order:
:file:`$XDG_CONFIG_HOME/{appname}/{conf_name}.conf`, :file:`~/.config/{appname}/{conf_name}.conf`, {macos_confpath}
:file:`$XDG_CONFIG_DIRS/{appname}/{conf_name}.conf`. The first one that exists is used as the
config file.
:file:`$XDG_CONFIG_HOME/{appname}/{conf_name}.conf`,
:file:`~/.config/{appname}/{conf_name}.conf`,{macos_confpath}
:file:`$XDG_CONFIG_DIRS/{appname}/{conf_name}.conf`. The first one that exists
is used as the config file.
If the environment variable :envvar:`KITTY_CONFIG_DIRECTORY` is specified, that
directory is always used and the above searching does not happen.
If :file:`/etc/xdg/{appname}/{conf_name}.conf` exists it is merged before (i.e. with lower
priority) than any user config files. It can be used to specify system-wide
defaults for all users. You can use either :code:`-` or :code:`/dev/stdin` to read the
config from STDIN.
If :file:`/etc/xdg/{appname}/{conf_name}.conf` exists, it is merged before (i.e.
with lower priority) than any user config files. It can be used to specify
system-wide defaults for all users. You can use either :code:`-` or
:file:`/dev/stdin` to read the config from STDIN.
'''.replace(
'{macos_confpath}',
(':file:`~/Library/Preferences/{appname}/{conf_name}.conf`,' if is_macos else ''), 1
(' :file:`~/Library/Preferences/{appname}/{conf_name}.conf`,' if is_macos else ''), 1
)
@ -294,9 +295,10 @@ def get_defaults_from_seq(seq: OptionSpecSeq) -> Dict[str, Any]:
default_msg = ('''\
Run the :italic:`{appname}` terminal emulator. You can also specify the :italic:`program`
to run inside :italic:`{appname}` as normal arguments following the :italic:`options`.
For example: {appname} sh -c "echo hello, world. Press ENTER to quit; read"
Run the :italic:`{appname}` terminal emulator. You can also specify the
:italic:`program` to run inside :italic:`{appname}` as normal arguments
following the :italic:`options`.
For example: {appname} --hold sh -c "echo hello, world"
For comprehensive documentation for kitty, please see: {url}''').format(
appname=appname, url=website_url())
@ -583,17 +585,20 @@ def options_spec() -> str:
dest=cls
default={appname}
condition=not is_macos
Set the class part of the :italic:`WM_CLASS` window property. On Wayland, it sets the app id.
Set the class part of the :italic:`WM_CLASS` window property. On Wayland, it
sets the app id.
--name
condition=not is_macos
Set the name part of the :italic:`WM_CLASS` property (defaults to using the value from :option:`{appname} --class`)
Set the name part of the :italic:`WM_CLASS` property. Defaults to using the
value from :option:`{appname} --class`.
--title -T
Set the OS window title. This will override any title set by the program running inside kitty, permanently
fixing the OS Window's title. So only use this if you are running a program that does not set titles.
Set the OS window title. This will override any title set by the program running
inside kitty, permanently fixing the OS window's title. So only use this if you
are running a program that does not set titles.
--config -c
@ -604,68 +609,74 @@ type=list
--override -o
type=list
Override individual configuration options, can be specified multiple times.
Syntax: :italic:`name=value`. For example: :option:`kitty -o` font_size=20
Syntax: :italic:`name=value`. For example: :option:`{appname} -o` font_size=20
--directory --working-directory -d
default=.
Change to the specified directory when launching
Change to the specified directory when launching.
--detach
type=bool-set
condition=not is_macos
Detach from the controlling terminal, if any
Detach from the controlling terminal, if any.
--session
Path to a file containing the startup :italic:`session` (tabs, windows, layout, programs).
Use - to read from STDIN. See the README file for details and an example.
Path to a file containing the startup :italic:`session` (tabs, windows, layout,
programs). Use - to read from STDIN. See the :file:`README` file for details and
an example.
--hold
type=bool-set
Remain open after child process exits. Note that this only affects the first
window. You can quit by either using the close window shortcut or pressing any key.
window. You can quit by either using the close window shortcut or pressing any
key.
--single-instance -1
type=bool-set
If specified only a single instance of :italic:`{appname}` will run. New invocations will
instead create a new top-level window in the existing :italic:`{appname}` instance. This
allows :italic:`{appname}` to share a single sprite cache on the GPU and also reduces
startup time. You can also have separate groups of :italic:`{appname}` instances by using the
:option:`kitty --instance-group` option
If specified only a single instance of :italic:`{appname}` will run. New
invocations will instead create a new top-level window in the existing
:italic:`{appname}` instance. This allows :italic:`{appname}` to share a single
sprite cache on the GPU and also reduces startup time. You can also have
separate groups of :italic:`{appname}` instances by using the :option:`{appname}
--instance-group` option.
--instance-group
Used in combination with the :option:`kitty --single-instance` option. All :italic:`{appname}` invocations
with the same :option:`kitty --instance-group` will result in new windows being created
in the first :italic:`{appname}` instance within that group
Used in combination with the :option:`{appname} --single-instance` option. All
:italic:`{appname}` invocations with the same :option:`{appname}
--instance-group` will result in new windows being created in the first
:italic:`{appname}` instance within that group.
--wait-for-single-instance-window-close
type=bool-set
Normally, when using :option:`--single-instance`, :italic:`{appname}` will open a new window in an existing
instance and quit immediately. With this option, it will not quit till the newly opened
window is closed. Note that if no previous instance is found, then :italic:`{appname}` will wait anyway,
Normally, when using :option:`{appname} --single-instance`, :italic:`{appname}`
will open a new window in an existing instance and quit immediately. With this
option, it will not quit till the newly opened window is closed. Note that if no
previous instance is found, then :italic:`{appname}` will wait anyway,
regardless of this option.
--listen-on
Tell kitty to listen on the specified address for control
messages. For example, :option:`{appname} --listen-on`=unix:/tmp/mykitty or
Listen on the specified socket address for control messages. For example,
:option:`{appname} --listen-on`=unix:/tmp/mykitty or
:option:`{appname} --listen-on`=tcp:localhost:12345. On Linux systems, you can
also use abstract UNIX sockets, not associated with a file, like this:
:option:`{appname} --listen-on`=unix:@mykitty. Environment variables
in the setting are expanded and relative paths are resolved with
respect to the temporary directory. To control kitty, you can send
it commands with :italic:`kitty @` using the :option:`kitty @ --to` option to
specify this address. This option will be ignored, unless you set
:opt:`allow_remote_control` to yes in :file:`kitty.conf`. Note that if you run
:italic:`kitty @` within a kitty window, there is no need to specify the :option:`kitty @ --to`
option as it is read automatically from the environment. For UNIX sockets, this
can also be specified in :file:`kitty.conf`.
:option:`{appname} --listen-on`=unix:@mykitty. Environment variables are
expanded and relative paths are resolved with respect to the temporary
directory. To control kitty, you can send commands to it with
:italic:`{appname} @` using the :option:`{appname} @ --to` option to specify
this address. Unless you enabled :opt:`allow_remote_control` in
:file:`{conf_name}.conf`, this option will be ignored. Note that if you run
:italic:`{appname} @` within a kitty window, there is
no need to specify the :option:`{appname} @ --to` option as it will
automatically read from the environment. For UNIX sockets, this can also be
specified in :file:`{conf_name}.conf`.
--start-as
@ -679,45 +690,48 @@ Control how the initial kitty window is created.
--version -v
type=bool-set
The current {appname} version
The current {appname} version.
--dump-commands
type=bool-set
Output commands received from child process to stdout
Output commands received from child process to STDOUT.
--replay-commands
Replay previously dumped commands. Specify the path to a dump file previously created by :option:`kitty --dump-commands`. You
Replay previously dumped commands. Specify the path to a dump file previously
created by :option:`{appname} --dump-commands`. You
can open a new kitty window to replay the commands with::
kitty sh -c "kitty --replay-commands /path/to/dump/file; read"
{appname} --hold {appname} --replay-commands /path/to/dump/file
--dump-bytes
Path to file in which to store the raw bytes received from the child process
Path to file in which to store the raw bytes received from the child process.
--debug-rendering --debug-gl
type=bool-set
Debug rendering commands. This will cause all OpenGL calls to check for errors
instead of ignoring them. Also prints out miscellaneous debug information.
Useful when debugging rendering problems
Useful when debugging rendering problems.
--debug-input --debug-keyboard
dest=debug_keyboard
type=bool-set
This option will cause kitty to print out key and mouse events as they are received
Print out key and mouse events as they are received.
--debug-font-fallback
type=bool-set
Print out information about the selection of fallback fonts for characters not present in the main font.
Print out information about the selection of fallback fonts for characters not
present in the main font.
--watcher
This option is deprecated in favor of the :opt:`watcher` option in kitty.conf and should not be used.
This option is deprecated in favor of the :opt:`watcher` option in
:file:`{conf_name}.conf` and should not be used.
--execute -e
@ -725,7 +739,8 @@ type=bool-set
!
'''
setattr(options_spec, 'ans', OPTIONS.format(
appname=appname, config_help=CONFIG_HELP.format(appname=appname, conf_name=appname),
appname=appname, conf_name=appname,
config_help=CONFIG_HELP.format(appname=appname, conf_name=appname),
))
ans: str = getattr(options_spec, 'ans')
return ans
@ -769,7 +784,7 @@ def parse_args(
return ans, parse_cmdline(oc, disabled, ans, args=args)
SYSTEM_CONF = '/etc/xdg/kitty/kitty.conf'
SYSTEM_CONF = f'/etc/xdg/{appname}/{appname}.conf'
def create_opts(args: CLIOptions, accumulate_bad_lines: Optional[List[BadLineType]] = None) -> KittyOpts:

30
kitty/conf/types.py
View File

@ -55,6 +55,7 @@ def ref_map() -> Dict[str, str]:
'functional': f'{website_url("keyboard-protocol")}#functional-key-definitions',
'ssh_copy_command': f'{website_url("kittens/ssh")}#ssh-copy-command',
'shell_integration': website_url("shell-integration"),
'clone_shell': f'{website_url("shell-integration")}#clone-shell',
'github_discussions': 'https://github.com/kovidgoyal/kitty/discussions',
}
for actions in get_all_actions().values():
@ -65,17 +66,30 @@ def ref_map() -> Dict[str, str]:
def remove_markup(text: str) -> str:
def sub(m: 'Match[str]') -> str:
if m.group(1) == 'ref':
q = m.group(2).split('<')[-1].rstrip('>')
return ref_map()[q]
if m.group(1) == 'ac':
q = m.group(2).split('<')[-1].rstrip('>')
return ref_map()[f'action-{q}']
if m.group(1) == 'disc':
def extract(m: 'Match[str]') -> Tuple[str, str]:
parts = m.group(2).split('<')
t = parts[0].strip()
q = parts[-1].rstrip('>')
return t, q
def sub(m: 'Match[str]') -> str:
if m.group(1) == 'ref':
t, q = extract(m)
return f'{t} <{ref_map()[q]}>'
if m.group(1) == 'doc':
t, q = extract(m)
return f'{t} <{website_url(q.lstrip("/"))}>'
if m.group(1) == 'ac':
q = m.group(2).split('<')[-1].rstrip('>')
return q
if m.group(1) == 'term':
t, _ = extract(m)
return t
if m.group(1) == 'option':
t, _ = extract(m)
return t
if m.group(1) == 'disc':
t, q = extract(m)
return f'{t} {ref_map()["github_discussions"]}/{q}'
return str(m.group(2))

1159
kitty/options/definition.py
View File

File diff suppressed because it is too large Load Diff