Start work on a kitty website
Port the current asciidoc documentation to sphinx
This commit is contained in:
Kovid Goyal
parent
edda0d91bb
commit
f82b7841c6
1
.gitignore
vendored
1
.gitignore
vendored
@ -13,3 +13,4 @@ kitty-profile
|
|||||||
dev
|
dev
|
||||||
__pycache__
|
__pycache__
|
||||||
glfw/wayland-*-client-protocol.[ch]
|
glfw/wayland-*-client-protocol.[ch]
|
||||||
|
docs/_build
|
||||||
|
|||||||
512
README.asciidoc
512
README.asciidoc
@ -1,519 +1,7 @@
|
|||||||
= kitty - A terminal emulator
|
= kitty - A terminal emulator
|
||||||
:toc:
|
|
||||||
:toc-placement!:
|
|
||||||
// START_SHORTCUT_BLOCK
|
|
||||||
:sc_change_font_size_all_0: pass:quotes[`ctrl+shift+backspace`]
|
|
||||||
:sc_change_font_size_all_2_0: pass:quotes[`ctrl+shift+minus`]
|
|
||||||
:sc_change_font_size_all_plus2_0: pass:quotes[`ctrl+shift+equal`]
|
|
||||||
:sc_close_tab: pass:quotes[`ctrl+shift+q`]
|
|
||||||
:sc_close_window: pass:quotes[`ctrl+shift+w`]
|
|
||||||
:sc_copy_to_clipboard: pass:quotes[`ctrl+shift+c`]
|
|
||||||
:sc_edit_config_file: pass:quotes[`ctrl+shift+f2`]
|
|
||||||
:sc_eighth_window: pass:quotes[`ctrl+shift+8`]
|
|
||||||
:sc_fifth_window: pass:quotes[`ctrl+shift+5`]
|
|
||||||
:sc_first_window: pass:quotes[`ctrl+shift+1`]
|
|
||||||
:sc_fourth_window: pass:quotes[`ctrl+shift+4`]
|
|
||||||
:sc_input_unicode_character: pass:quotes[`ctrl+shift+u`]
|
|
||||||
:sc_kitten_hints: pass:quotes[`ctrl+shift+e`]
|
|
||||||
:sc_kitten_hints_type_line_program: pass:quotes[`ctrl+shift+p → l`]
|
|
||||||
:sc_kitten_hints_type_path: pass:quotes[`ctrl+shift+p → shift+f`]
|
|
||||||
:sc_kitten_hints_type_path_program: pass:quotes[`ctrl+shift+p → f`]
|
|
||||||
:sc_kitten_hints_type_word_program: pass:quotes[`ctrl+shift+p → w`]
|
|
||||||
:sc_kitty_shell_window: pass:quotes[`ctrl+shift+escape`]
|
|
||||||
:sc_move_tab_backward: pass:quotes[`ctrl+shift+,`]
|
|
||||||
:sc_move_tab_forward: pass:quotes[`ctrl+shift+.`]
|
|
||||||
:sc_move_window_backward: pass:quotes[`ctrl+shift+b`]
|
|
||||||
:sc_move_window_forward: pass:quotes[`ctrl+shift+f`]
|
|
||||||
:sc_move_window_to_top: pass:quotes[`ctrl+shift+``]
|
|
||||||
:sc_new_os_window: pass:quotes[`ctrl+shift+n`]
|
|
||||||
:sc_new_tab: pass:quotes[`ctrl+shift+t`]
|
|
||||||
:sc_new_window: pass:quotes[`ctrl+shift+enter`]
|
|
||||||
:sc_next_layout: pass:quotes[`ctrl+shift+l`]
|
|
||||||
:sc_next_tab: pass:quotes[`ctrl+shift+right`]
|
|
||||||
:sc_next_window: pass:quotes[`ctrl+shift+]`]
|
|
||||||
:sc_ninth_window: pass:quotes[`ctrl+shift+9`]
|
|
||||||
:sc_pass_selection_to_program: pass:quotes[`ctrl+shift+o`]
|
|
||||||
:sc_paste_from_clipboard: pass:quotes[`ctrl+shift+v`]
|
|
||||||
:sc_paste_from_selection: pass:quotes[`ctrl+shift+s` or `shift+insert`]
|
|
||||||
:sc_previous_tab: pass:quotes[`ctrl+shift+left`]
|
|
||||||
:sc_previous_window: pass:quotes[`ctrl+shift+[`]
|
|
||||||
:sc_scroll_end: pass:quotes[`ctrl+shift+end`]
|
|
||||||
:sc_scroll_home: pass:quotes[`ctrl+shift+home`]
|
|
||||||
:sc_scroll_line_down: pass:quotes[`ctrl+shift+down` or `ctrl+shift+j`]
|
|
||||||
:sc_scroll_line_up: pass:quotes[`ctrl+shift+up` or `ctrl+shift+k`]
|
|
||||||
:sc_scroll_page_down: pass:quotes[`ctrl+shift+page_down`]
|
|
||||||
:sc_scroll_page_up: pass:quotes[`ctrl+shift+page_up`]
|
|
||||||
:sc_second_window: pass:quotes[`ctrl+shift+2`]
|
|
||||||
:sc_set_background_opacity_0_1: pass:quotes[`ctrl+shift+a → l`]
|
|
||||||
:sc_set_background_opacity_1: pass:quotes[`ctrl+shift+a → 1`]
|
|
||||||
:sc_set_background_opacity_default: pass:quotes[`ctrl+shift+a → d`]
|
|
||||||
:sc_set_background_opacity_plus0_1: pass:quotes[`ctrl+shift+a → m`]
|
|
||||||
:sc_set_tab_title: pass:quotes[`ctrl+shift+alt+t`]
|
|
||||||
:sc_seventh_window: pass:quotes[`ctrl+shift+7`]
|
|
||||||
:sc_show_scrollback: pass:quotes[`ctrl+shift+h`]
|
|
||||||
:sc_sixth_window: pass:quotes[`ctrl+shift+6`]
|
|
||||||
:sc_start_resizing_window: pass:quotes[`ctrl+shift+r`]
|
|
||||||
:sc_tenth_window: pass:quotes[`ctrl+shift+0`]
|
|
||||||
:sc_third_window: pass:quotes[`ctrl+shift+3`]
|
|
||||||
:sc_toggle_fullscreen: pass:quotes[`ctrl+shift+f11`]
|
|
||||||
// END_SHORTCUT_BLOCK
|
|
||||||
|
|
||||||
++++
|
|
||||||
<img align="left" role="left" src="logo/kitty.png?raw=true"/>
|
|
||||||
++++
|
|
||||||
image::https://travis-ci.org/kovidgoyal/kitty.svg?branch=master[Build status, link=https://travis-ci.org/kovidgoyal/kitty]
|
image::https://travis-ci.org/kovidgoyal/kitty.svg?branch=master[Build status, link=https://travis-ci.org/kovidgoyal/kitty]
|
||||||
|
|
||||||
== Major Features
|
|
||||||
|
|
||||||
* Uses OpenGL for rendering, offloads rendering to the GPU for link:#performance[lower system
|
|
||||||
load] and buttery smooth scrolling. Uses threaded rendering to minimize input
|
|
||||||
latency.
|
|
||||||
|
|
||||||
* Supports all modern terminal features: link:graphics-protocol.asciidoc[graphics (images)], unicode,
|
|
||||||
true-color, OpenType ligatures, mouse protocol, focus tracking, bracketed paste and so on.
|
|
||||||
|
|
||||||
* Supports tiling multiple terminal windows side by side in different
|
|
||||||
link:#layouts[layouts] without needing to use an extra program like tmux
|
|
||||||
|
|
||||||
* Can be link:remote-control.asciidoc[controlled from scripts or the shell prompt], even over SSH.
|
|
||||||
|
|
||||||
* Has a framework for _kittens_, small terminal programs that can be used to extend kitty's functionality.
|
|
||||||
For example, they are used for link:#unicode-input[Unicode input], link:#hints[Hints] and link:https://github.com/kovidgoyal/kitty/blob/master/kittens/diff/README.asciidoc[Side-by-side diff].
|
|
||||||
|
|
||||||
* Supports link:#startup-sessions[startup sessions] which allow you to specify the window/tab layout,
|
|
||||||
working directories and programs to run on startup.
|
|
||||||
|
|
||||||
* Cross-platform support: kitty currently works on Linux and macOS, but because
|
|
||||||
it uses only OpenGL for rendering, it should be trivial to port to other
|
|
||||||
platforms.
|
|
||||||
|
|
||||||
* Allows you to open link:#the-scrollback-buffer[the scrollback buffer] in a separate
|
|
||||||
window using arbitrary programs of your choice. This is useful for browsing
|
|
||||||
the history comfortably in a pager or editor.
|
|
||||||
|
|
||||||
|
|
||||||
image::screenshots/screenshot.png?raw=true[Screenshot, showing three programs in the "Tall" layout]
|
|
||||||
|
|
||||||
toc::[]
|
|
||||||
|
|
||||||
|
|
||||||
== Installation
|
|
||||||
|
|
||||||
kitty is designed to run from source, for easy hackability. Make sure
|
|
||||||
the following dependencies are installed first.
|
|
||||||
|
|
||||||
=== Dependencies
|
|
||||||
|
|
||||||
* python >= 3.5
|
|
||||||
* harfbuzz >= 1.5.0
|
|
||||||
* zlib
|
|
||||||
* libpng
|
|
||||||
* freetype (not needed on macOS)
|
|
||||||
* fontconfig (not needed on macOS)
|
|
||||||
* ImageMagick (optional, needed to use the `kitty icat` tool to display images in the terminal)
|
|
||||||
* pygments (optional, need for syntax highlighting in `kitty +kitten diff`)
|
|
||||||
* gcc or clang (required only for building)
|
|
||||||
* pkg-config (required only for building)
|
|
||||||
* For building on Linux in addition to the above dependencies you might also need to install the `-dev` packages for `xcursor`, `xrandr`, `libxi`, `xinerama`, `libgl1-mesa` and `xkbcommon-x11`, if they are not already installed by your distro.
|
|
||||||
|
|
||||||
=== Install and run from source
|
|
||||||
|
|
||||||
....
|
|
||||||
git clone https://github.com/kovidgoyal/kitty && cd kitty
|
|
||||||
....
|
|
||||||
|
|
||||||
Now build the native code parts of kitty with the following command:
|
|
||||||
|
|
||||||
....
|
|
||||||
make
|
|
||||||
....
|
|
||||||
|
|
||||||
You can run kitty, as:
|
|
||||||
|
|
||||||
....
|
|
||||||
python3 .
|
|
||||||
....
|
|
||||||
|
|
||||||
If that works, you can create a script to launch kitty:
|
|
||||||
|
|
||||||
....
|
|
||||||
#!/usr/bin/env python3
|
|
||||||
|
|
||||||
import runpy
|
|
||||||
runpy.run_path('/path/to/kitty/dir', run_name='__main__')
|
|
||||||
....
|
|
||||||
|
|
||||||
And place it in `~/bin` or `/usr/bin` so that you can run kitty using
|
|
||||||
just `kitty`.
|
|
||||||
|
|
||||||
=== Linux packages
|
|
||||||
|
|
||||||
* Arch Linux: https://www.archlinux.org/packages/community/x86_64/kitty/
|
|
||||||
|
|
||||||
* Arch Linux: AUR git package https://aur.archlinux.org/packages/kitty-git/
|
|
||||||
|
|
||||||
* NixOS / nixpkgs: https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/kitty/default.nix
|
|
||||||
|
|
||||||
* Gentoo: https://packages.gentoo.org/packages/x11-terms/kitty
|
|
||||||
|
|
||||||
* openSUSE: https://build.opensuse.org/package/show/X11:terminals/kitty
|
|
||||||
|
|
||||||
* Debian: https://packages.debian.org/buster/kitty
|
|
||||||
|
|
||||||
=== macOS packages
|
|
||||||
|
|
||||||
kitty is available as a macOS `dmg` file for easy installation from the
|
|
||||||
link:../../releases[releases page]. You can also run kitty directly from
|
|
||||||
source using the above install from source instructions, after installing its
|
|
||||||
dependencies using http://brew.sh/[brew] or a similar package manager.
|
|
||||||
|
|
||||||
|
|
||||||
== Design philosophy
|
|
||||||
|
|
||||||
kitty is designed for power keyboard users. To that end all its controls
|
|
||||||
work with the keyboard (although it fully supports mouse interactions as
|
|
||||||
well). Its configuration is a simple, human editable, single file for
|
|
||||||
easy reproducibility (I like to store config files in source control).
|
|
||||||
|
|
||||||
The code in kitty is designed to be simple, modular and hackable. It is
|
|
||||||
written in a mix of C (for performance sensitive parts) and Python (for
|
|
||||||
easy hackability of the UI). It does not depend on any large and complex
|
|
||||||
UI toolkit, using only OpenGL for rendering everything.
|
|
||||||
|
|
||||||
Finally, kitty is designed from the ground up to support all modern
|
|
||||||
terminal features, such as unicode, true color, bold/italic fonts, text
|
|
||||||
formatting, etc. It even extends existing text formatting escape codes,
|
|
||||||
to add support for features not available elsewhere, such as colored and
|
|
||||||
styled (curly) underlines. One of the design goals of kitty is to be
|
|
||||||
easily extensible so that new features can be added in the future with
|
|
||||||
relatively less effort.
|
|
||||||
|
|
||||||
== Tabs and Windows
|
|
||||||
|
|
||||||
kitty is capable of running multiple programs organized into tabs and
|
|
||||||
windows. The top level of organization is the _Tab_. Each tab consists
|
|
||||||
of one or more _windows_. The windows can be arranged in multiple
|
|
||||||
different layouts, like windows are organized in a tiling window
|
|
||||||
manager. The keyboard controls (which are all customizable) for tabs and
|
|
||||||
windows are:
|
|
||||||
|
|
||||||
[[scrolling-shortcuts]]
|
|
||||||
[options="header"]
|
|
||||||
|
|
||||||
=== Scrolling
|
|
||||||
|
|
||||||
|===
|
|
||||||
|Action |Shortcut
|
|
||||||
|
|
||||||
|Scroll line up | {sc_scroll_line_up}
|
|
||||||
|Scroll line down | {sc_scroll_line_down}
|
|
||||||
|Scroll page up | {sc_scroll_page_up}
|
|
||||||
|Scroll page down | {sc_scroll_page_down}
|
|
||||||
|Scroll to top | {sc_scroll_home}
|
|
||||||
|Scroll to bottom | {sc_scroll_end}
|
|
||||||
|
|
||||||
|===
|
|
||||||
|
|
||||||
[options="header"]
|
|
||||||
|
|
||||||
=== Tabs
|
|
||||||
|
|
||||||
|===
|
|
||||||
|Action |Shortcut
|
|
||||||
|
|
||||||
|New tab | {sc_new_tab}
|
|
||||||
|Close tab | {sc_close_tab}
|
|
||||||
|Next tab | {sc_next_tab}
|
|
||||||
|Previous tab | {sc_previous_tab}
|
|
||||||
|Next layout | {sc_next_layout}
|
|
||||||
|Move tab forward | {sc_move_tab_forward}
|
|
||||||
|Move tab backward | {sc_move_tab_backward}
|
|
||||||
|Set tab title | {sc_set_tab_title}
|
|
||||||
|
|
||||||
|===
|
|
||||||
|
|
||||||
|
|
||||||
[options="header"]
|
|
||||||
|
|
||||||
=== Windows
|
|
||||||
|
|
||||||
|===
|
|
||||||
|Action |Shortcut
|
|
||||||
|
|
||||||
|New window | {sc_new_window}
|
|
||||||
|New OS window| {sc_new_os_window}
|
|
||||||
|Close window | {sc_close_window}
|
|
||||||
|Next window | {sc_next_window}
|
|
||||||
|Previous window | {sc_previous_window}
|
|
||||||
|Move window forward | {sc_move_window_forward}
|
|
||||||
|Move window backward | {sc_move_window_backward}
|
|
||||||
|Move window to top | {sc_move_window_to_top}
|
|
||||||
|Focus specific window (windows are counted clockwise from the top left corner) | {sc_first_window}, {sc_second_window} ... {sc_tenth_window}
|
|
||||||
|
|
||||||
|===
|
|
||||||
|
|
||||||
== Other keyboard shortcuts
|
|
||||||
|
|
||||||
|===
|
|
||||||
|Action |Shortcut
|
|
||||||
|
|
||||||
|Copy to clipboard | {sc_copy_to_clipboard}
|
|
||||||
|Paste from clipboard | {sc_paste_from_clipboard}
|
|
||||||
|Paste from selection | {sc_paste_from_selection}
|
|
||||||
|Increase font size | {sc_change_font_size_all_plus2_0}
|
|
||||||
|Decrease font size | {sc_change_font_size_all_2_0}
|
|
||||||
|Restore font size | {sc_change_font_size_all_0}
|
|
||||||
|Toggle fullscreen | {sc_toggle_fullscreen}
|
|
||||||
|Input unicode character | {sc_input_unicode_character}
|
|
||||||
|Click URL using the keyboard | {sc_kitten_hints}
|
|
||||||
|Pass current selection to program | {sc_pass_selection_to_program}
|
|
||||||
|Edit kitty config file | {sc_edit_config_file}
|
|
||||||
|Open a kitty shell | {sc_kitty_shell_window}
|
|
||||||
|Increase background opacity | {sc_set_background_opacity_plus0_1}
|
|
||||||
|Decrease background opacity | {sc_set_background_opacity_0_1}
|
|
||||||
|Full background opacity | {sc_set_background_opacity_1}
|
|
||||||
|Reset background opacity | {sc_set_background_opacity_default}
|
|
||||||
|===
|
|
||||||
|
|
||||||
|
|
||||||
== Controlling kitty from scripts
|
|
||||||
|
|
||||||
You can control kitty from the command line/scripts by sending it messages.
|
|
||||||
You can tell kitty to open/close/rename tabs and windows. You can even send
|
|
||||||
arbitrary input/text to any specified window. Messages can be sent using `kitty
|
|
||||||
@`. Note that you must set `allow_remote_control yes` in your
|
|
||||||
link:kitty/kitty.conf[kitty.conf] to use this feature. It even works over SSH
|
|
||||||
connections. This feature is best illustrated with a
|
|
||||||
link:remote-control.asciidoc[tutorial].
|
|
||||||
|
|
||||||
|
|
||||||
== The scrollback buffer
|
|
||||||
|
|
||||||
kitty supports scrolling back to view history, just like most terminals. You
|
|
||||||
can use either the <<scrolling-shortcuts,keyboard shortcuts>> or the mouse
|
|
||||||
scroll wheel to do so. However, kitty has an extra, neat feature. Sometimes
|
|
||||||
you need to explore the scrollback buffer in more detail, maybe search for some
|
|
||||||
text or refer to it side-by-side while typing in a follow-up command. kitty
|
|
||||||
allows you to do this by pressing the {sc_show_scrollback} key-combination,
|
|
||||||
which will open the scrollback buffer in your favorite pager program (which is
|
|
||||||
`less` by default). Colors and text formatting are preserved. You can explore
|
|
||||||
the scrollback pager comfortably within the pager.
|
|
||||||
|
|
||||||
|
|
||||||
== 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.
|
|
||||||
|
|
||||||
image::screenshots/unicode.png?raw=true[Unicode input widget, showing selection of unicode characters by name]
|
|
||||||
|
|
||||||
In 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.
|
|
||||||
|
|
||||||
In 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 leading period and the index for the match if you dont like to use arrow
|
|
||||||
keys.
|
|
||||||
|
|
||||||
== 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_kitten_hints}
|
|
||||||
to choose any URL visible on the screen and then open it using your system
|
|
||||||
browser.
|
|
||||||
|
|
||||||
image::screenshots/hints_mode.png?raw=true[URL hints mode]
|
|
||||||
|
|
||||||
Similarly, you can press {sc_kitten_hints_type_path_program} 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.
|
|
||||||
|
|
||||||
The hints kitten is very powerful to see more detailed help on its various
|
|
||||||
options and modes of operation, use: `kitty +kitten hints --help`.
|
|
||||||
|
|
||||||
== Miscellaneous features
|
|
||||||
|
|
||||||
* You can also hold down `ctrl+shift` and click on a URL to open it in a browser.
|
|
||||||
* You can double click to select a word and triple click to select a line.
|
|
||||||
* You can right click to extend a previous selection
|
|
||||||
|
|
||||||
|
|
||||||
== Layouts
|
|
||||||
|
|
||||||
Currently, there are five layouts available,
|
|
||||||
|
|
||||||
* Stack -- Only a single maximized window is shown at a time
|
|
||||||
* Tall -- One window is shown full height on the left, the rest of the windows are shown one below the other on the right
|
|
||||||
* Fat -- One window is shown full width on the top, the rest of the windows are shown side-by-side on the bottom
|
|
||||||
* Grid -- All windows are shown in a grid
|
|
||||||
* Horizontal -- All windows are shown side-by-side
|
|
||||||
* Vertical -- All windows are shown one below the other
|
|
||||||
|
|
||||||
You can switch between layouts using the {sc_next_layout} key combination. You can
|
|
||||||
also create shortcuts to select particular layouts, and choose which layouts
|
|
||||||
you want to enable/disable, see link:kitty/kitty.conf[kitty.conf] for examples.
|
|
||||||
|
|
||||||
You can resize windows inside layouts. Press {sc_start_resizing_window} to
|
|
||||||
enter resizing mode and follow the on-screen instructions. In a given window
|
|
||||||
layout only some operations may be possible for a particular window. For
|
|
||||||
example, in the Tall layout you can make the first window wider/narrower, but
|
|
||||||
not taller/shorter. Note that what you are resizing is actually not a window,
|
|
||||||
but a row/column in the layout, all windows in that row/column will be resized.
|
|
||||||
|
|
||||||
Some layouts take options to control their behavior. For example, the `fat` and `tall`
|
|
||||||
layouts accept the `bias` option to control how the available space is split up. To specify the
|
|
||||||
option, in kitty.conf use:
|
|
||||||
|
|
||||||
```
|
|
||||||
enabled_layouts tall:bias=70
|
|
||||||
```
|
|
||||||
|
|
||||||
This will make the tall window occupy `70%` of available width. `bias` can be
|
|
||||||
any number between 10 and 90.
|
|
||||||
|
|
||||||
Writing a new layout only requires about a hundred lines of code, so if there is
|
|
||||||
some layout you want, take a look at link:kitty/layout.py[layout.py] and submit
|
|
||||||
a pull request!
|
|
||||||
|
|
||||||
|
|
||||||
== Configuration
|
|
||||||
|
|
||||||
kitty is highly customizable, everything from keyboard shortcuts, to painting
|
|
||||||
frames-per-second. See the heavily commented link:kitty/kitty.conf[default
|
|
||||||
config file] for an overview of all customization possibilities.
|
|
||||||
|
|
||||||
By default kitty looks for a config file in the OS config directories (usually
|
|
||||||
`~/.config/kitty/kitty.conf` and additionally
|
|
||||||
`~/Library/Preferences/kitty/kitty.conf` on macOS) but you can pass a specific
|
|
||||||
path via the `--config` option or use the `KITTY_CONFIG_DIRECTORY` environment
|
|
||||||
variable. See the help for the `--config` option in `kitty --help` for full
|
|
||||||
details. You can also dump the current configuration using the `--debug-config`
|
|
||||||
option.
|
|
||||||
|
|
||||||
|
|
||||||
== Startup Sessions
|
|
||||||
|
|
||||||
You can control the tabs, window layout, working directory, startup
|
|
||||||
programs, etc. by creating a "session" file and using the `--session`
|
|
||||||
command line flag. For example:
|
|
||||||
|
|
||||||
....
|
|
||||||
# Set the window layout for the current tab
|
|
||||||
layout tall
|
|
||||||
# Set the working directory for windows in the current tab
|
|
||||||
cd ~
|
|
||||||
# Create a window and run the specified command in it
|
|
||||||
launch zsh
|
|
||||||
# Create a window with some environment variables set and run vim in it
|
|
||||||
launch env FOO=BAR vim
|
|
||||||
# Set the title for the next window
|
|
||||||
title Chat with x
|
|
||||||
launch irssi --profile x
|
|
||||||
|
|
||||||
# Create a new tab (the part after new_tab is the optional tab name which will
|
|
||||||
# be displayed in the tab bar, if omitted, the title of the active window will
|
|
||||||
# be used instead)
|
|
||||||
new_tab my tab
|
|
||||||
cd ~/somewhere
|
|
||||||
# Set the layouts allowed in this tab
|
|
||||||
enabled_layouts tall, stack
|
|
||||||
# Set the current layout
|
|
||||||
layout stack
|
|
||||||
launch zsh
|
|
||||||
# Make the current window the active (focused) window
|
|
||||||
focus
|
|
||||||
launch emacs
|
|
||||||
....
|
|
||||||
|
|
||||||
== Protocol Extensions
|
|
||||||
|
|
||||||
kitty has a few extensions to the xterm protocol, to enable advanced features,
|
|
||||||
see link:protocol-extensions.asciidoc[Protocol Extensions].
|
|
||||||
|
|
||||||
|
|
||||||
== Font control
|
|
||||||
|
|
||||||
kitty has extremely flexible and powerful font selection features. You can
|
|
||||||
specify individual families for the regular, bold, italic and bold+italic
|
|
||||||
fonts. You can even specify specific font families for specific ranges of
|
|
||||||
unicode characters. This allows precise control over text rendering. It can
|
|
||||||
come in handy for applications like powerline, without the need to use patched
|
|
||||||
fonts. See the various font related configuration directives in the
|
|
||||||
link:kitty/kitty.conf[config file].
|
|
||||||
|
|
||||||
== Performance
|
|
||||||
|
|
||||||
The main goals for kitty performance are user perceived latency while typing
|
|
||||||
and "smoothness" while scrolling as well as CPU usage. kitty tries hard to find
|
|
||||||
an optimum balance for these. To that end it keeps a cache of each rendered
|
|
||||||
glyph in video RAM so that font rendering is not a bottleneck. Interaction
|
|
||||||
with child programs takes place in a separate thread from rendering, to improve
|
|
||||||
smoothness.
|
|
||||||
|
|
||||||
There are two parameters you can tune to adjust the performance. ``repaint_delay``
|
|
||||||
and ``input_delay``. These control the artificial delays introduced into the
|
|
||||||
render loop to reduce CPU usage. See the link:kitty/kitty.conf[config file] for details.
|
|
||||||
See also the ``sync_to_monitor`` option to further decrease latency at the cost
|
|
||||||
of some link:https://en.wikipedia.org/wiki/Screen_tearing[tearing] while scrolling.
|
|
||||||
|
|
||||||
You can generate detailed per-function performance data using
|
|
||||||
link:https://github.com/gperftools/gperftools[gperftools]. Build kitty with
|
|
||||||
`make profile` which will create an executable called `kitty-profile`. Run
|
|
||||||
that and perform the task you want to analyse, for example, scrolling a large
|
|
||||||
file with `less`. After you quit, function call statistics will be printed to
|
|
||||||
`stdout` and you can use tools like *kcachegrind* for more detailed analysis.
|
|
||||||
|
|
||||||
Here are some CPU usage numbers for the task of scrolling a file continuously in less.
|
|
||||||
The CPU usage is for the terminal process and X together and is measured using htop.
|
|
||||||
The measurements are taken at the same font and window size for all terminals on a
|
|
||||||
`Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz` CPU with a
|
|
||||||
`Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD 7770/8760 / R7 250X]` GPU.
|
|
||||||
|
|
||||||
|===
|
|
||||||
| Terminal | CPU usage (X + terminal)
|
|
||||||
|
|
||||||
| kitty | 6 - 8%
|
|
||||||
| xterm | 5 - 7% (but scrolling was extremely janky)
|
|
||||||
| termite | 10 - 13%
|
|
||||||
| urxvt | 12 - 14%
|
|
||||||
| gnome-terminal | 15 - 17%
|
|
||||||
| konsole | 29 - 31%
|
|
||||||
|
|
||||||
|===
|
|
||||||
|
|
||||||
As you can see, kitty uses much less CPU than all terminals, except xterm, but
|
|
||||||
its scrolling "smoothness" is much better than that of xterm (at least to my,
|
|
||||||
admittedly biased, eyes).
|
|
||||||
|
|
||||||
== Note for Linux/macOS packagers
|
|
||||||
|
|
||||||
While kitty does use python, it is not a traditional python package, so please do not install it in site-packages.
|
|
||||||
Instead run,
|
|
||||||
|
|
||||||
```
|
|
||||||
python3 setup.py linux-package
|
|
||||||
```
|
|
||||||
|
|
||||||
This will install kitty into the directory `linux-package`. You can run kitty
|
|
||||||
with `linux-package/bin/kitty`. All the files needed to run kitty will be in
|
|
||||||
`linux-package/lib/kitty`. The terminfo file will be installed into
|
|
||||||
`linux-package/share/terminfo`. Simply copy these files into `/usr` to install
|
|
||||||
kitty. In other words, `linux-package` is the staging area into which kitty is
|
|
||||||
installed. You can choose a different staging area, by passing the `--prefix`
|
|
||||||
argument to `setup.py`.
|
|
||||||
|
|
||||||
You should probably split kitty into two packages, `kitty-terminfo` that
|
|
||||||
installs the terminfo file and `kitty` that installs the main program.
|
|
||||||
This allows users to install the terminfo file on servers into which they ssh,
|
|
||||||
without needing to install all of kitty.
|
|
||||||
|
|
||||||
You also need `tic` to compile the terminfo files, it is usually found in the development package of `ncurses`
|
|
||||||
|
|
||||||
This applies to creating packages for kitty for macOS package managers such as
|
|
||||||
brew or MacPorts as well.
|
|
||||||
|
|
||||||
|
|
||||||
== Frequently Asked Questions
|
== Frequently Asked Questions
|
||||||
|
|||||||
20
docs/Makefile
Normal file
20
docs/Makefile
Normal file
@ -0,0 +1,20 @@
|
|||||||
|
# Minimal makefile for Sphinx documentation
|
||||||
|
#
|
||||||
|
|
||||||
|
# You can set these variables from the command line.
|
||||||
|
SPHINXOPTS =
|
||||||
|
SPHINXBUILD = kitty +launch /usr/bin/sphinx-build
|
||||||
|
SPHINXPROJ = kitty
|
||||||
|
SOURCEDIR = .
|
||||||
|
BUILDDIR = _build
|
||||||
|
|
||||||
|
# Put it first so that "make" without argument is like "make help".
|
||||||
|
help:
|
||||||
|
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||||
|
|
||||||
|
.PHONY: help Makefile
|
||||||
|
|
||||||
|
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||||
|
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||||
|
%: Makefile
|
||||||
|
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||||
26
docs/_static/custom.css
vendored
Normal file
26
docs/_static/custom.css
vendored
Normal file
@ -0,0 +1,26 @@
|
|||||||
|
/*
|
||||||
|
* custom.css
|
||||||
|
* Copyright (C) 2018 Kovid Goyal
|
||||||
|
*
|
||||||
|
* Distributed under terms of the MIT license.
|
||||||
|
*/
|
||||||
|
|
||||||
|
.float-left-img {
|
||||||
|
float: left;
|
||||||
|
margin-right: 1em;
|
||||||
|
margin-bottom: 1em;
|
||||||
|
}
|
||||||
|
|
||||||
|
a {
|
||||||
|
text-decoration: none !important;
|
||||||
|
border-bottom: none !important;
|
||||||
|
}
|
||||||
|
|
||||||
|
#searchbox h3 {
|
||||||
|
display: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.major-features li {
|
||||||
|
margin-top: 0.75ex;
|
||||||
|
margin-bottom: 0.75ex;
|
||||||
|
}
|
||||||
22
docs/_templates/searchbox.html
vendored
Normal file
22
docs/_templates/searchbox.html
vendored
Normal file
@ -0,0 +1,22 @@
|
|||||||
|
{#
|
||||||
|
basic/searchbox.html
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Sphinx sidebar template: quick search box.
|
||||||
|
|
||||||
|
:copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
|
||||||
|
:license: BSD, see LICENSE for details.
|
||||||
|
#}
|
||||||
|
{%- if pagename != "search" and builder != "singlehtml" %}
|
||||||
|
<div id="searchbox" style="display: none" role="search">
|
||||||
|
<div class="searchformwrapper">
|
||||||
|
<form class="search" action="{{ pathto('search') }}" method="get">
|
||||||
|
<input type="text" name="q" placeholder="{{ _('Search') }}" />
|
||||||
|
<input type="submit" value="🔍" style="cursor: pointer" />
|
||||||
|
<input type="hidden" name="check_keywords" value="yes" />
|
||||||
|
<input type="hidden" name="area" value="default" />
|
||||||
|
</form>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<script type="text/javascript">$('#searchbox').show(0);</script>
|
||||||
|
{%- endif %}
|
||||||
74
docs/build.rst
Normal file
74
docs/build.rst
Normal file
@ -0,0 +1,74 @@
|
|||||||
|
Building kitty from source
|
||||||
|
==============================
|
||||||
|
|
||||||
|
|kitty| is designed to run from source, for easy hackability. Make sure
|
||||||
|
the following dependencies are installed first.
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
----------------
|
||||||
|
|
||||||
|
* python >= 3.5
|
||||||
|
* harfbuzz >= 1.5.0
|
||||||
|
* zlib
|
||||||
|
* libpng
|
||||||
|
* freetype (not needed on macOS)
|
||||||
|
* fontconfig (not needed on macOS)
|
||||||
|
* ImageMagick (optional, needed to use the ``kitty icat`` tool to display images in the terminal)
|
||||||
|
* pygments (optional, need for syntax highlighting in ``kitty +kitten diff``)
|
||||||
|
* gcc or clang (required only for building)
|
||||||
|
* pkg-config (required only for building)
|
||||||
|
* For building on Linux in addition to the above dependencies you might also need to install the ``-dev`` packages for ``xcursor``, ``xrandr``, ``libxi``, ``xinerama``, ``libgl1-mesa`` and ``xkbcommon-x11``, if they are not already installed by your distro.
|
||||||
|
|
||||||
|
Install and run from source
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
git clone https://github.com/kovidgoyal/kitty && cd kitty
|
||||||
|
|
||||||
|
Now build the native code parts of |kitty| with the following command::
|
||||||
|
|
||||||
|
make
|
||||||
|
|
||||||
|
You can run |kitty|, as::
|
||||||
|
|
||||||
|
python3 .
|
||||||
|
|
||||||
|
If that works, you can create a script to launch |kitty|:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
#!/usr/bin/env python3
|
||||||
|
import runpy
|
||||||
|
runpy.run_path('/path/to/kitty/dir', run_name='__main__')
|
||||||
|
|
||||||
|
And place it in :file:`~/bin` or :file:`/usr/bin` so that you can run |kitty| using
|
||||||
|
just ``kitty``.
|
||||||
|
|
||||||
|
Note for Linux/macOS packagers
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
While kitty does use python, it is not a traditional python package, so please
|
||||||
|
do not install it in site-packages.
|
||||||
|
Instead run::
|
||||||
|
|
||||||
|
python3 setup.py linux-package
|
||||||
|
|
||||||
|
This will install kitty into the directory :file:`linux-package`. You can run kitty
|
||||||
|
with :file:`linux-package/bin/kitty`. All the files needed to run kitty will be in
|
||||||
|
:file:`linux-package/lib/kitty`. The terminfo file will be installed into
|
||||||
|
:file:`linux-package/share/terminfo`. Simply copy these files into :file:`/usr` to install
|
||||||
|
kitty. In other words, :file:`linux-package` is the staging area into which kitty is
|
||||||
|
installed. You can choose a different staging area, by passing the ``--prefix``
|
||||||
|
argument to :file:`setup.py`.
|
||||||
|
|
||||||
|
You should probably split kitty into two packages, :file:`kitty-terminfo` that
|
||||||
|
installs the terminfo file and :file:`kitty` that installs the main program.
|
||||||
|
This allows users to install the terminfo file on servers into which they ssh,
|
||||||
|
without needing to install all of kitty.
|
||||||
|
|
||||||
|
You also need :file:`tic` to compile the terminfo files, it is usually found in
|
||||||
|
the development package of :file:`ncurses`.
|
||||||
|
|
||||||
|
This applies to creating packages for kitty for macOS package managers such as
|
||||||
|
brew or MacPorts as well.
|
||||||
196
docs/conf.py
Normal file
196
docs/conf.py
Normal file
@ -0,0 +1,196 @@
|
|||||||
|
# -*- coding: utf-8 -*-
|
||||||
|
#
|
||||||
|
# Configuration file for the Sphinx documentation builder.
|
||||||
|
#
|
||||||
|
# This file does only contain a selection of the most common options. For a
|
||||||
|
# full list see the documentation:
|
||||||
|
# http://www.sphinx-doc.org/en/master/config
|
||||||
|
|
||||||
|
from collections import defaultdict
|
||||||
|
|
||||||
|
|
||||||
|
def create_shortcut_defs():
|
||||||
|
defns = defaultdict(list)
|
||||||
|
|
||||||
|
for line in open('../kitty/kitty.conf'):
|
||||||
|
if line.startswith('map '):
|
||||||
|
_, sc, name = line.split(maxsplit=2)
|
||||||
|
sc = sc.replace('kitty_mod', 'ctrl+shift')
|
||||||
|
name = name.rstrip().replace(' ', '_').replace('-', '_').replace('+', 'plus').replace('.', '_').replace('___', '_').replace('__', '_').strip('_')
|
||||||
|
defns[name].append(':kbd:`' + sc.replace('>', ' → ') + '`')
|
||||||
|
|
||||||
|
defns = [
|
||||||
|
'.. |sc_{}| replace:: {}'.format(name, ' or '.join(defns[name]))
|
||||||
|
for name in sorted(defns)
|
||||||
|
]
|
||||||
|
return '\n'.join(defns)
|
||||||
|
|
||||||
|
|
||||||
|
# -- Project information -----------------------------------------------------
|
||||||
|
|
||||||
|
project = 'kitty'
|
||||||
|
copyright = '2018, Kovid Goyal'
|
||||||
|
author = 'Kovid Goyal'
|
||||||
|
|
||||||
|
# The short X.Y version
|
||||||
|
version = ''
|
||||||
|
# The full version, including alpha/beta/rc tags
|
||||||
|
release = ''
|
||||||
|
|
||||||
|
|
||||||
|
# -- General configuration ---------------------------------------------------
|
||||||
|
|
||||||
|
# If your documentation needs a minimal Sphinx version, state it here.
|
||||||
|
#
|
||||||
|
needs_sphinx = '1.7'
|
||||||
|
|
||||||
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
|
# ones.
|
||||||
|
extensions = [
|
||||||
|
'sphinx.ext.ifconfig',
|
||||||
|
'sphinx.ext.viewcode',
|
||||||
|
'sphinx.ext.githubpages',
|
||||||
|
]
|
||||||
|
|
||||||
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
|
templates_path = ['_templates']
|
||||||
|
|
||||||
|
# The suffix(es) of source filenames.
|
||||||
|
# You can specify multiple suffix as a list of string:
|
||||||
|
#
|
||||||
|
# source_suffix = ['.rst', '.md']
|
||||||
|
source_suffix = '.rst'
|
||||||
|
|
||||||
|
# The master toctree document.
|
||||||
|
master_doc = 'index'
|
||||||
|
|
||||||
|
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||||
|
# for a list of supported languages.
|
||||||
|
#
|
||||||
|
# This is also used if you do content translation via gettext catalogs.
|
||||||
|
# Usually you set "language" from the command line for these cases.
|
||||||
|
language = None
|
||||||
|
|
||||||
|
# List of patterns, relative to source directory, that match files and
|
||||||
|
# directories to ignore when looking for source files.
|
||||||
|
# This pattern also affects html_static_path and html_extra_path .
|
||||||
|
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||||
|
|
||||||
|
# The name of the Pygments (syntax highlighting) style to use.
|
||||||
|
pygments_style = 'sphinx'
|
||||||
|
|
||||||
|
rst_prolog = '''
|
||||||
|
.. |kitty.conf| replace:: :doc:`kitty.conf </conf>`
|
||||||
|
.. |kitty| replace:: *kitty*
|
||||||
|
|
||||||
|
''' + create_shortcut_defs()
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for HTML output -------------------------------------------------
|
||||||
|
|
||||||
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||||
|
# a list of builtin themes.
|
||||||
|
#
|
||||||
|
html_theme = 'alabaster'
|
||||||
|
|
||||||
|
# Theme options are theme-specific and customize the look and feel of a theme
|
||||||
|
# further. For a list of options available for each theme, see the
|
||||||
|
# documentation.
|
||||||
|
#
|
||||||
|
html_theme_options = {
|
||||||
|
'logo': 'kitty.png',
|
||||||
|
'show_powered_by': False,
|
||||||
|
'fixed_sidebar': True,
|
||||||
|
'sidebar_collapse': True,
|
||||||
|
'analytics_id': 'UA-20736318-1',
|
||||||
|
'github_button': True,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
# Add any paths that contain custom static files (such as style sheets) here,
|
||||||
|
# relative to this directory. They are copied after the builtin static files,
|
||||||
|
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||||
|
html_static_path = ['_static', '../logo/kitty.png']
|
||||||
|
html_context = {
|
||||||
|
'css_files': ['_static/custom.css']
|
||||||
|
}
|
||||||
|
|
||||||
|
# Custom sidebar templates, must be a dictionary that maps document names
|
||||||
|
# to template names.
|
||||||
|
#
|
||||||
|
# The default sidebars (for documents that don't match any pattern) are
|
||||||
|
# defined by theme itself. Builtin themes are using these templates by
|
||||||
|
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
|
||||||
|
# 'searchbox.html']``.
|
||||||
|
#
|
||||||
|
html_sidebars = {
|
||||||
|
'**': [
|
||||||
|
'about.html',
|
||||||
|
'searchbox.html',
|
||||||
|
'localtoc.html',
|
||||||
|
'relations.html',
|
||||||
|
]
|
||||||
|
}
|
||||||
|
html_show_sourcelink = False
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for HTMLHelp output ---------------------------------------------
|
||||||
|
|
||||||
|
# Output file base name for HTML help builder.
|
||||||
|
htmlhelp_basename = 'kittydoc'
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for LaTeX output ------------------------------------------------
|
||||||
|
|
||||||
|
latex_elements = {
|
||||||
|
# The paper size ('letterpaper' or 'a4paper').
|
||||||
|
#
|
||||||
|
# 'papersize': 'letterpaper',
|
||||||
|
|
||||||
|
# The font size ('10pt', '11pt' or '12pt').
|
||||||
|
#
|
||||||
|
# 'pointsize': '10pt',
|
||||||
|
|
||||||
|
# Additional stuff for the LaTeX preamble.
|
||||||
|
#
|
||||||
|
# 'preamble': '',
|
||||||
|
|
||||||
|
# Latex figure (float) alignment
|
||||||
|
#
|
||||||
|
# 'figure_align': 'htbp',
|
||||||
|
}
|
||||||
|
|
||||||
|
# Grouping the document tree into LaTeX files. List of tuples
|
||||||
|
# (source start file, target name, title,
|
||||||
|
# author, documentclass [howto, manual, or own class]).
|
||||||
|
latex_documents = [
|
||||||
|
(master_doc, 'kitty.tex', 'kitty Documentation',
|
||||||
|
'Kovid Goyal', 'manual'),
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for manual page output ------------------------------------------
|
||||||
|
|
||||||
|
# One entry per manual page. List of tuples
|
||||||
|
# (source start file, name, description, authors, manual section).
|
||||||
|
man_pages = [
|
||||||
|
(master_doc, 'kitty', 'kitty Documentation',
|
||||||
|
[author], 1)
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
# -- Options for Texinfo output ----------------------------------------------
|
||||||
|
|
||||||
|
# Grouping the document tree into Texinfo files. List of tuples
|
||||||
|
# (source start file, target name, title, author,
|
||||||
|
# dir menu entry, description, category)
|
||||||
|
texinfo_documents = [
|
||||||
|
(master_doc, 'kitty', 'kitty Documentation',
|
||||||
|
author, 'kitty', 'One line description of project.',
|
||||||
|
'Miscellaneous'),
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
def setup(app):
|
||||||
|
pass
|
||||||
23
docs/conf.rst
Normal file
23
docs/conf.rst
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
Configuring kitty
|
||||||
|
===============================
|
||||||
|
|
||||||
|
|kitty| is highly customizable, everything from keyboard shortcuts, to painting
|
||||||
|
frames-per-second. See the heavily commented default config file below for an
|
||||||
|
overview of all customization possibilities.
|
||||||
|
|
||||||
|
You can open the config file within kitty by pressing |sc_edit_config_file|.
|
||||||
|
You can also display the current configuration by running ``kitty
|
||||||
|
--debug-config``.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. literalinclude:: ../kitty/kitty.conf
|
||||||
|
:language: ini
|
||||||
|
|
||||||
|
|
||||||
|
|kitty| looks for a config file in the OS config directories (usually
|
||||||
|
:file:`~/.config/kitty/kitty.conf` and additionally
|
||||||
|
:file:`~/Library/Preferences/kitty/kitty.conf` on macOS) but you can pass a
|
||||||
|
specific path via the ``--config`` option or use the ``KITTY_CONFIG_DIRECTORY``
|
||||||
|
environment variable. See the help for the :option:`--config` option in ``kitty
|
||||||
|
--help`` for full details.
|
||||||
114
docs/faq.rst
Normal file
114
docs/faq.rst
Normal file
@ -0,0 +1,114 @@
|
|||||||
|
Frequently Asked Questions
|
||||||
|
==============================
|
||||||
|
|
||||||
|
.. highlight:: sh
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Some special symbols are rendered small/truncated in kitty?
|
||||||
|
-----------------------------------------------------------------
|
||||||
|
|
||||||
|
The number of cells a unicode character takes up are controlled by the unicode
|
||||||
|
standard. All characters are rendered in a single cell unless the unicode
|
||||||
|
standard says they should be rendered in two cells. When a symbol does not fit,
|
||||||
|
it will either be rescaled to be smaller or truncated (depending on how much
|
||||||
|
extra space it needs). This is often different from other terminals which just
|
||||||
|
let the character overflow into neighboring cells, which is fine if the
|
||||||
|
neighboring cell is empty, but looks terrible if it is not.
|
||||||
|
|
||||||
|
Some programs, like powerline, vim with fancy gutter symbols/status-bar, etc.
|
||||||
|
misuse unicode characters from the private use area to represent symbols. Often
|
||||||
|
these symbols are square and should be rendered in two cells. However, since
|
||||||
|
private use area symbols all have their width set to one in the unicode
|
||||||
|
standard, |kitty| renders them either smaller or truncated. The exception is if
|
||||||
|
these characters are followed by a space or empty cell in which case kitty
|
||||||
|
makes use of the extra cell to render them in two cells.
|
||||||
|
|
||||||
|
|
||||||
|
How do I build kitty.app on macOS?
|
||||||
|
----------------------------------------
|
||||||
|
|
||||||
|
Install `imagemagick`, `optipng` and `librsvg` using `brew` or similar (needed
|
||||||
|
for the logo generation step). And run::
|
||||||
|
|
||||||
|
make app
|
||||||
|
|
||||||
|
This :file:`kitty.app` unlike the released one does not include its own copy of
|
||||||
|
python and the other dependencies. So if you ever un-install/upgrade those dependencies
|
||||||
|
you might have to rebuild the app.
|
||||||
|
|
||||||
|
Note that the released :file:`kitty.dmg` includes all dependencies, unlike the
|
||||||
|
:file:`kitty.app` built above and is built automatically by using the :file:`kitty` branch of
|
||||||
|
`build-calibre <https://github.com/kovidgoyal/build-calibre>`_ however, that
|
||||||
|
is designed to run on Linux and is not for the faint of heart.
|
||||||
|
|
||||||
|
|
||||||
|
Using a color theme with a background color does not work well in vim?
|
||||||
|
-----------------------------------------------------------------------
|
||||||
|
|
||||||
|
First make sure you have not changed the TERM environment variable, it should
|
||||||
|
be ``xterm-kitty``. vim uses *background color erase* even if the terminfo file
|
||||||
|
does not contain the ``bce`` capability. This is a bug in vim. You can work around
|
||||||
|
it by adding the following to your vimrc::
|
||||||
|
|
||||||
|
let &t_ut=''
|
||||||
|
|
||||||
|
|
||||||
|
See `here <https://github.com/kovidgoyal/kitty/blob/master/protocol-extensions.asciidoc#setting-text-styles-colors-in-arbitrary-regions-of-the-screen>`_ for why |kitty| does not support background color erase.
|
||||||
|
|
||||||
|
I get errors about the terminal being unknown or opening the terminal failing when SSHing into a different computer?
|
||||||
|
-----------------------------------------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
This happens because the |kitty| terminfo files are not available on the server.
|
||||||
|
You can ssh in using the following command which will automatically copy the
|
||||||
|
terminfo files to the server::
|
||||||
|
|
||||||
|
kitty +kitten ssh myserver
|
||||||
|
|
||||||
|
If for some reason that does not work (typically because the server is using a
|
||||||
|
very limited shell), you can use the following one-liner instead (it is slower
|
||||||
|
as it needs to ssh into the server twice, but will work with most servers)::
|
||||||
|
|
||||||
|
infocmp xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin
|
||||||
|
|
||||||
|
Really, the correct solution for this is to convince the OpenSSH maintainers to
|
||||||
|
have ssh do this automatically when connecting to a server, so that all
|
||||||
|
terminals work transparently.
|
||||||
|
|
||||||
|
|
||||||
|
How do I change the colors in a running kitty instance?
|
||||||
|
------------------------------------------------------------
|
||||||
|
|
||||||
|
You can either use the
|
||||||
|
`OSC terminal escape codes <http://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Operating-System-Commands>`_
|
||||||
|
to set colors or you can enable :doc:`remote control <remote-control>`
|
||||||
|
for |kitty| and use ``kitty @ set-colors --help``.
|
||||||
|
|
||||||
|
|
||||||
|
How do I specify command line options for kitty on macOS?
|
||||||
|
---------------------------------------------------------------
|
||||||
|
|
||||||
|
Apple does not want you to use command line options with GUI applications. To
|
||||||
|
workaround that limitation, |kitty| will read command line options from the file
|
||||||
|
:file:`<kitty config dir>/macos-launch-services-cmdline` when it is launched
|
||||||
|
from the GUI, i.e. by clicking the |kitty| application icon or using ``open -a kitty``.
|
||||||
|
Note that this file is *only read* when running via the GUI.
|
||||||
|
|
||||||
|
You can, of course, also run |kitty| from a terminal with command line options, using:
|
||||||
|
:file:`/Applications/kitty.app/Contents/MacOS/kitty`.
|
||||||
|
|
||||||
|
And within |kitty| itself, you can always run |kitty| using just `kitty` as it
|
||||||
|
cleverly adds itself to the ``PATH``.
|
||||||
|
|
||||||
|
|
||||||
|
kitty is not able to use my favorite font?
|
||||||
|
---------------------------------------------
|
||||||
|
|
||||||
|
|kitty| achieves its stellar performance by caching alpha masks of each rendered
|
||||||
|
character on the GPU, so that every character needs to be rendered only once.
|
||||||
|
This means it is a strictly character cell based display. As such it can use
|
||||||
|
only monospace fonts, since every cell in the grid has to be the same size. If
|
||||||
|
your font is not listed in ``kitty list-fonts`` it means that it is not
|
||||||
|
monospace. On Linux you can list all monospace fonts with::
|
||||||
|
|
||||||
|
fc-list : family spacing | grep spacing=100
|
||||||
396
docs/graphics-protocol.rst
Normal file
396
docs/graphics-protocol.rst
Normal file
@ -0,0 +1,396 @@
|
|||||||
|
The terminal graphics protocol
|
||||||
|
==================================
|
||||||
|
|
||||||
|
The goal of this specification is to create a flexible and performant protocol
|
||||||
|
that allows the program running in the terminal, hereafter called the *client*,
|
||||||
|
to render arbitrary pixel (raster) graphics to the screen of the terminal
|
||||||
|
emulator. The major design goals are
|
||||||
|
|
||||||
|
* Should not require terminal emulators to understand image formats.
|
||||||
|
* Should allow specifying graphics to be drawn at individual pixel positions.
|
||||||
|
* The graphics should integrate with the text, in particular it should be possible to draw graphics
|
||||||
|
below as well as above the text, with alpha blending. The graphics should also scroll with the text, automatically.
|
||||||
|
* Should use optimizations when the client is running on the same computer as the terminal emulator.
|
||||||
|
|
||||||
|
For some discussion regarding the design choices, see `#33
|
||||||
|
<https://github.com/kovidgoyal/kitty/issues/33>`_.
|
||||||
|
|
||||||
|
To see a quick demo, inside a |kitty| terminal run::
|
||||||
|
|
||||||
|
kitty icat path/to/some/image.png
|
||||||
|
|
||||||
|
You can also see a screenshot with more sophisticated features such as
|
||||||
|
alpha-blending and text over graphics.
|
||||||
|
|
||||||
|
.. image:: https://user-images.githubusercontent.com/1308621/31647475-1188ab66-b326-11e7-8d26-24b937f1c3e8.png
|
||||||
|
:alt: Demo of graphics rendering in kitty
|
||||||
|
:align: center
|
||||||
|
|
||||||
|
Some programs that use the kitty graphics protocol:
|
||||||
|
|
||||||
|
* `termpdf <https://github.com/dsanson/termpdf>`_ - a terminal PDF/DJVU/CBR viewer
|
||||||
|
* `ranger <https://github.com/ranger/ranger>`_ - a terminal file manager, with
|
||||||
|
image previews, see this `PR <https://github.com/ranger/ranger/pull/1077>`_
|
||||||
|
* :doc:`kitty-diff <kittens/diff>` - a side-by-side terminal diff program with support for images
|
||||||
|
* `neofetch <https://github.com/dylanaraps/neofetch>`_ - A command line system
|
||||||
|
information tool
|
||||||
|
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
|
||||||
|
Getting the window size
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
In order to know what size of images to display and how to position them, the
|
||||||
|
client must be able to get the window size in pixels and the number of cells
|
||||||
|
per row and column. This can be done by using the ``TIOCGWINSZ`` ioctl. Some
|
||||||
|
code to demonstrate its use
|
||||||
|
|
||||||
|
In C:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
struct ttysize ts;
|
||||||
|
ioctl(0, TIOCGWINSZ, &ts);
|
||||||
|
printf("number of columns: %i, number of rows: %i, screen width: %i, screen height: %i\n", sz.ws_col, sz.ws_row, sz.ws_xpixel, sz.ws_ypixel);
|
||||||
|
|
||||||
|
In Python:
|
||||||
|
|
||||||
|
.. code-block:: python
|
||||||
|
|
||||||
|
import array, fcntl, termios
|
||||||
|
buf = array.array('H', [0, 0, 0, 0])
|
||||||
|
fcntl.ioctl(sys.stdout, termios.TIOCGWINSZ, buf)
|
||||||
|
print('number of columns: {}, number of rows: {}, screen width: {}, screen height: {}'.format(*buf))
|
||||||
|
|
||||||
|
Note that some terminals return ``0`` for the width and height values. Such
|
||||||
|
terminals should be modified to return the correct values. Examples of
|
||||||
|
terminals that return correct values: ``kitty, xterm``
|
||||||
|
|
||||||
|
You can also use the *CSI t* escape code to get the screen size. Send
|
||||||
|
``<ESC>[14t`` to *stdout* and kitty will reply on *stdin* with
|
||||||
|
``<ESC>[4;<height>;<width>t`` where *height* and *width* are the window size in
|
||||||
|
pixels. This escape code is supported in many terminals, not just kitty.
|
||||||
|
|
||||||
|
The graphics escape code
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
All graphics escape codes are of the form::
|
||||||
|
|
||||||
|
<ESC>_G<control data>;<payload><ESC>\
|
||||||
|
|
||||||
|
This is a so-called *Application Programming Command (APC)*. Most terminal
|
||||||
|
emulators ignore APC codes, making it safe to use.
|
||||||
|
|
||||||
|
The control data is a comma-separated list of ``key=value`` pairs. The payload
|
||||||
|
is arbitrary binary data, base64-encoded to prevent interoperation problems
|
||||||
|
with legacy terminals that get confused by control codes within an APC code.
|
||||||
|
The meaning of the payload is interpreted based on the control data.
|
||||||
|
|
||||||
|
The first step is to transmit the actual image data.
|
||||||
|
|
||||||
|
Transferring pixel data
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
The first consideration when transferring data between the client and the
|
||||||
|
terminal emulator is the format in which to do so. Since there is a vast and
|
||||||
|
growing number of image formats in existence, it does not make sense to have
|
||||||
|
every terminal emulator implement support for them. Instead, the client should
|
||||||
|
send simple pixel data to the terminal emulator. The obvious downside to this
|
||||||
|
is performance, especially when the client is running on a remote machine.
|
||||||
|
Techniques for remedying this limitation are discussed later. The terminal
|
||||||
|
emulator must understand pixel data in three formats, 24-bit RGB, 32-bit RGBA and
|
||||||
|
PNG. This is specified using the ``f`` key in the control data. ``f=32`` (which is the
|
||||||
|
default) indicates 32-bit RGBA data and ``f=24`` indicates 24-bit RGB data and ``f=100``
|
||||||
|
indicates PNG data. The PNG format is supported for convenience and a compact way
|
||||||
|
of transmitting paletted images.
|
||||||
|
|
||||||
|
RGB and RGBA data
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
In these formats the pixel data is stored directly as 3 or 4 bytes per pixel, respectively.
|
||||||
|
When specifying images in this format, the image dimensions **must** be sent in the control data.
|
||||||
|
For example::
|
||||||
|
|
||||||
|
<ESC>_Gf=24,s=10,v=20;<payload><ESC>\
|
||||||
|
|
||||||
|
Here the width and height are specified using the ``s`` and ``v`` keys respectively. Since
|
||||||
|
``f=24`` there are three bytes per pixel and therefore the pixel data must be ``3 * 10 * 20 = 600``
|
||||||
|
bytes.
|
||||||
|
|
||||||
|
PNG data
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
In this format any PNG image can be transmitted directly. For example::
|
||||||
|
|
||||||
|
<ESC>_Gf=100;<payload><ESC>\
|
||||||
|
|
||||||
|
|
||||||
|
The PNG format is specified using the ``f=100`` key. The width and height of
|
||||||
|
the image will be read from the PNG data itself. Note that if you use both PNG and
|
||||||
|
compression, then you must provide the ``S`` key with the size of the PNG data.
|
||||||
|
|
||||||
|
|
||||||
|
Compression
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The client can send compressed image data to the terminal emulator, by specifying the
|
||||||
|
``o`` key. Currently, only zlib based deflate compression is supported, which is specified using
|
||||||
|
``o=z``. For example::
|
||||||
|
|
||||||
|
<ESC>_Gf=24,s=10,v=20,o=z;<payload><ESC>\
|
||||||
|
|
||||||
|
This is the same as the example from the RGB data section, except that the
|
||||||
|
payload is now compressed using deflate. The terminal emulator will decompress
|
||||||
|
it before rendering. You can specify compression for any format. The terminal
|
||||||
|
emulator will decompress before interpreting the pixel data.
|
||||||
|
|
||||||
|
|
||||||
|
The transmission medium
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The transmission medium is specified using the ``t`` key. The ``t`` key defaults to ``d``
|
||||||
|
and can take the values:
|
||||||
|
|
||||||
|
================== ============
|
||||||
|
Value of `t` Meaning
|
||||||
|
================== ============
|
||||||
|
``d`` Direct (the data is transmitted within the escape code itself)
|
||||||
|
``f`` A simple file
|
||||||
|
``t`` A temporary file, the terminal emulator will delete the file after reading the pixel data
|
||||||
|
``s`` A `POSIX shared memory object <http://man7.org/linux/man-pages/man7/shm_overview.7.html>`_.
|
||||||
|
The terminal emulator will delete it after reading the pixel data
|
||||||
|
================== ============
|
||||||
|
|
||||||
|
Local client
|
||||||
|
^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
First let us consider the local client techniques (files and shared memory). Some examples::
|
||||||
|
|
||||||
|
<ESC>_Gf=100,t=f;<encoded /path/to/file.png><ESC>\
|
||||||
|
|
||||||
|
Here we tell the terminal emulator to read PNG data from the specified file of
|
||||||
|
the specified size::
|
||||||
|
|
||||||
|
<ESC>_Gs=10,v=2,t=s,o=z;<encoded /some-shared-memory-name><ESC>\
|
||||||
|
|
||||||
|
Here we tell the terminal emulator to read compressed image data from
|
||||||
|
the specified shared memory object.
|
||||||
|
|
||||||
|
The client can also specify a size and offset to tell the terminal emulator
|
||||||
|
to only read a part of the specified file. The is done using the ``S`` and ``O``
|
||||||
|
keys respectively. For example::
|
||||||
|
|
||||||
|
<ESC>_Gs=10,v=2,t=s,S=80,O=10;<encoded /some-shared-memory-name><ESC>\
|
||||||
|
|
||||||
|
This tells the terminal emulator to read ``80`` bytes starting from the offset ``10``
|
||||||
|
inside the specified shared memory buffer.
|
||||||
|
|
||||||
|
|
||||||
|
Remote client
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Remote clients, those that are unable to use the filesystem/shared memory to
|
||||||
|
transmit data, must send the pixel data directly using escape codes. Since
|
||||||
|
escape codes are of limited maximum length, the data will need to be chunked up
|
||||||
|
for transfer. This is done using the ``m`` key. The pixel data must first be
|
||||||
|
base64 encoded then chunked up into chunks no larger than ``4096`` bytes. The client
|
||||||
|
then sends the graphics escape code as usual, with the addition of an ``m`` key that
|
||||||
|
must have the value ``1`` for all but the last chunk, where it must be ``0``. For example,
|
||||||
|
if the data is split into three chunks, the client would send the following
|
||||||
|
sequence of escape codes to the terminal emulator::
|
||||||
|
|
||||||
|
<ESC>_Gs=100,v=30,m=1;<encoded pixel data first chunk><ESC>\
|
||||||
|
<ESC>_Gm=1;<encoded pixel data second chunk><ESC>\
|
||||||
|
<ESC>_Gm=0;<encoded pixel data last chunk><ESC>\
|
||||||
|
|
||||||
|
Note that only the first escape code needs to have the full set of control
|
||||||
|
codes such as width, height, format etc. Subsequent chunks must have
|
||||||
|
only the ``m`` key. The client **must** finish sending all chunks for a single image
|
||||||
|
before sending any other graphics related escape codes.
|
||||||
|
|
||||||
|
|
||||||
|
Detecting available transmission mediums
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Since a client has no a-priori knowledge of whether it shares a filesystem/shared memory
|
||||||
|
with the terminal emulator, it can send an id with the control data, using the ``i`` key
|
||||||
|
(which can be an arbitrary positive integer up to 4294967295, it must not be zero).
|
||||||
|
If it does so, the terminal emulator will reply after trying to load the image, saying
|
||||||
|
whether loading was successful or not. For example::
|
||||||
|
|
||||||
|
<ESC>_Gi=31,s=10,v=2,t=s;<encoded /some-shared-memory-name><ESC>\
|
||||||
|
|
||||||
|
to which the terminal emulator will reply (after trying to load the data)::
|
||||||
|
|
||||||
|
<ESC>_Gi=31;error message or OK<ESC>\
|
||||||
|
|
||||||
|
Here the ``i`` value will be the same as was sent by the client in the original
|
||||||
|
request. The message data will be a ASCII encoded string containing only
|
||||||
|
printable characters and spaces. The string will be ``OK`` if reading the pixel
|
||||||
|
data succeeded or an error message.
|
||||||
|
|
||||||
|
Sometimes, using an id is not appropriate, for example, if you do not want to
|
||||||
|
replace a previously sent image with the same id, or if you are sending a dummy
|
||||||
|
image and do not want it stored by the terminal emulator. In that case, you can
|
||||||
|
use the *query action*, set ``a=q``. Then the terminal emulator will try to load
|
||||||
|
the image and respond with either OK or an error, as above, but it will not
|
||||||
|
replace an existing image with the same id, nor will it store the image.
|
||||||
|
|
||||||
|
|
||||||
|
Display images on screen
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
Every transmitted image can be displayed an arbitrary number of times on the
|
||||||
|
screen, in different locations, using different parts of the source image, as
|
||||||
|
needed. You can either simultaneously transmit and display an image using the
|
||||||
|
action ``a=T``, or first transmit the image with a id, such as ``i=10`` and then display
|
||||||
|
it with ``a=p,i=10`` which will display the previously transmitted image at the current
|
||||||
|
cursor position. When specifying an image id, the terminal emulator will reply with an
|
||||||
|
acknowledgement code, which will be either::
|
||||||
|
|
||||||
|
<ESC>_Gi=<id>;OK<ESC>\
|
||||||
|
|
||||||
|
when the image referred to by id was found, or::
|
||||||
|
|
||||||
|
<ESC>_Gi=<id>;ENOENT:<some detailed error msg><ESC>\
|
||||||
|
|
||||||
|
when the image with the specified id was not found. This is similar to the
|
||||||
|
scheme described above for querying available transmission media, except that
|
||||||
|
here we are querying if the image with the specified id is available or needs to
|
||||||
|
be re-transmitted.
|
||||||
|
|
||||||
|
Controlling displayed image layout
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The image is rendered at the current cursor position, from the upper left corner of
|
||||||
|
the current cell. You can also specify extra ``X=3`` and ``Y=4`` pixel offsets to display from
|
||||||
|
a different origin within the cell. Note that the offsets must be smaller that the size of the cell.
|
||||||
|
|
||||||
|
By default, the entire image will be displayed (images wider than the available
|
||||||
|
width will be truncated on the right edge). You can choose a source rectangle (in pixels)
|
||||||
|
as the part of the image to display. This is done with the keys: ``x, y, w, h`` which specify
|
||||||
|
the top-left corner, width and height of the source rectangle.
|
||||||
|
|
||||||
|
You can also ask the terminal emulator to display the image in a specified rectangle
|
||||||
|
(num of columns / num of lines), using the control codes ``c,r``. ``c`` is the number of columns
|
||||||
|
and `r` the number of rows. The image will be scaled (enlarged/shrunk) as needed to fit
|
||||||
|
the specified area. Note that if you specify a start cell offset via the ``X,Y`` keys, it is not
|
||||||
|
added to the number of rows/columns.
|
||||||
|
|
||||||
|
Finally, you can specify the image *z-index*, i.e. the vertical stacking order. Images
|
||||||
|
placed in the same location with different z-index values will be blended if
|
||||||
|
they are semi-transparent. You can specify z-index values using the ``z`` key.
|
||||||
|
Negative z-index values mean that the images will be drawn under the text. This
|
||||||
|
allows rendering of text on top of images.
|
||||||
|
|
||||||
|
Deleting images
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Images can be deleted by using the delete action ``a=d``. If specified without any
|
||||||
|
other keys, it will delete all images visible on screen. To delete specific images,
|
||||||
|
use the `d` key as described in the table below. Note that each value of d has
|
||||||
|
both a lowercase and an uppercase variant. The lowercase variant only deletes the
|
||||||
|
images without necessarily freeing up the stored image data, so that the images can be
|
||||||
|
re-displayed without needing to resend the data. The uppercase variants will delete
|
||||||
|
the image data as well, provided that the image is not referenced elsewhere, such as in the
|
||||||
|
scrollback buffer. The values of the ``x`` and ``y`` keys are the same as cursor positions (i.e.
|
||||||
|
``x=1, y=1`` is the top left cell).
|
||||||
|
|
||||||
|
================= ============
|
||||||
|
Value of ``d`` Meaning
|
||||||
|
================= ============
|
||||||
|
``a`` or ``A`` Delete all images visible on screen
|
||||||
|
``i`` or ``I`` Delete all images with the specified id, specified using the ``i`` key.
|
||||||
|
``c`` or ``C`` Delete all images that intersect with the current cursor position.
|
||||||
|
``p`` or ``P`` Delete all images that intersect a specific cell, the cell is specified using the ``x`` and ``y`` keys
|
||||||
|
``q`` or ``Q`` Delete all images that intersect a specific cell having a specific z-index. The cell and z-index is specified using the ``x``, ``y`` and ``z`` keys.
|
||||||
|
``x`` or ``X`` Delete all images that intersect the specified column, specified using the ``x`` key.
|
||||||
|
``y`` or ``Y`` Delete all images that intersect the specified row, specified using the ``y`` key.
|
||||||
|
``z`` or ``Z`` Delete all images that have the specified z-index, specified using the ``z`` key.
|
||||||
|
================= ============
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Some examples::
|
||||||
|
|
||||||
|
<ESC>_Ga=d<ESC>\ # delete all visible images
|
||||||
|
<ESC>_Ga=d,i=10<ESC>\ # delete the image with id=10
|
||||||
|
<ESC>_Ga=Z,z=-1<ESC>\ # delete the images with z-index -1, also freeing up image data
|
||||||
|
<ESC>_Ga=P,x=3,y=4<ESC>\ # delete all images that intersect the cell at (3, 4)
|
||||||
|
|
||||||
|
Image persistence and storage quotas
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
In order to avoid *Denial-of-Service* attacks, terminal emulators should have a
|
||||||
|
maximum storage quota for image data. It should allow at least a few full
|
||||||
|
screen images. For example the quota in kitty is 320MB per buffer. When adding
|
||||||
|
a new image, if the total size exceeds the quota, the terminal emulator should
|
||||||
|
delete older images to make space for the new one.
|
||||||
|
|
||||||
|
|
||||||
|
Control data reference
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
The table below shows all the control data keys as well as what values they can
|
||||||
|
take, and the default value they take when missing. All integers are 32-bit.
|
||||||
|
|
||||||
|
======= ==================== ========= =================
|
||||||
|
Key Value Default Description
|
||||||
|
======= ==================== ========= =================
|
||||||
|
``a`` Single character. ``t`` The overall action this graphics command is performing.
|
||||||
|
``(t, T, q, p, d)``
|
||||||
|
**Keys for image transmission**
|
||||||
|
-----------------------------------------------------------
|
||||||
|
``f`` Positive integer. ``32`` The format in which the image data is sent.
|
||||||
|
``(24, 32, 100)``.
|
||||||
|
``t`` Single character. ``d`` The transmission medium used.
|
||||||
|
``(d, f, t, s)``.
|
||||||
|
``s`` Positive integer. ``0`` The width of the image being sent.
|
||||||
|
``v`` Positive integer. ``0`` The height of the image being sent.
|
||||||
|
``S`` Positive integer. ``0`` The size of data to read from a file.
|
||||||
|
``O`` Positive integer. ``0`` The offset from which to read data from a file.
|
||||||
|
``i`` Positive integer.
|
||||||
|
``(0 - 4294967295)`` ``0`` The image id
|
||||||
|
``o`` Single character. ``null`` The type of data compression.
|
||||||
|
``only z``
|
||||||
|
``m`` zero or one ``0`` Whether there is more chunked data available.
|
||||||
|
**Keys for image display**
|
||||||
|
-----------------------------------------------------------
|
||||||
|
``x`` Positive integer ``0`` The left edge (in pixels) of the image area to display
|
||||||
|
``y`` Positive integer ``0`` The top edge (in pixels) of the image area to display
|
||||||
|
``w`` Positive integer ``0`` The width (in pixels) of the image area to display. By default, the entire width is used.
|
||||||
|
``h`` Positive integer ``0`` The height (in pixels) of the image area to display. By default, the entire height is used
|
||||||
|
``X`` Positive integer ``0`` The x-offset within the first cell at which to start displaying the image
|
||||||
|
``Y`` Positive integer ``0`` The y-offset within the first cell at which to start displaying the image
|
||||||
|
``c`` Positive integer ``0`` The number of columns to display the image over
|
||||||
|
``r`` Positive integer ``0`` The number of rows to display the image over
|
||||||
|
``z`` Integer ``0`` The *z-index* vertical stacking order of the image
|
||||||
|
**Keys for deleting images**
|
||||||
|
-----------------------------------------------------------
|
||||||
|
``d`` Single character. ``a`` What to delete.
|
||||||
|
``(a, A, c, C, p,
|
||||||
|
P, q, Q, x, X, y,
|
||||||
|
Y, z, Z)``.
|
||||||
|
======= ==================== ========= =================
|
||||||
|
|
||||||
|
|
||||||
|
Interaction with other terminal actions
|
||||||
|
--------------------------------------------
|
||||||
|
|
||||||
|
When resetting the terminal, all images that are visible on the screen must be
|
||||||
|
cleared. When switching from the main screen to the alternate screen buffer
|
||||||
|
(1049 private mode) all images in the alternate screen must be cleared, just as
|
||||||
|
all text is cleared. The clear screen escape code (usually ``<ESC>[2J``) should
|
||||||
|
also clear all images. This is so that the clear command works.
|
||||||
|
|
||||||
|
The other commands to erase text must have no effect on graphics.
|
||||||
|
The dedicated delete graphics commands must be used for those.
|
||||||
|
|
||||||
|
When scrolling the screen (such as when using index cursor movement commands,
|
||||||
|
or scrolling through the history buffer), images must be scrolled along with
|
||||||
|
text. When page margins are defined and the index commands are used, only
|
||||||
|
images that are entirely within the page area (between the margins) must be
|
||||||
|
scrolled. When scrolling them would cause them to extend outside the page area,
|
||||||
|
they must be clipped.
|
||||||
292
docs/index.rst
Normal file
292
docs/index.rst
Normal file
@ -0,0 +1,292 @@
|
|||||||
|
==========================================================
|
||||||
|
kitty - the fast, featureful, GPU based, terminal emulator
|
||||||
|
==========================================================
|
||||||
|
|
||||||
|
.. container:: major-features
|
||||||
|
|
||||||
|
* Offloads rendering to the GPU for :doc:`lower system load <performance>` and
|
||||||
|
buttery smooth scrolling. Uses threaded rendering to minimize input latency.
|
||||||
|
|
||||||
|
* Supports all modern terminal features: :doc:`graphics (images)
|
||||||
|
<graphics-protocol>`, unicode, true-color, OpenType ligatures, mouse
|
||||||
|
protocol, focus tracking, bracketed paste and so on.
|
||||||
|
|
||||||
|
* Supports tiling multiple terminal windows side by side in different
|
||||||
|
:ref:`layouts <layouts>` without needing to use an extra program like tmux
|
||||||
|
|
||||||
|
* Can be :doc:`controlled from scripts or the shell prompt <remote-control>`,
|
||||||
|
even over SSH.
|
||||||
|
|
||||||
|
* Has a framework for *kittens*, small terminal programs that can be used to
|
||||||
|
extend |kitty|'s functionality. For example, they are used for
|
||||||
|
:doc:`Unicode input <kittens/unicode-input>`, :doc:`Hints <kittens/hints>` and
|
||||||
|
:doc:`Side-by-side diff <kittens/diff>`.
|
||||||
|
|
||||||
|
* Supports :ref:`startup sessions <sessions>` which allow you to specify
|
||||||
|
the window/tab layout, working directories and programs to run on startup.
|
||||||
|
|
||||||
|
* Cross-platform: |kitty| works on Linux and macOS, but because it uses only
|
||||||
|
OpenGL for rendering, it should be trivial to port to other platforms.
|
||||||
|
|
||||||
|
* Allows you to open :ref:`the scrollback buffer <scrollback>` in a
|
||||||
|
separate window using arbitrary programs of your choice. This is useful for
|
||||||
|
browsing the history comfortably in a pager or editor.
|
||||||
|
|
||||||
|
|
||||||
|
.. figure:: screenshots/screenshot.png
|
||||||
|
:alt: Screenshot, showing three programs in the 'Tall' layout
|
||||||
|
:align: center
|
||||||
|
|
||||||
|
Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout
|
||||||
|
|
||||||
|
|
||||||
|
Quickstart
|
||||||
|
--------------
|
||||||
|
|
||||||
|
If you are on macOS, simply download and install the ``.dmg`` from the `releases
|
||||||
|
page <https://github.com/kovidgoyal/kitty/releases>`_.
|
||||||
|
|
||||||
|
If you are on Linux, install the |kitty| package if your distro provides it,
|
||||||
|
otherwise follow the :doc:`Build from source instructions <build>`. |kitty|
|
||||||
|
packages are available for:
|
||||||
|
`Debian <https://packages.debian.org/buster/kitty>`_,
|
||||||
|
`openSUSE <https://build.opensuse.org/package/show/X11:terminals/kitty>`_,
|
||||||
|
`Arch Linux <https://www.archlinux.org/packages/community/x86_64/kitty/>`_,
|
||||||
|
`NixOS <https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/kitty/default.nix>`_,
|
||||||
|
`Gentoo <https://packages.gentoo.org/packages/x11-terms/kitty>`_,
|
||||||
|
`Fedora <https://copr.fedorainfracloud.org/coprs/oleastre/kitty-terminal/>`_.
|
||||||
|
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
|
||||||
|
Design philosophy
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
|kitty| is designed for power keyboard users. To that end all its controls
|
||||||
|
work with the keyboard (although it fully supports mouse interactions as
|
||||||
|
well). Its configuration is a simple, human editable, single file for
|
||||||
|
easy reproducibility (I like to store configuration in source control).
|
||||||
|
|
||||||
|
The code in |kitty| is designed to be simple, modular and hackable. It is
|
||||||
|
written in a mix of C (for performance sensitive parts) and Python (for
|
||||||
|
easy hackability of the UI). It does not depend on any large and complex
|
||||||
|
UI toolkit, using only OpenGL for rendering everything.
|
||||||
|
|
||||||
|
Finally, |kitty| is designed from the ground up to support all modern
|
||||||
|
terminal features, such as unicode, true color, bold/italic fonts, text
|
||||||
|
formatting, etc. It even extends existing text formatting escape codes,
|
||||||
|
to add support for features not available elsewhere, such as colored and
|
||||||
|
styled (curly) underlines. One of the design goals of |kitty| is to be
|
||||||
|
easily extensible so that new features can be added in the future with
|
||||||
|
relatively less effort.
|
||||||
|
|
||||||
|
Tabs and Windows
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
|kitty| is capable of running multiple programs organized into tabs and
|
||||||
|
windows. The top level of organization is the *Tab*. Each tab consists
|
||||||
|
of one or more *windows*. The windows can be arranged in multiple
|
||||||
|
different layouts, like windows are organized in a tiling window
|
||||||
|
manager. The keyboard controls (which are all customizable) for tabs and
|
||||||
|
windows are:
|
||||||
|
|
||||||
|
Scrolling
|
||||||
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
======================== =======================
|
||||||
|
Action Shortcut
|
||||||
|
======================== =======================
|
||||||
|
Scroll line up |sc_scroll_line_up|
|
||||||
|
Scroll line down |sc_scroll_line_down|
|
||||||
|
Scroll page up |sc_scroll_page_up|
|
||||||
|
Scroll page down |sc_scroll_page_down|
|
||||||
|
Scroll to top |sc_scroll_home|
|
||||||
|
Scroll to bottom |sc_scroll_end|
|
||||||
|
======================== =======================
|
||||||
|
|
||||||
|
Tabs
|
||||||
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
======================== =======================
|
||||||
|
Action Shortcut
|
||||||
|
======================== =======================
|
||||||
|
New tab |sc_new_tab|
|
||||||
|
Close tab |sc_close_tab|
|
||||||
|
Next tab |sc_next_tab|
|
||||||
|
Previous tab |sc_previous_tab|
|
||||||
|
Next layout |sc_next_layout|
|
||||||
|
Move tab forward |sc_move_tab_forward|
|
||||||
|
Move tab backward |sc_move_tab_backward|
|
||||||
|
Set tab title |sc_set_tab_title|
|
||||||
|
======================== =======================
|
||||||
|
|
||||||
|
|
||||||
|
Windows
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
======================== =======================
|
||||||
|
Action Shortcut
|
||||||
|
======================== =======================
|
||||||
|
New window |sc_new_window|
|
||||||
|
New OS window |sc_new_os_window|
|
||||||
|
Close window |sc_close_window|
|
||||||
|
Next window |sc_next_window|
|
||||||
|
Previous window |sc_previous_window|
|
||||||
|
Move window forward |sc_move_window_forward|
|
||||||
|
Move window backward |sc_move_window_backward|
|
||||||
|
Move window to top |sc_move_window_to_top|
|
||||||
|
Focus specific window |sc_first_window|, |sc_second_window| ... |sc_tenth_window|
|
||||||
|
(clockwise from the top-left)
|
||||||
|
======================== =======================
|
||||||
|
|
||||||
|
|
||||||
|
Other keyboard shortcuts
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
================================== =======================
|
||||||
|
Action Shortcut
|
||||||
|
================================== =======================
|
||||||
|
Copy to clipboard |sc_copy_to_clipboard|
|
||||||
|
Paste from clipboard |sc_paste_from_clipboard|
|
||||||
|
Paste from selection |sc_paste_from_selection|
|
||||||
|
Increase font size |sc_change_font_size_all_plus2_0|
|
||||||
|
Decrease font size |sc_change_font_size_all_2_0|
|
||||||
|
Restore font size |sc_change_font_size_all_0|
|
||||||
|
Toggle fullscreen |sc_toggle_fullscreen|
|
||||||
|
Input unicode character |sc_input_unicode_character|
|
||||||
|
Click URL using the keyboard |sc_kitten_hints|
|
||||||
|
Pass current selection to program |sc_pass_selection_to_program|
|
||||||
|
Edit |kitty| config file |sc_edit_config_file|
|
||||||
|
Open a |kitty| shell |sc_kitty_shell_window|
|
||||||
|
Increase background opacity |sc_set_background_opacity_plus0_1|
|
||||||
|
Decrease background opacity |sc_set_background_opacity_0_1|
|
||||||
|
Full background opacity |sc_set_background_opacity_1|
|
||||||
|
Reset background opacity |sc_set_background_opacity_default|
|
||||||
|
================================== =======================
|
||||||
|
|
||||||
|
|
||||||
|
.. _layouts:
|
||||||
|
|
||||||
|
Layouts
|
||||||
|
----------
|
||||||
|
|
||||||
|
Currently, there are five layouts available,
|
||||||
|
|
||||||
|
* **Stack** -- Only a single maximized window is shown at a time
|
||||||
|
* **Tall** -- One window is shown full height on the left, the rest of the windows are shown one below the other on the right
|
||||||
|
* **Fat** -- One window is shown full width on the top, the rest of the windows are shown side-by-side on the bottom
|
||||||
|
* **Grid** -- All windows are shown in a grid
|
||||||
|
* **Horizontal** -- All windows are shown side-by-side
|
||||||
|
* **Vertical** -- All windows are shown one below the other
|
||||||
|
|
||||||
|
You can switch between layouts using the |sc_next_layout| key combination. You can
|
||||||
|
also create shortcuts to select particular layouts, and choose which layouts
|
||||||
|
you want to enable/disable, see |kitty.conf| for examples.
|
||||||
|
|
||||||
|
You can resize windows inside layouts. Press |sc_start_resizing_window| to
|
||||||
|
enter resizing mode and follow the on-screen instructions. In a given window
|
||||||
|
layout only some operations may be possible for a particular window. For
|
||||||
|
example, in the Tall layout you can make the first window wider/narrower, but
|
||||||
|
not taller/shorter. Note that what you are resizing is actually not a window,
|
||||||
|
but a row/column in the layout, all windows in that row/column will be resized.
|
||||||
|
|
||||||
|
Some layouts take options to control their behavior. For example, the ``fat``
|
||||||
|
and ``tall`` layouts accept the ``bias`` option to control how the available
|
||||||
|
space is split up. To specify the option, in |kitty.conf| use::
|
||||||
|
|
||||||
|
enabled_layouts tall:bias=70
|
||||||
|
|
||||||
|
This will make the tall window occupy ``70%`` of available width. ``bias`` can be
|
||||||
|
any number between 10 and 90.
|
||||||
|
|
||||||
|
Writing a new layout only requires about a hundred lines of code, so if there
|
||||||
|
is some layout you want, take a look at `layout.py
|
||||||
|
<https://github.com/kovidgoyal/kitty/blob/master/kitty/layout.py>`_ and submit
|
||||||
|
a pull request!
|
||||||
|
|
||||||
|
.. _sessions:
|
||||||
|
|
||||||
|
Startup Sessions
|
||||||
|
------------------
|
||||||
|
|
||||||
|
You can control the tabs, window layout, working directory, startup
|
||||||
|
programs, etc. by creating a "session" file and using the :option:`--session`
|
||||||
|
command line flag. For example:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
# Set the window layout for the current tab
|
||||||
|
layout tall
|
||||||
|
# Set the working directory for windows in the current tab
|
||||||
|
cd ~
|
||||||
|
# Create a window and run the specified command in it
|
||||||
|
launch zsh
|
||||||
|
# Create a window with some environment variables set and run vim in it
|
||||||
|
launch env FOO=BAR vim
|
||||||
|
# Set the title for the next window
|
||||||
|
title Chat with x
|
||||||
|
launch irssi --profile x
|
||||||
|
|
||||||
|
# Create a new tab (the part after new_tab is the optional tab name which will
|
||||||
|
# be displayed in the tab bar, if omitted, the title of the active window will
|
||||||
|
# be used instead)
|
||||||
|
new_tab my tab
|
||||||
|
cd ~/somewhere
|
||||||
|
# Set the layouts allowed in this tab
|
||||||
|
enabled_layouts tall, stack
|
||||||
|
# Set the current layout
|
||||||
|
layout stack
|
||||||
|
launch zsh
|
||||||
|
# Make the current window the active (focused) window
|
||||||
|
focus
|
||||||
|
launch emacs
|
||||||
|
|
||||||
|
|
||||||
|
Mouse features
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
* You can also hold down :kbd:`ctrl+shift` and click on a URL to open it in a browser.
|
||||||
|
* You can double click to select a word and triple click to select a line.
|
||||||
|
* You can right click to extend a previous selection
|
||||||
|
|
||||||
|
|
||||||
|
Font control
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
|kitty| has extremely flexible and powerful font selection features. You can
|
||||||
|
specify individual families for the regular, bold, italic and bold+italic
|
||||||
|
fonts. You can even specify specific font families for specific ranges of
|
||||||
|
unicode characters. This allows precise control over text rendering. It can
|
||||||
|
come in handy for applications like powerline, without the need to use patched
|
||||||
|
fonts. See the various font related configuration directives in |kitty.conf|.
|
||||||
|
|
||||||
|
|
||||||
|
.. _scrollback:
|
||||||
|
|
||||||
|
The scrollback buffer
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
|kitty| supports scrolling back to view history, just like most terminals. You
|
||||||
|
can use either keyboard shortcuts or the mouse scroll wheel to do so. However,
|
||||||
|
|kitty| has an extra, neat feature. Sometimes you need to explore the
|
||||||
|
scrollback buffer in more detail, maybe search for some text or refer to it
|
||||||
|
side-by-side while typing in a follow-up command. |kitty| allows you to do this
|
||||||
|
by pressing the |sc_show_scrollback| key-combination, which will open the
|
||||||
|
scrollback buffer in your favorite pager program (which is ``less`` by default).
|
||||||
|
Colors and text formatting are preserved. You can explore the scrollback buffer
|
||||||
|
comfortably within the pager.
|
||||||
|
|
||||||
|
|
||||||
|
Frequently Asked Questions
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
The list of Frequently Asked Questions (*FAQ*) is :doc:`available here <faq>`.
|
||||||
|
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:hidden:
|
||||||
|
:glob:
|
||||||
|
|
||||||
|
*
|
||||||
|
kittens/*
|
||||||
129
docs/key-encoding.rst
Normal file
129
docs/key-encoding.rst
Normal file
@ -0,0 +1,129 @@
|
|||||||
|
Key encoding for extended keyboard protocol
|
||||||
|
===============================================
|
||||||
|
|
||||||
|
See :ref:`extended-key-protocol` for more information and `this table in JSON
|
||||||
|
format <https://github.com/kovidgoyal/kitty/blob/master/key_encoding.json>`_.
|
||||||
|
|
||||||
|
===================== ======================
|
||||||
|
Name Encoded representation (base64)
|
||||||
|
0 ``G``
|
||||||
|
1 ``H``
|
||||||
|
2 ``I``
|
||||||
|
3 ``J``
|
||||||
|
4 ``K``
|
||||||
|
5 ``L``
|
||||||
|
6 ``M``
|
||||||
|
7 ``N``
|
||||||
|
8 ``O``
|
||||||
|
9 ``P``
|
||||||
|
A ``S``
|
||||||
|
APOSTROPHE ``B``
|
||||||
|
B ``T``
|
||||||
|
BACKSLASH ``t``
|
||||||
|
BACKSPACE ``1``
|
||||||
|
C ``U``
|
||||||
|
CAPS LOCK ``:``
|
||||||
|
COMMA ``C``
|
||||||
|
D ``V``
|
||||||
|
DELETE ``3``
|
||||||
|
DOWN ``6``
|
||||||
|
E ``W``
|
||||||
|
END ``-``
|
||||||
|
ENTER ``z``
|
||||||
|
EQUAL ``R``
|
||||||
|
ESCAPE ``y``
|
||||||
|
F ``X``
|
||||||
|
F1 ``/``
|
||||||
|
F10 ``]``
|
||||||
|
F11 ``{``
|
||||||
|
F12 ``}``
|
||||||
|
F13 ``@``
|
||||||
|
F14 ``%``
|
||||||
|
F15 ``$``
|
||||||
|
F16 ``#``
|
||||||
|
F17 ``BA``
|
||||||
|
F18 ``BB``
|
||||||
|
F19 ``BC``
|
||||||
|
F2 ``*``
|
||||||
|
F20 ``BD``
|
||||||
|
F21 ``BE``
|
||||||
|
F22 ``BF``
|
||||||
|
F23 ``BG``
|
||||||
|
F24 ``BH``
|
||||||
|
F25 ``BI``
|
||||||
|
F3 ``?``
|
||||||
|
F4 ``&``
|
||||||
|
F5 ``<``
|
||||||
|
F6 ``>``
|
||||||
|
F7 ``(``
|
||||||
|
F8 ``)``
|
||||||
|
F9 ``[``
|
||||||
|
G ``Y``
|
||||||
|
GRAVE ACCENT ``v``
|
||||||
|
H ``Z``
|
||||||
|
HOME ``.``
|
||||||
|
I ``a``
|
||||||
|
INSERT ``2``
|
||||||
|
J ``b``
|
||||||
|
K ``c``
|
||||||
|
KP 0 ``BJ``
|
||||||
|
KP 1 ``BK``
|
||||||
|
KP 2 ``BL``
|
||||||
|
KP 3 ``BM``
|
||||||
|
KP 4 ``BN``
|
||||||
|
KP 5 ``BO``
|
||||||
|
KP 6 ``BP``
|
||||||
|
KP 7 ``BQ``
|
||||||
|
KP 8 ``BR``
|
||||||
|
KP 9 ``BS``
|
||||||
|
KP ADD ``BX``
|
||||||
|
KP DECIMAL ``BT``
|
||||||
|
KP DIVIDE ``BU``
|
||||||
|
KP ENTER ``BY``
|
||||||
|
KP EQUAL ``BZ``
|
||||||
|
KP MULTIPLY ``BV``
|
||||||
|
KP SUBTRACT ``BW``
|
||||||
|
L ``d``
|
||||||
|
LEFT ``5``
|
||||||
|
LEFT ALT ``Bc``
|
||||||
|
LEFT BRACKET ``s``
|
||||||
|
LEFT CONTROL ``Bb``
|
||||||
|
LEFT SHIFT ``Ba``
|
||||||
|
LEFT SUPER ``Bd``
|
||||||
|
M ``e``
|
||||||
|
MINUS ``D``
|
||||||
|
N ``f``
|
||||||
|
NUM LOCK ``=``
|
||||||
|
O ``g``
|
||||||
|
P ``h``
|
||||||
|
PAGE DOWN ``9``
|
||||||
|
PAGE UP ``8``
|
||||||
|
PAUSE ``!``
|
||||||
|
PERIOD ``E``
|
||||||
|
PRINT SCREEN ``^``
|
||||||
|
Q ``i``
|
||||||
|
R ``j``
|
||||||
|
RIGHT ``4``
|
||||||
|
RIGHT ALT ``Bg``
|
||||||
|
RIGHT BRACKET ``u``
|
||||||
|
RIGHT CONTROL ``Bf``
|
||||||
|
RIGHT SHIFT ``Be``
|
||||||
|
RIGHT SUPER ``Bh``
|
||||||
|
S ``k``
|
||||||
|
SCROLL LOCK ``+``
|
||||||
|
SEMICOLON ``Q``
|
||||||
|
SLASH ``F``
|
||||||
|
SPACE ``A``
|
||||||
|
T ``l``
|
||||||
|
TAB ``0``
|
||||||
|
U ``m``
|
||||||
|
UP ``7``
|
||||||
|
V ``n``
|
||||||
|
W ``o``
|
||||||
|
WORLD 1 ``w``
|
||||||
|
WORLD 2 ``x``
|
||||||
|
X ``p``
|
||||||
|
Y ``q``
|
||||||
|
Z ``r``
|
||||||
|
===================== ======================
|
||||||
|
|
||||||
129
docs/kittens/diff.rst
Normal file
129
docs/kittens/diff.rst
Normal file
@ -0,0 +1,129 @@
|
|||||||
|
kitty-diff - A side-by-side diff tool with syntax highlighting and images
|
||||||
|
=============================================================================
|
||||||
|
|
||||||
|
Major Features
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
* Displays diffs side-by-side in the kitty terminal.
|
||||||
|
|
||||||
|
* Does syntax highlighting of displayed diffs
|
||||||
|
|
||||||
|
* Displays images as well as text diffs, even over SSH
|
||||||
|
|
||||||
|
* Does recursive directory diffing
|
||||||
|
|
||||||
|
|
||||||
|
.. image:: ../screenshots/diff.png
|
||||||
|
:alt: Screenshot, showing a sample diff
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
|
||||||
|
Installation
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Simply install `kitty <https://github.com/kovidgoyal/kitty>`_. 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 <http://pygments.org/>`_ must be installed (note that pygments is
|
||||||
|
included in the macOS kitty app).
|
||||||
|
|
||||||
|
|
||||||
|
Usage
|
||||||
|
--------
|
||||||
|
|
||||||
|
In the kitty terminal, run::
|
||||||
|
|
||||||
|
kitty +kitten diff file1 file2
|
||||||
|
|
||||||
|
to see the diff between file1 and file2.
|
||||||
|
|
||||||
|
Create an alias in your shell's startup file to shorten the command, for example:
|
||||||
|
|
||||||
|
.. code-block:: sh
|
||||||
|
|
||||||
|
alias d="kitty +kitten diff"
|
||||||
|
|
||||||
|
Now all you need to do to diff two files is::
|
||||||
|
|
||||||
|
d file1 file2
|
||||||
|
|
||||||
|
You can also pass directories instead of files to see the recursive diff of the
|
||||||
|
directory contents.
|
||||||
|
|
||||||
|
|
||||||
|
Keyboard controls
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
========================= ===========================
|
||||||
|
Action Shortcut
|
||||||
|
========================= ===========================
|
||||||
|
Quit ``q, Ctrl+c``
|
||||||
|
Scroll line up ``k, up``
|
||||||
|
Scroll line down ``j, down``
|
||||||
|
Scroll page up ``PgUp``
|
||||||
|
Scroll page down ``PgDn``
|
||||||
|
Scroll to top ``Home``
|
||||||
|
Scroll to bottom ``End``
|
||||||
|
Scroll to next page ``Space, PgDn``
|
||||||
|
Scroll to previous page ``PgUp``
|
||||||
|
Scroll to next change ``n``
|
||||||
|
Scroll to previous change ``p``
|
||||||
|
Increase lines of context ``+``
|
||||||
|
Decrease lines of context ``-``
|
||||||
|
All lines of context ``a``
|
||||||
|
Restore default context ``=``
|
||||||
|
========================= ===========================
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Configuring kitty-diff
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
You can configure the colors used, keyboard shortcut, the diff implementation,
|
||||||
|
the default lines of context, etc. by creating a diff.conf in your kitty
|
||||||
|
config folder. The default diff.conf is below.
|
||||||
|
|
||||||
|
.. literalinclude:: ../../kittens/diff/diff.conf
|
||||||
|
:language: ini
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Integrating with git
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
Add the following to `~/.gitconfig`:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[diff]
|
||||||
|
tool = kitty
|
||||||
|
guitool = kitty.gui
|
||||||
|
[difftool]
|
||||||
|
prompt = false
|
||||||
|
trustExitCode = true
|
||||||
|
[difftool "kitty"]
|
||||||
|
cmd = kitty +kitten diff $LOCAL $REMOTE
|
||||||
|
[difftool "kitty.gui"]
|
||||||
|
cmd = kitty kitty +kitten diff $LOCAL $REMOTE
|
||||||
|
|
||||||
|
Now to use kitty-diff to view git diffs, you can simply do::
|
||||||
|
|
||||||
|
git difftool --no-symlinks --dir-diff
|
||||||
|
|
||||||
|
Once again, creating an alias for this command is useful.
|
||||||
|
|
||||||
|
|
||||||
|
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 </graphics-protocol>`,
|
||||||
|
the extended 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 :)
|
||||||
22
docs/kittens/hints.rst
Normal file
22
docs/kittens/hints.rst
Normal file
@ -0,0 +1,22 @@
|
|||||||
|
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_kitten_hints|
|
||||||
|
to choose any URL visible on the screen and then open it using your system
|
||||||
|
browser.
|
||||||
|
|
||||||
|
.. image:: ../screenshots/hints_mode.png
|
||||||
|
:alt: URL hints mode
|
||||||
|
|
||||||
|
Similarly, you can press |sc_kitten_hints_type_path_program| 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.
|
||||||
|
|
||||||
|
The hints kitten is very powerful to see more detailed help on its various
|
||||||
|
options and modes of operation, use::
|
||||||
|
|
||||||
|
kitty +kitten hints --help
|
||||||
|
|
||||||
|
|
||||||
18
docs/kittens/unicode-input.rst
Normal file
18
docs/kittens/unicode-input.rst
Normal file
@ -0,0 +1,18 @@
|
|||||||
|
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.
|
||||||
|
|
||||||
|
.. image:: ../screenshots/unicode.png
|
||||||
|
:alt: A screenshot of the unicode input widget
|
||||||
|
|
||||||
|
In *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.
|
||||||
|
|
||||||
|
In *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 leading period and the index for the match if you dont like to use arrow
|
||||||
|
keys.
|
||||||
45
docs/performance.rst
Normal file
45
docs/performance.rst
Normal file
@ -0,0 +1,45 @@
|
|||||||
|
|kitty| Performance
|
||||||
|
===================
|
||||||
|
|
||||||
|
The main goals for |kitty| performance are user perceived latency while typing
|
||||||
|
and "smoothness" while scrolling as well as CPU usage. |kitty| tries hard to find
|
||||||
|
an optimum balance for these. To that end it keeps a cache of each rendered
|
||||||
|
glyph in video RAM so that font rendering is not a bottleneck. Interaction
|
||||||
|
with child programs takes place in a separate thread from rendering, to improve
|
||||||
|
smoothness.
|
||||||
|
|
||||||
|
There are two parameters you can tune to adjust the performance. ``repaint_delay``
|
||||||
|
and ``input_delay``. These control the artificial delays introduced into the
|
||||||
|
render loop to reduce CPU usage. See |kitty.conf| for details.
|
||||||
|
See also the ``sync_to_monitor`` option to further decrease latency at the cost
|
||||||
|
of some `tearing <https://en.wikipedia.org/wiki/Screen_tearing>`_ while scrolling.
|
||||||
|
|
||||||
|
You can generate detailed per-function performance data using
|
||||||
|
`gperftools <https://github.com/gperftools/gperftools>`_. Build |kitty| with
|
||||||
|
`make profile` which will create an executable called `kitty-profile`. Run
|
||||||
|
that and perform the task you want to analyse, for example, scrolling a large
|
||||||
|
file with `less`. After you quit, function call statistics will be printed to
|
||||||
|
`stdout` and you can use tools like *kcachegrind* for more detailed analysis.
|
||||||
|
|
||||||
|
Here are some CPU usage numbers for the task of scrolling a file continuously
|
||||||
|
in less. The CPU usage is for the terminal process and X together and is
|
||||||
|
measured using htop. The measurements are taken at the same font and window
|
||||||
|
size for all terminals on a ``Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz`` CPU
|
||||||
|
with a ``Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD
|
||||||
|
7770/8760 / R7 250X]`` GPU.
|
||||||
|
|
||||||
|
============== =========================
|
||||||
|
Terminal CPU usage (X + terminal)
|
||||||
|
============== =========================
|
||||||
|
|kitty| 6 - 8%
|
||||||
|
xterm 5 - 7% (but scrolling was extremely janky)
|
||||||
|
termite 10 - 13%
|
||||||
|
urxvt 12 - 14%
|
||||||
|
gnome-terminal 15 - 17%
|
||||||
|
konsole 29 - 31%
|
||||||
|
============== =========================
|
||||||
|
|
||||||
|
|
||||||
|
As you can see, |kitty| uses much less CPU than all terminals, except xterm, but
|
||||||
|
its scrolling "smoothness" is much better than that of xterm (at least to my,
|
||||||
|
admittedly biased, eyes).
|
||||||
165
docs/protocol-extensions.rst
Normal file
165
docs/protocol-extensions.rst
Normal file
@ -0,0 +1,165 @@
|
|||||||
|
Extensions to the xterm protocol
|
||||||
|
===================================
|
||||||
|
|
||||||
|
|kitty| has a few extensions to the xterm protocol, to enable advanced features.
|
||||||
|
These are typically in the form of new or re-purposed escape codes. While these
|
||||||
|
extensions are currently |kitty| specific, it would be nice to get some of them
|
||||||
|
adopted more broadly, to push the state of terminal emulators forward.
|
||||||
|
|
||||||
|
The goal of these extensions is to be as small an unobtrusive as possible,
|
||||||
|
while filling in some gaps in the existing xterm protocol. In particular, one
|
||||||
|
of the goals of this specification is explicitly not to "re-imagine" the tty.
|
||||||
|
The tty should remain what it is -- a device for efficiently processing text
|
||||||
|
received as a simple byte stream. Another objective is to only move the minimum
|
||||||
|
possible amount of extra functionality into the terminal program itself. This
|
||||||
|
is to make it as easy to implement these protocol extensions as possible,
|
||||||
|
thereby hopefully encouraging their widespread adoption.
|
||||||
|
|
||||||
|
If you wish to discuss these extensions, propose additions/changes to them
|
||||||
|
please do so by opening issues in the github bug tracker.
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Colored and styled underlines
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
|kitty| supports colored and styled (wavy) underlines. This is of particular
|
||||||
|
use in terminal editors such as vim and emacs to display red, wavy underlines
|
||||||
|
under mis-spelled words and/or syntax errors. This is done by re-purposing some
|
||||||
|
SGR escape codes that are not used in modern terminals (`CSI codes
|
||||||
|
<https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_codes>`_)
|
||||||
|
|
||||||
|
To set the underline style::
|
||||||
|
|
||||||
|
<ESC>[4:0m # this is no underline
|
||||||
|
<ESC>[4:1m # this is a straight underline
|
||||||
|
<ESC>[4:2m # this is a double underline
|
||||||
|
<ESC>[4:3m # this is a curly underline
|
||||||
|
<ESC>[4:4m # this is a dotted underline (not implemented in kitty)
|
||||||
|
<ESC>[4:5m # this is a dashed underline (not implemented in kitty)
|
||||||
|
<ESC>[4m # this is a straight underline (for backwards compat)
|
||||||
|
<ESC>[24m # this is no underline (for backwards compat)
|
||||||
|
|
||||||
|
To set the underline color (this is reserved and as far as I can tell not actually used for anything)::
|
||||||
|
|
||||||
|
<ESC>[58...m
|
||||||
|
|
||||||
|
This works exactly like the codes ``38, 48`` that are used to set foreground and
|
||||||
|
background color respectively.
|
||||||
|
|
||||||
|
To reset the underline color (also previously reserved and unused)::
|
||||||
|
|
||||||
|
<ESC>[59m
|
||||||
|
|
||||||
|
To detect support for this feature in a terminal emulator, query the terminfo database
|
||||||
|
for the ``Su`` boolean capability.
|
||||||
|
|
||||||
|
Graphics rendering
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
See :doc:`/graphics-protocol` for a description
|
||||||
|
of this protocol to enable drawing of arbitrary raster images in the terminal.
|
||||||
|
|
||||||
|
|
||||||
|
.. _extended-key-protocol:
|
||||||
|
|
||||||
|
Keyboard handling
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
There are various problems with the current state of keyboard handling. They
|
||||||
|
include:
|
||||||
|
|
||||||
|
* No way to use modifiers other than ``Ctrl`` and ``Alt``
|
||||||
|
|
||||||
|
* No way to use multiple modifier keys, other than, ``Shift+Alt``.
|
||||||
|
|
||||||
|
* No way to handle different types of keyboard events, such as press, release or repeat
|
||||||
|
|
||||||
|
* No reliable way to distinguish single ``Esc`` keypresses from the start of a
|
||||||
|
escape sequence. Currently, client programs use fragile timing related hacks
|
||||||
|
for this, leading to bugs, for example:
|
||||||
|
`neovim #2035 <https://github.com/neovim/neovim/issues/2035>`_.
|
||||||
|
|
||||||
|
There are already two distinct keyboard handling modes, *normal mode* and
|
||||||
|
*application mode*. These modes generate different escape sequences for the
|
||||||
|
various special keys (arrow keys, function keys, home/end etc.) Most terminals
|
||||||
|
start out in normal mode, however, most shell programs like ``bash`` switch them to
|
||||||
|
application mode. We propose adding a third mode, named *full mode* that addresses
|
||||||
|
the shortcomings listed above.
|
||||||
|
|
||||||
|
Switching to the new *full mode* is accomplished using the standard private
|
||||||
|
mode DECSET escape sequence::
|
||||||
|
|
||||||
|
<ESC>[?2017h
|
||||||
|
|
||||||
|
and to leave *full mode*, use DECRST::
|
||||||
|
|
||||||
|
<ESC>[?2017l
|
||||||
|
|
||||||
|
The number ``2017`` above is not used for any existing modes, as far as I know.
|
||||||
|
Client programs can query if the terminal emulator is in *full mode* by using
|
||||||
|
the standard `DECRQM <http://vt100.net/docs/vt510-rm/DECRQM>`_ escape sequence.
|
||||||
|
|
||||||
|
The new mode works as follows:
|
||||||
|
|
||||||
|
* All printable key presses without modifier keys are sent just as in the
|
||||||
|
*normal mode*. This means all printable ASCII characters and in addition,
|
||||||
|
``Enter``, ``Space`` and ``Backspace``. Also any unicode characters generated by
|
||||||
|
platform specific extended input modes, such as using the ``AltGr`` key. This
|
||||||
|
is done so that client programs that are not aware of this mode can still
|
||||||
|
handle basic text entry, so if a *full mode* using program crashes and does
|
||||||
|
not reset, the user can still issue a ``reset`` command in the shell to restore
|
||||||
|
normal key handling. Note that this includes pressing the ``Shift`` modifier
|
||||||
|
and printable keys. Note that this means there are no repeat and release
|
||||||
|
events for these keys and also for the left and right shift keys.
|
||||||
|
|
||||||
|
* For non printable keys and key combinations including one or more modifiers,
|
||||||
|
an escape sequence encoding the key event is sent. For details on the
|
||||||
|
escape sequence, see below.
|
||||||
|
|
||||||
|
The escape sequence encodes the following properties:
|
||||||
|
|
||||||
|
* Type of event: ``press,repeat,release``
|
||||||
|
* Modifiers pressed at the time of the event
|
||||||
|
* The actual key being pressed
|
||||||
|
|
||||||
|
Schematically::
|
||||||
|
|
||||||
|
<ESC>_K<type><modifiers><key><ESC>\
|
||||||
|
|
||||||
|
Where ``<type>`` is one of ``p`` -- press, ``r`` -- release and ``t`` -- repeat.
|
||||||
|
Modifiers is a bitmask represented as a single base64 digit. Shift -- ``0x1``,
|
||||||
|
Alt -- ``0x2``, Control -- ``0x4`` and Super -- ``0x8``. ``<key>`` is a number
|
||||||
|
(encoded in base85) corresponding to the key pressed. The key name to number
|
||||||
|
mapping is defined in :doc:`this table <key-encoding>`.
|
||||||
|
|
||||||
|
For example::
|
||||||
|
|
||||||
|
<ESC>_KpGp<ESC>\ is <Ctrl>+<Alt>+x (press)
|
||||||
|
<ESC>_KrP8<ESC>\ is <Ctrl>+<Alt>+<Shift>+<Super>+PageUp (release)
|
||||||
|
|
||||||
|
This encoding means each key event is represented by 8 or 9 printable ascii
|
||||||
|
only bytes, for maximum robustness.
|
||||||
|
|
||||||
|
|
||||||
|
Setting text styles/colors in arbitrary regions of the screen
|
||||||
|
------------------------------------------------------------------
|
||||||
|
|
||||||
|
There already exists an escape code to set *some* text attributes in arbitrary
|
||||||
|
regions of the screen, `DECCARA
|
||||||
|
<https://vt100.net/docs/vt510-rm/DECCARA.html>`_. However, it is limited to
|
||||||
|
only a few attributes. |kitty| extends this to work with *all* SGR attributes.
|
||||||
|
So, for example, this can be used to set the background color in an arbitrary
|
||||||
|
region of the screen.
|
||||||
|
|
||||||
|
The motivation for this extension is the various problems with the existing
|
||||||
|
solution for erasing to background color, namely the *background color erase
|
||||||
|
(bce)* capability. See
|
||||||
|
`this discussion <https://github.com/kovidgoyal/kitty/issues/160#issuecomment-346470545>`_
|
||||||
|
and `this FAQ <http://invisible-island.net/ncurses/ncurses.faq.html#bce_mismatches>`_
|
||||||
|
for a summary of problems with *bce*.
|
||||||
|
|
||||||
|
For example, to set the background color to blue in a
|
||||||
|
rectangular region of the screen from (3, 4) to (10, 11), you use::
|
||||||
|
|
||||||
|
<ESC>[2*x<ESC>[4;3;11;10;44$r<ESC>[*x
|
||||||
114
docs/remote-control.rst
Normal file
114
docs/remote-control.rst
Normal file
@ -0,0 +1,114 @@
|
|||||||
|
Controlling kitty from scripts or the shell
|
||||||
|
==============================================
|
||||||
|
|
||||||
|
.. 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.
|
||||||
|
Let's walk through a few examples of controlling |kitty|.
|
||||||
|
|
||||||
|
Start by running |kitty| as::
|
||||||
|
|
||||||
|
kitty -o allow_remote_control=yes --window-layout tall
|
||||||
|
|
||||||
|
In order for control to work, ``allow_remote_control`` must be enabled in
|
||||||
|
|kitty.conf|. Here we turn it on explicitly at the command line.
|
||||||
|
|
||||||
|
Now, in the new |kitty| window, enter the command::
|
||||||
|
|
||||||
|
kitty @ new-window --title Output --keep-focus cat
|
||||||
|
|
||||||
|
This will open a new window, running the ``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:`--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.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
You can even have things you type show up in a different window. Run::
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Now, let's open a new tab::
|
||||||
|
|
||||||
|
kitty @ new-window --new-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::
|
||||||
|
|
||||||
|
kitty @ set-tab-title --match title:My New Title
|
||||||
|
|
||||||
|
Let's change the title of the current tab::
|
||||||
|
|
||||||
|
kitty @ set-tab-title Master Tab
|
||||||
|
|
||||||
|
Now lets switch to the newly opened tab::
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
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:`--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.
|
||||||
|
|
||||||
|
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:`--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:`--to` command line argument to ``kitty @``. For example::
|
||||||
|
|
||||||
|
kitty @ --to unix:/tmp/mykitty ls
|
||||||
|
|
||||||
|
|
||||||
|
Note that is 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:`--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 even open the |kitty| shell inside a running |kitty| using a simple
|
||||||
|
keyboard shortcut (|sc_kitty_shell_window| by default). This has the added
|
||||||
|
advantage that you dont need to use ``allow_remote_control`` to make it work.
|
||||||
|
Before Width: | Height: | Size: 131 KiB After Width: | Height: | Size: 131 KiB |
|
Before Width: | Height: | Size: 62 KiB After Width: | Height: | Size: 62 KiB |
|
Before Width: | Height: | Size: 1.2 MiB After Width: | Height: | Size: 1.2 MiB |
|
Before Width: | Height: | Size: 88 KiB After Width: | Height: | Size: 88 KiB |
@ -1,57 +0,0 @@
|
|||||||
#!/usr/bin/env python3
|
|
||||||
# vim:fileencoding=utf-8
|
|
||||||
# License: GPL v3 Copyright: 2016, Kovid Goyal <kovid at kovidgoyal.net>
|
|
||||||
|
|
||||||
import json
|
|
||||||
import os
|
|
||||||
import re
|
|
||||||
import subprocess
|
|
||||||
from collections import defaultdict
|
|
||||||
|
|
||||||
base = os.path.dirname(os.path.abspath(__file__))
|
|
||||||
os.chdir(base)
|
|
||||||
|
|
||||||
defns = defaultdict(list)
|
|
||||||
|
|
||||||
for line in open('kitty/kitty.conf'):
|
|
||||||
if line.startswith('map '):
|
|
||||||
_, sc, name = line.split(maxsplit=2)
|
|
||||||
sc = sc.replace('kitty_mod', 'ctrl+shift')
|
|
||||||
name = name.rstrip().replace(' ', '_').replace('-', '_').replace('+', 'plus').replace('.', '_').replace('___', '_').replace('__', '_').strip('_')
|
|
||||||
defns[name].append('`' + sc.replace('>', ' → ') + '`')
|
|
||||||
|
|
||||||
defns = [
|
|
||||||
':sc_{}: pass:quotes[{}]'.format(name, ' or '.join(defns[name]))
|
|
||||||
for name in sorted(defns)
|
|
||||||
]
|
|
||||||
defns = '\n'.join(defns)
|
|
||||||
|
|
||||||
raw = open('README.asciidoc').read()
|
|
||||||
pat = re.compile(
|
|
||||||
r'^// START_SHORTCUT_BLOCK$.+?^// END_SHORTCUT_BLOCK$', re.M | re.DOTALL
|
|
||||||
)
|
|
||||||
nraw = pat.sub(
|
|
||||||
'// START_SHORTCUT_BLOCK\n' + defns + '\n// END_SHORTCUT_BLOCK', raw
|
|
||||||
)
|
|
||||||
if raw != nraw:
|
|
||||||
print('Updating shortcuts block')
|
|
||||||
open('README.asciidoc', 'w').write(nraw)
|
|
||||||
|
|
||||||
raw = subprocess.check_output([
|
|
||||||
'kitty', '+runpy',
|
|
||||||
'from kitty.key_encoding import *; import json; print(json.dumps(ENCODING))'
|
|
||||||
]).decode('utf-8')
|
|
||||||
key_map = json.loads(raw)
|
|
||||||
lines = [
|
|
||||||
'See link:protocol-extensions.asciidoc#keyboard-handling[Keyboard Handling protocol extension]',
|
|
||||||
' for more information and link:key_encoding.json[for this table in JSON format].',
|
|
||||||
'', '|===', '| Name | Encoded representation (base64)', ''
|
|
||||||
]
|
|
||||||
for k in sorted(key_map):
|
|
||||||
lines.append('| {:15s} | `{}`'.format(k.replace('_', ' '), key_map[k].replace('`', '\\`')))
|
|
||||||
lines += ['', '|===']
|
|
||||||
with open('key_encoding.asciidoc', 'w') as f:
|
|
||||||
print('= Key encoding for extended keyboard protocol\n', file=f)
|
|
||||||
print('\n'.join(lines), file=f)
|
|
||||||
with open('key_encoding.json', 'w') as f:
|
|
||||||
f.write(json.dumps(key_map, indent=2))
|
|
||||||
Loading…
x
Reference in New Issue
Block a user