mirror of
https://github.com/kovidgoyal/kitty.git
synced 2024-09-11 14:45:31 +03:00
313 lines
10 KiB
Plaintext
313 lines
10 KiB
Plaintext
= kitty - A terminal emulator
|
|
:toc:
|
|
:toc-placement!:
|
|
// START_SHORTCUT_BLOCK
|
|
: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_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_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_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_paste_from_clipboard: pass:quotes[`ctrl+shift+v`]
|
|
:sc_paste_from_selection: pass:quotes[`ctrl+shift+s`]
|
|
: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_seventh_window: pass:quotes[`ctrl+shift+7`]
|
|
:sc_show_scrollback: pass:quotes[`ctrl+shift+h`]
|
|
:sc_sixth_window: pass:quotes[`ctrl+shift+6`]
|
|
:sc_tenth_window: pass:quotes[`ctrl+shift+0`]
|
|
:sc_third_window: pass:quotes[`ctrl+shift+3`]
|
|
// 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
|
|
|
|
* Supports tiling multiple terminal windows side by side in different
|
|
layouts without needing to use an extra program like tmux
|
|
|
|
* Supports all modern terminal features: unicode, true-color, mouse
|
|
protocol, focus tracking, bracketed paste and so on.
|
|
|
|
* Allows you to view the scrollback buffer in a separate window
|
|
using your favorite pager program such as less
|
|
|
|
* Support startup sessions which allow you to specify the window/tab layout,
|
|
working directories and programs to run on startup.
|
|
|
|
* Easily hackable (UI layer written in python, inner loops in C for
|
|
speed). Less than ten thousand lines of code.
|
|
|
|
* Uses OpenGL for rendering, offloads rendering work to the GPU for lower system load.
|
|
|
|
* 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. See link:../../issues/5[5] for the status of the macOS port.
|
|
|
|
image::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
|
|
* glfw >= 3.2
|
|
* glew >= 2.0 (not needed on macOS)
|
|
* freetype, fontconfig (not needed on macOS)
|
|
* xdpyinfo and xsel (only on X11 based systems)
|
|
* gcc or clang (required only for building)
|
|
* pkg-config (required only for building)
|
|
|
|
=== Install and run from source
|
|
|
|
....
|
|
git clone https://github.com/kovidgoyal/kitty && cd kitty
|
|
....
|
|
|
|
Now build the C parts of kitty with the following command:
|
|
|
|
....
|
|
python3 setup.py build
|
|
....
|
|
|
|
You can run kitty, as:
|
|
|
|
....
|
|
python3 /path/to/kitty/folder
|
|
....
|
|
|
|
=== Linux packages
|
|
|
|
* Arch linux: AUR git package https://aur.archlinux.org/packages/kitty-git/
|
|
|
|
|
|
=== macOS packages
|
|
|
|
Currently, no one has made macOS packages for kitty, but you can use the above
|
|
install from source instructions to run kitty on macOS, after installing its two
|
|
dependencies (python >= 3.5 and glfw >= 3.2)
|
|
|
|
|
|
== 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). It's configuration is a simple, human editable, single file for
|
|
easy reproducability (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+FreeType 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}
|
|
|
|
|===
|
|
|
|
|
|
[options="header"]
|
|
|
|
=== Windows
|
|
|
|
|===
|
|
|Action |Shortcut
|
|
|
|
|New window | {sc_new_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}
|
|
|
|
|===
|
|
|
|
|
|
== 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 a new window, using your favorite
|
|
pager program (which is `less` by default). You can then explore the scrollback
|
|
buffer using whatever program you normally use. Colors and text formatting are
|
|
preserved.
|
|
|
|
|
|
== Miscellaneous features
|
|
|
|
You can double click to select a word and triple click to select a line. You can also
|
|
hold down `ctrl+shift` and click on a URL to open it in a browser.
|
|
|
|
|
|
== Layouts
|
|
|
|
Currently, there are two 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.
|
|
|
|
You can switch between layouts using the {sc_next_layout} key combination.
|
|
|
|
Writing a new layout only requires about thirty 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]. By default kitty looks for a
|
|
config file in the OS config directory (usually
|
|
`~/.config/kitty/kitty.conf` on Linux) but you can pass a specific path
|
|
via the `--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 the current tab
|
|
cd ~
|
|
# Create a window and run the specified command in it
|
|
launch zsh
|
|
launch vim
|
|
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].
|
|
|
|
== 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.
|
|
|
|
This applies to creating packages for kitty for macOS package managers such as
|
|
brew or MacPorts as well.
|
|
|
|
== Resources on terminal behavior
|
|
|
|
http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
|
|
|
|
https://en.wikipedia.org/wiki/C0_and_C1_control_codes
|
|
|
|
http://vt100.net/
|