Start work on a kitty website
Port the current asciidoc documentation to sphinx
1
.gitignore
vendored
@ -13,3 +13,4 @@ kitty-profile
|
||||
dev
|
||||
__pycache__
|
||||
glfw/wayland-*-client-protocol.[ch]
|
||||
docs/_build
|
||||
|
512
README.asciidoc
@ -1,519 +1,7 @@
|
||||
= 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]
|
||||
|
||||
== 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
|
||||
|
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
@ -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
@ -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
@ -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
@ -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
@ -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
@ -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
@ -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
@ -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
@ -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
@ -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
@ -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
@ -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
@ -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
@ -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
@ -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))
|