mirrors/foot
1
0
Fork 0
mirror of https://codeberg.org/dnkl/foot.git synced 2026-06-13 14:33:17 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add educational note

Browse source
This commit is contained in:
Serhii Pozhidayev 2026-06-07 23:43:20 +02:00
parent 4bf60d0fbc
commit 383a7a550b
1 changed files with 87 additions and 114 deletions
Download patch file Download diff file Expand all files Collapse all files

201
README.md
View file

@ -6,7 +6,6 @@ The fast, lightweight and minimalistic Wayland terminal emulator.
[![Packaging status](https://repology.org/badge/vertical-allrepos/foot.svg?columns=4)](https://repology.org/project/foot/versions)
## Index
1. [Features](#features)
@ -16,17 +15,17 @@ The fast, lightweight and minimalistic Wayland terminal emulator.
1. [Why the name 'foot'?](#why-the-name-foot)
1. [Fonts](#fonts)
1. [Shortcuts](#shortcuts)
1. [Keyboard](#keyboard)
1. [Normal mode](#normal-mode)
1. [Scrollback search](#scrollback-search)
1. [Mouse](#mouse)
1. [Touchscreen](#touchscreen)
1. [Keyboard](#keyboard)
1. [Normal mode](#normal-mode)
1. [Scrollback search](#scrollback-search)
1. [Mouse](#mouse)
1. [Touchscreen](#touchscreen)
1. [Server (daemon) mode](#server-daemon-mode)
1. [URLs](#urls)
1. [Shell integration](#shell-integration)
1. [Current working directory](#current-working-directory)
1. [Jumping between prompts](#jumping-between-prompts)
1. [Piping last command's output](#piping-last-command-s-output)
1. [Current working directory](#current-working-directory)
1. [Jumping between prompts](#jumping-between-prompts)
1. [Piping last command's output](#piping-last-command-s-output)
1. [Alt/meta](#alt-meta)
1. [Backspace](#backspace)
1. [Keypad](#keypad)
@ -38,57 +37,52 @@ The fast, lightweight and minimalistic Wayland terminal emulator.
1. [Code of Conduct](#code-of-conduct)
1. [Bugs](#bugs)
1. [Contact](#contact)
1. [IRC](#irc)
1. [Mastodon](#mastodon)
1. [IRC](#irc)
1. [Mastodon](#mastodon)
1. [Sponsoring/donations](#sponsoring-donations)
1. [License](#license)
## Features
* Fast (see [benchmarks](doc/benchmark.md), and
- Fast (see [benchmarks](doc/benchmark.md), and
[performance](https://codeberg.org/dnkl/foot/wiki/Performance))
* Lightweight, in dependencies, on-disk and in-memory
* Wayland native
* DE agnostic
* Server/daemon mode
* User configurable font fallback
* On-the-fly font resize
* On-the-fly DPI font size adjustment
* Scrollback search
* Keyboard driven URL detection
* Color emoji support
* IME (via `text-input-v3`)
* Multi-seat
* True Color (24bpp)
* [Styled and colored underlines](https://sw.kovidgoyal.net/kitty/underlines/)
* [Synchronized Updates](https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/2) support
* [Sixel image support](https://en.wikipedia.org/wiki/Sixel)
![tux-with-foot](doc/sixel-tux-foot.png "Sixel screenshot")
- Lightweight, in dependencies, on-disk and in-memory
- Wayland native
- DE agnostic
- Server/daemon mode
- User configurable font fallback
- On-the-fly font resize
- On-the-fly DPI font size adjustment
- Scrollback search
- Keyboard driven URL detection
- Color emoji support
- IME (via `text-input-v3`)
- Multi-seat
- True Color (24bpp)
- [Styled and colored underlines](https://sw.kovidgoyal.net/kitty/underlines/)
- [Synchronized Updates](https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/2) support
- [Sixel image support](https://en.wikipedia.org/wiki/Sixel)
![tux-with-foot](doc/sixel-tux-foot.png "Sixel screenshot")
# Installing
See [INSTALL.md](INSTALL.md).
## Configuration
**foot** can be configured by creating a file
`$XDG_CONFIG_HOME/foot/foot.ini` (defaulting to
`~/.config/foot/foot.ini`). A template for that can usually be found
`~/.config/foot/foot.ini`). A template for that can usually be found
in `/etc/xdg/foot/foot.ini` or
[here](https://codeberg.org/dnkl/foot/src/branch/master/foot.ini).
Further information can be found in foot's man page `foot.ini(5)`.
## Troubleshooting
See the [wiki](https://codeberg.org/dnkl/foot/wiki#user-content-troubleshooting)
## Why the name 'foot'?
I'm bad at names. Most of my projects usually start out as _foo
@ -105,7 +99,6 @@ As a side note, if you pronounce the _foo_ part of _foot_ the same way
you pronounce _foobar_, then _foot_ sounds a lot like the Swedish word
_fot_, which incidentally means (you guessed it) _foot_.
## Fonts
**foot** supports all fonts that can be loaded by _freetype_,
@ -119,18 +112,16 @@ fallback fonts to use.
This also means you can configure _each_ fallback font individually;
you want _that_ fallback font to use _this_ size, and you want that
_other_ fallback font to be _italic_? No problem!
_other_ fallback font to be _italic_? No problem!
If a glyph cannot be found in _any_ of the user configured fallback
fonts, _then_ fontconfig's list is used.
## Shortcuts
These are the default shortcuts. See `man foot.ini` and the example
`foot.ini` to see how these can be changed.
### Keyboard
#### Normal mode
@ -161,25 +152,24 @@ These are the default shortcuts. See `man foot.ini` and the example
<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>n</kbd>
: Spawn a new terminal. If the shell has been [configured to emit the
OSC 7 escape
sequence](https://codeberg.org/dnkl/foot/wiki#user-content-spawning-new-terminal-instances-in-the-current-working-directory),
the new terminal will start in the current working directory.
OSC 7 escape
sequence](https://codeberg.org/dnkl/foot/wiki#user-content-spawning-new-terminal-instances-in-the-current-working-directory),
the new terminal will start in the current working directory.
<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>o</kbd>
: Enter URL mode, where all currently visible URLs are tagged with a
jump label with a key sequence that will open the URL.
jump label with a key sequence that will open the URL.
<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>u</kbd>
: Enter Unicode input mode.
<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>z</kbd>
: Jump to the previous, currently not visible, prompt. Requires [shell
integration](https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts).
integration](https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts).
<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>x</kbd>
: Jump to the next prompt. Requires [shell
integration](https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts).
integration](https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts).
#### Scrollback search
@ -191,12 +181,12 @@ These are the default shortcuts. See `man foot.ini` and the example
<kbd>ctrl</kbd>+<kbd>w</kbd>
: Extend current selection (and thus the search criteria) to the end
of the word, or the next word if currently at a word separating
character.
of the word, or the next word if currently at a word separating
character.
<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>w</kbd>
: Same as <kbd>ctrl</kbd>+<kbd>w</kbd>, except that the only word
separating characters are whitespace characters.
separating characters are whitespace characters.
<kbd>ctrl</kbd>+<kbd>v</kbd>, <kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>v</kbd>, <kbd>ctrl</kbd>+<kbd>y</kbd>, <kbd>XF86Paste</kbd>
: Paste from clipboard into the search buffer.
@ -209,8 +199,7 @@ These are the default shortcuts. See `man foot.ini` and the example
<kbd>return</kbd>
: Finish the search and copy the current match to the primary
selection
selection
### URL mode
@ -220,25 +209,24 @@ These are the default shortcuts. See `man foot.ini` and the example
<kbd>escape</kbd>, <kbd>ctrl</kbd>+<kbd>c</kbd>, <kbd>ctrl</kbd>+<kbd>g</kbd>, <kbd>ctrl</kbd>+<kbd>d</kbd>
: Exit URL mode without launching any URLs
### Mouse
<kbd>left</kbd> - **single-click**
: Drag to select; when released, the selected text is copied to the
_primary_ selection. This feature is **disabled** when client has
enabled _mouse tracking_.
_primary_ selection. This feature is **disabled** when client has
enabled _mouse tracking_.
: Holding <kbd>shift</kbd> enables selection in mouse tracking enabled
clients.
clients.
: Holding <kbd>ctrl</kbd> will create a block selection.
<kbd>left</kbd> - **double-click**
: Selects the _word_ (separated by spaces, period, comma, parenthesis
etc) under the pointer. Hold <kbd>ctrl</kbd> to select everything
under the pointer up to, and until, the next space characters.
etc) under the pointer. Hold <kbd>ctrl</kbd> to select everything
under the pointer up to, and until, the next space characters.
<kbd>left</kbd> - **triple-click**
: Selects the everything between enclosing quotes, or the entire row
if not inside a quote.
if not inside a quote.
<kbd>left</kbd> - **quad-click**
: Selects the entire row.
@ -248,12 +236,12 @@ These are the default shortcuts. See `man foot.ini` and the example
<kbd>right</kbd>
: Extend current selection. Clicking immediately extends the
selection, while hold-and-drag allows you to interactively resize
the selection.
selection, while hold-and-drag allows you to interactively resize
the selection.
<kbd>ctrl</kbd>+<kbd>right</kbd>
: Extend the current selection, but force it to be character wise,
rather than depending on the original selection mode.
rather than depending on the original selection mode.
<kbd>wheel</kbd>
: Scroll up/down in history
@ -261,7 +249,6 @@ These are the default shortcuts. See `man foot.ini` and the example
<kbd>ctrl</kbd>+<kbd>wheel</kbd>
: Increase/decrease font size
### Touchscreen
<kbd>tap</kbd>
@ -270,8 +257,7 @@ These are the default shortcuts. See `man foot.ini` and the example
<kbd>drag</kbd>
: Scrolls up/down in history.
: Holding for a while before dragging (time delay can be configured)
emulates mouse dragging with left button held.
emulates mouse dragging with left button held.
## Server (daemon) mode
@ -333,7 +319,6 @@ the clipboard. It is unbound by default.
Jump label colors, the URL underline color, and the letters used in
the jump label key sequences can be configured.
## Shell integration
### Current working directory
@ -348,7 +333,6 @@ scripted to do this, if they do not support it natively. See the
[wiki](https://codeberg.org/dnkl/foot/wiki#user-content-spawning-new-terminal-instances-in-the-current-working-directory)
for details.
### Jumping between prompts
Foot can move the current viewport to focus prompts of already
@ -407,7 +391,6 @@ See the
[wiki](https://codeberg.org/dnkl/foot/wiki#user-content-piping-last-command-s-output)
for details, and examples for other shells
## Alt/meta
By default, foot prefixes _Meta characters_ with ESC. This corresponds
@ -424,7 +407,6 @@ This can also be disabled programmatically with `rmm` (_reset meta
mode_, `\E[?1034l`), and enabled again with `smm` (_set meta mode_,
`\E[?1034h`).
## Backspace
Foot transmits DEL (`^?`) on <kbd>backspace</kbd>. This corresponds to
@ -440,7 +422,6 @@ described above **cannot** be changed.
Finally, pressing <kbd>alt</kbd> will prefix the transmitted byte with
ESC.
## Keypad
By default, <kbd>Num Lock</kbd> overrides the run-time configuration
@ -459,7 +440,6 @@ again with `\E[?1035h`).
When disabled, the keypad sends custom escape sequences instead of
numbers, when in _application_ mode.
## DPI and font size
Font sizes are apparently a complex thing. Many applications use a
@ -503,7 +483,6 @@ distance**, the font size will appear to be the same, at all times.
_Note_: if you configure **pixelsize**, rather than **size**, then DPI
changes will **not** change the font size. Pixels are always pixels.
### Fractional scaling on Wayland
For a long time, there was no **true** support for _fractional
@ -520,42 +499,40 @@ allows compositors to tell applications the _actual_ scaling
factor. Applications can then scale the image using a _viewport_
object, instead of setting a scale factor on the raw pixel buffer.
## Supported OSCs
OSC, _Operating System Command_, are escape sequences that interacts
with the terminal emulator itself. Foot implements the following OSCs:
* `OSC 0` - change window icon + title (but only title is actually
- `OSC 0` - change window icon + title (but only title is actually
supported)
* `OSC 2` - change window title
* `OSC 4` - change color palette
* `OSC 7` - report CWD (see [shell integration](#shell-integration))
* `OSC 8` - hyperlink
* `OSC 9` - desktop notification
* `OSC 10` - change (default) foreground color
* `OSC 11` - change (default) background color
* `OSC 12` - change cursor color
* `OSC 17` - change highlight (selection) background color
* `OSC 19` - change highlight (selection) foreground color
* `OSC 22` - set the xcursor (mouse) pointer
* `OSC 52` - copy/paste clipboard data
* `OSC 104` - reset color palette
* `OSC 110` - reset default foreground color
* `OSC 111` - reset default background color
* `OSC 112` - reset cursor color
* `OSC 117` - reset highlight background color
* `OSC 119` - reset highlight foreground color
* `OSC 133` - [shell integration](#shell-integration)
* `OSC 176` - set app ID
* `OSC 555` - flash screen (**foot specific**)
* `OSC 777` - desktop notification (only the `;notify` sub-command of
- `OSC 2` - change window title
- `OSC 4` - change color palette
- `OSC 7` - report CWD (see [shell integration](#shell-integration))
- `OSC 8` - hyperlink
- `OSC 9` - desktop notification
- `OSC 10` - change (default) foreground color
- `OSC 11` - change (default) background color
- `OSC 12` - change cursor color
- `OSC 17` - change highlight (selection) background color
- `OSC 19` - change highlight (selection) foreground color
- `OSC 22` - set the xcursor (mouse) pointer
- `OSC 52` - copy/paste clipboard data
- `OSC 104` - reset color palette
- `OSC 110` - reset default foreground color
- `OSC 111` - reset default background color
- `OSC 112` - reset cursor color
- `OSC 117` - reset highlight background color
- `OSC 119` - reset highlight foreground color
- `OSC 133` - [shell integration](#shell-integration)
- `OSC 176` - set app ID
- `OSC 555` - flash screen (**foot specific**)
- `OSC 777` - desktop notification (only the `;notify` sub-command of
OSC 777 is supported.)
See the **foot-ctlseqs**(7) man page for a complete list of supported
control sequences.
## Programmatically checking if running in foot
Foot does **not** set any environment variables that can be used to
@ -589,7 +566,6 @@ which it will reply with `\EP>|foot(version)\E\\`. Version is
e.g. "1.8.2" for a regular release, or "1.8.2-36-g7db8e06f" for a git
build.
# XTGETTCAP
`XTGETTCAP` is an escape sequence initially introduced by XTerm, and
@ -604,9 +580,9 @@ foot's terminfo on remote hosts you SSH into.
XTerm's implementation (as of XTerm-370) only supports querying key
(as in keyboard keys) capabilities, and three custom capabilities:
* `TN` - terminal name
* `Co` - number of colors (alias for the `colors` capability)
* `RGB` - number of bits per color channel (different semantics from
- `TN` - terminal name
- `Co` - number of colors (alias for the `colors` capability)
- `RGB` - number of bits per color channel (different semantics from
the `RGB` capability in file-based terminfo definitions!).
Kitty has extended this, and also supports querying all integer and
@ -622,11 +598,11 @@ multi-capability queries slightly differently, compared to XTerm.
XTerm will send a single DCS reply, with `;`-separated
capability/value pairs. There are a couple of issues with this:
* The success/fail flag in the beginning of the response is always `1`
- The success/fail flag in the beginning of the response is always `1`
(success), unless the very **first** queried capability is invalid.
* XTerm will not respond **at all** to an invalid capability, unless
- XTerm will not respond **at all** to an invalid capability, unless
it's the first one in the `XTGETTCAP` query.
* XTerm will end the response at the first invalid capability.
- XTerm will end the response at the first invalid capability.
In other words, if you send a large multi-capability query, you will
only get responses up to, but not including, the first invalid
@ -645,18 +621,15 @@ In addition to queries for terminfo entries, the `query-os-name` query
will be answered with a response of the form `uname=$(uname -s)`,
where `$(uname -s)` is the name of the OS foot was compiled for.
# Credits
* [Ordoviz](https://codeberg.org/Ordoviz), for designing and
contributing foot's [logo](icons/hicolor/48x48/apps/foot.png).
- [Ordoviz](https://codeberg.org/Ordoviz), for designing and
contributing foot's [logo](icons/hicolor/48x48/apps/foot.png).
# Code of Conduct
See [Code of Conduct](CODE_OF_CONDUCT.md)
# Bugs
Please report bugs to https://codeberg.org/dnkl/foot/issues
@ -674,7 +647,6 @@ The report should contain the following:
with symbols.
- Steps to reproduce. The more details the better.
# Contact
## IRC
@ -684,21 +656,22 @@ channel on
[irc.libera.chat](https://web.libera.chat/?channels=#foot). Logs are
available at https://libera.irclog.whitequark.org/foot.
## Mastodon
Every now and then I post foot related updates on
[@dnkl@social.treehouse.systems](https://social.treehouse.systems/@dnkl)
# Sponsoring/donations
* Liberapay: https://liberapay.com/dnkl
* GitHub Sponsors: https://github.com/sponsors/dnkl
- Liberapay: https://liberapay.com/dnkl
- GitHub Sponsors: https://github.com/sponsors/dnkl
[![Donate using Liberapay](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/dnkl/donate)
# License
Foot is released under the [MIT license](LICENSE).
## Educational Note
This repository is used for learning Git workflow.