mirror of
https://github.com/kovidgoyal/kitty
synced 2026-07-26 02:02:14 +02:00
Docs: Improve the documentations
Add more text roles and links. Fix typos. Adjust the default shortcut order in overview. Notes on the impact of kitty-open.desktop on the default open apps. Document KITTY_DEVELOP_FROM in glossary. Add Python type hints to the watcher example. Mention clone-in-kitty in launch --copy-env. Fix remote control ls example does not work, by escaping the backslash.
This commit is contained in:
pagedown
@@ -5,22 +5,21 @@ The :command:`launch` command
|
||||
|
||||
|
||||
|kitty| has a :code:`launch` action that can be used to run arbitrary programs
|
||||
in new windows/tabs. It can be mapped to user defined shortcuts in kitty.conf.
|
||||
It is very powerful and allows sending the contents of
|
||||
the current window to the launched program, as well as many other options.
|
||||
in new windows/tabs. It can be mapped to user defined shortcuts in
|
||||
:file:`kitty.conf`. It is very powerful and allows sending the contents of the
|
||||
current window to the launched program, as well as many other options.
|
||||
|
||||
In the simplest form, you can use it to open a new kitty window running the
|
||||
shell, as shown below::
|
||||
|
||||
map f1 launch
|
||||
|
||||
To run a different program simply pass the command line as arguments to
|
||||
launch::
|
||||
To run a different program simply pass the command line as arguments to launch::
|
||||
|
||||
map f1 launch vim path/to/some/file
|
||||
|
||||
To open a new window with the same working directory as the currently
|
||||
active window::
|
||||
To open a new window with the same working directory as the currently active
|
||||
window::
|
||||
|
||||
map f1 launch --cwd=current
|
||||
|
||||
@@ -30,9 +29,10 @@ To open the new window in a new tab::
|
||||
|
||||
To run multiple commands in a shell, use::
|
||||
|
||||
map f1 launch sh -c "ls && zsh"
|
||||
map f1 launch sh -c "ls && exec zsh"
|
||||
|
||||
To pass the contents of the current screen and scrollback to the started process::
|
||||
To pass the contents of the current screen and scrollback to the started
|
||||
process::
|
||||
|
||||
map f1 launch --stdin-source=@screen_scrollback less
|
||||
|
||||
@@ -46,16 +46,16 @@ There are many more powerful options, refer to the complete list below.
|
||||
map f1 launch_tab vim
|
||||
map f2 launch_tab emacs
|
||||
|
||||
The :kbd:`F1` key will now open vim in a new tab with the current windows
|
||||
working directory
|
||||
The :kbd:`F1` key will now open :program:`vim` in a new tab with the current
|
||||
windows working directory.
|
||||
|
||||
|
||||
The piping environment
|
||||
--------------------------
|
||||
|
||||
When using :option:`launch --stdin-source`, the program to which the data is
|
||||
piped has a special environment variable declared, :envvar:`KITTY_PIPE_DATA` whose
|
||||
contents are::
|
||||
piped has a special environment variable declared, :envvar:`KITTY_PIPE_DATA`
|
||||
whose contents are::
|
||||
|
||||
KITTY_PIPE_DATA={scrolled_by}:{cursor_x},{cursor_y}:{lines},{columns}
|
||||
|
||||
@@ -73,33 +73,33 @@ the command line:
|
||||
|
||||
|
||||
``@selection``
|
||||
replaced by the currently selected text
|
||||
Replaced by the currently selected text.
|
||||
|
||||
``@active-kitty-window-id``
|
||||
replaced by the id of the currently active kitty window
|
||||
Replaced by the id of the currently active kitty window.
|
||||
|
||||
``@line-count``
|
||||
replaced by the number of lines in STDIN. Only present when passing some
|
||||
data to STDIN
|
||||
Replaced by the number of lines in STDIN. Only present when passing some
|
||||
data to STDIN.
|
||||
|
||||
``@input-line-number``
|
||||
replaced the number of lines a pager should scroll to match the current
|
||||
scroll position in kitty. See :opt:`scrollback_pager` for details
|
||||
Replaced the number of lines a pager should scroll to match the current
|
||||
scroll position in kitty. See :opt:`scrollback_pager` for details.
|
||||
|
||||
``@scrolled-by``
|
||||
replaced by the number of lines kitty is currently scrolled by
|
||||
Replaced by the number of lines kitty is currently scrolled by.
|
||||
|
||||
``@cursor-x``
|
||||
replaced by the current cursor x position with 1 being the leftmost cell
|
||||
Replaced by the current cursor x position with 1 being the leftmost cell.
|
||||
|
||||
``@cursor-y``
|
||||
replaced by the current cursor y position with 1 being the topmost cell
|
||||
Replaced by the current cursor y position with 1 being the topmost cell.
|
||||
|
||||
``@first-line-on-screen``
|
||||
replaced by the first line on screen. Can be used for pager positioning.
|
||||
Replaced by the first line on screen. Can be used for pager positioning.
|
||||
|
||||
``@last-line-on-screen``
|
||||
replaced by the last line on screen. Can be used for pager positioning.
|
||||
Replaced by the last line on screen. Can be used for pager positioning.
|
||||
|
||||
|
||||
For example::
|
||||
@@ -112,44 +112,51 @@ For example::
|
||||
Watching launched windows
|
||||
---------------------------
|
||||
|
||||
The :option:`launch --watcher` option allows you to specify python functions
|
||||
The :option:`launch --watcher` option allows you to specify Python functions
|
||||
that will be called at specific events, such as when the window is resized or
|
||||
closed. Simply specify the path to a python module that specifies callback
|
||||
closed. Simply specify the path to a Python module that specifies callback
|
||||
functions for the events you are interested in, for example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def on_resize(boss, window, data):
|
||||
from typing import Any, Dict
|
||||
|
||||
from kitty.boss import Boss
|
||||
from kitty.window import Window
|
||||
|
||||
|
||||
def on_resize(boss: Boss, window: Window, data: Dict[str, Any]) -> None:
|
||||
# Here data will contain old_geometry and new_geometry
|
||||
|
||||
def on_focus_change(boss, window, data):
|
||||
def on_focus_change(boss: Boss, window: Window, data: Dict[str, Any])-> None:
|
||||
# Here data will contain focused
|
||||
|
||||
def on_close(boss, window, data):
|
||||
def on_close(boss: Boss, window: Window, data: Dict[str, Any])-> None:
|
||||
# called when window is closed, typically when the program running in
|
||||
# it exits.
|
||||
|
||||
|
||||
Every callback is passed a reference to the global ``Boss`` object as well as
|
||||
the ``Window`` object the action is occurring on. The ``data`` object is
|
||||
a dict that contains event dependent data. Some useful methods and attributes
|
||||
for the ``Window`` object are: ``as_text(as_ans=False, add_history=False,
|
||||
the ``Window`` object the action is occurring on. The ``data`` object is a dict
|
||||
that contains event dependent data. Some useful methods and attributes for the
|
||||
``Window`` object are: ``as_text(as_ans=False, add_history=False,
|
||||
add_wrap_markers=False, alternate_screen=False)`` with which you can get the
|
||||
contents of the window and its scrollback buffer. Similarly,
|
||||
``window.child.pid`` is the PID of the processes that was launched
|
||||
in the window and ``window.id`` is the internal kitty ``id`` of the
|
||||
window.
|
||||
in the window and ``window.id`` is the internal kitty ``id`` of the window.
|
||||
|
||||
|
||||
Finding executables
|
||||
-----------------------
|
||||
|
||||
When you specify a command to run as just a name rather than an absolute path,
|
||||
it is searched for in the system-wide ``PATH`` environment variable. Note that
|
||||
this **may not** be the value of ``PATH`` inside a shell, as shell startup scripts
|
||||
often change the value of this variable. If it is not found there, then a
|
||||
system specific list of default paths is searched. If it is still not found,
|
||||
then your shell is run and the value of ``PATH`` inside the shell is used.
|
||||
it is searched for in the system-wide :envvar:`PATH` environment variable. Note
|
||||
that this **may not** be the value of :envvar:`PATH` inside a shell, as shell
|
||||
startup scripts often change the value of this variable. If it is not found
|
||||
there, then a system specific list of default paths is searched. If it is still
|
||||
not found, then your shell is run and the value of :envvar:`PATH` inside the
|
||||
shell is used.
|
||||
|
||||
See :opt:`exe_search_path` for details and how to control this.
|
||||
|
||||
Syntax reference
|
||||
|
||||
Reference in New Issue
Block a user