1# ![Logo: a terminal with a foot shaped prompt](icons/hicolor/48x48/apps/foot.png) foot 2 3The fast, lightweight and minimalistic Wayland terminal emulator. 4 5[![CI status](https://ci.codeberg.org/api/badges/dnkl/foot/status.svg)](https://ci.codeberg.org/dnkl/foot) 6[![Pipeline status](https://gitlab.com/dnkl/foot/badges/master/pipeline.svg)](https://gitlab.com/dnkl/foot/commits/master) 7[![builds.sr.ht status](https://builds.sr.ht/~dnkl/foot.svg)](https://builds.sr.ht/~dnkl/foot?) 8 9[![Packaging status](https://repology.org/badge/vertical-allrepos/foot.svg)](https://repology.org/project/foot/versions) 10 11 12## Index 13 141. [Features](#features) 151. [Installing](#installing) 161. [Configuration](#configuration) 171. [Troubleshooting](#troubleshooting) 181. [Why the name 'foot'?](#why-the-name-foot) 191. [Fonts](#fonts) 201. [Shortcuts](#shortcuts) 21 1. [Keyboard](#keyboard) 22 1. [Normal mode](#normal-mode) 23 1. [Scrollback search](#scrollback-search) 24 1. [Mouse](#mouse) 251. [Server (daemon) mode](#server-daemon-mode) 261. [URLs](#urls) 271. [Alt/meta](#alt-meta) 281. [Backspace](#backspace) 291. [Keypad](#keypad) 301. [DPI and font size](#dpi-and-font-size) 311. [Supported OSCs](#supported-oscs) 321. [Programmatically checking if running in foot](#programmatically-checking-if-running-in-foot) 331. [Credits](#Credits) 341. [Bugs](#bugs) 351. [Contact](#contact) 36 1. [IRC](#irc) 37 1. [Mastodon](#mastodon) 381. [Sponsoring/donations](#sponsoring-donations) 391. [License](#license) 40 41 42## Features 43 44* Fast (see [benchmarks](doc/benchmark.md), and 45 [performance](https://codeberg.org/dnkl/foot/wiki/Performance)) 46* Lightweight, in dependencies, on-disk and in-memory 47* Wayland native 48* DE agnostic 49* Server/daemon mode 50* User configurable font fallback 51* On-the-fly font resize 52* On-the-fly DPI font size adjustment 53* Scrollback search 54* Keyboard driven URL detection 55* Color emoji support 56* IME (via `text-input-v3`) 57* Multi-seat 58* True Color (24bpp) 59* [Synchronized Updates](https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/2) support 60* [Sixel image support](https://en.wikipedia.org/wiki/Sixel) 61 62 ![wow](doc/sixel-wow.png "Sixel screenshot") 63 64 65# Installing 66 67See [INSTALL.md](INSTALL.md). 68 69 70## Configuration 71 72**foot** can be configured by creating a file 73`$XDG_CONFIG_HOME/foot/foot.ini` (defaulting to 74`~/.config/foot/foot.ini`). A template for that can usually be found 75in `/usr/share/foot/foot.ini` or 76[here](https://codeberg.org/dnkl/foot/src/branch/master/foot.ini). 77 78Further information can be found in foot's man page `foot.ini(5)`. 79 80 81## Troubleshooting 82 83See the [wiki](https://codeberg.org/dnkl/foot/wiki#user-content-troubleshooting) 84 85 86## Why the name 'foot'? 87 88I'm bad at names. Most of my projects usually start out as _foo 89something_ (for example, [yambar](https://codeberg.org/dnkl/yambar) 90was _f00bar_ for a while). 91 92So why _foot_? 93 94_foo terminal_ → _footerm_ → _foot_ 95 96Pretty bad, I know. 97 98As a side note, if you pronounce the _foo_ part of _foot_ the same way 99you pronounce _foobar_, then _foot_ sounds a lot like the Swedish word 100_fot_, which incidentally means (you guessed it) _foot_. 101 102 103## Fonts 104 105**foot** supports all fonts that can be loaded by _freetype_, 106including **bitmap** fonts and **color emoji** fonts. 107 108Foot uses _fontconfig_ to locate and configure the font(s) to 109use. Since fontconfig's fallback mechanism is imperfect, especially 110for monospace fonts (it doesn't prefer monospace fonts even though the 111requested font is one), foot allows you, the user, to configure the 112fallback fonts to use. 113 114This also means you can configure _each_ fallback font individually; 115you want _that_ fallback font to use _this_ size, and you want that 116_other_ fallback font to be _italic_? No problem! 117 118If a glyph cannot be found in _any_ of the user configured fallback 119fonts, _then_ fontconfig's list is used. 120 121 122## Shortcuts 123 124These are the default shortcuts. See `man foot.ini` and the example 125`foot.ini` to see how these can be changed. 126 127 128### Keyboard 129 130#### Normal mode 131 132<kbd>shift</kbd>+<kbd>page up</kbd>/<kbd>page down</kbd> 133: Scroll up/down in history 134 135<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>c</kbd> 136: Copy selected text to the _clipboard_ 137 138<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>v</kbd> 139: Paste from _clipboard_ 140 141<kbd>shift</kbd>+<kbd>insert</kbd> 142: Paste from the _primary selection_ 143 144<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>r</kbd> 145: Start a scrollback search 146 147<kbd>ctrl</kbd>+<kbd>+</kbd>, <kbd>ctrl</kbd>+<kbd>=</kbd> 148: Increase font size by 0,5pt 149 150<kbd>ctrl</kbd>+<kbd>-</kbd> 151: Decrease font size by 0,5pt 152 153<kbd>ctrl</kbd>+<kbd>0</kbd> 154: Reset font size 155 156<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>n</kbd> 157: Spawn a new terminal. If the shell has been [configured to emit the 158 OSC 7 escape 159 sequence](https://codeberg.org/dnkl/foot/wiki#user-content-how-to-configure-my-shell-to-emit-the-osc-7-escape-sequence), 160 the new terminal will start in the current working directory. 161 162<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>u</kbd> 163: Enter URL mode, where all currently visible URLs are tagged with a 164 jump label with a key sequence that will open the URL. 165 166 167#### Scrollback search 168 169<kbd>ctrl</kbd>+<kbd>r</kbd> 170: Search _backward_ for next match 171 172<kbd>ctrl</kbd>+<kbd>s</kbd> 173: Search _forward_ for next match 174 175<kbd>ctrl</kbd>+<kbd>w</kbd> 176: Extend current selection (and thus the search criteria) to the end 177 of the word, or the next word if currently at a word separating 178 character. 179 180<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>w</kbd> 181: Same as <kbd>ctrl</kbd>+<kbd>w</kbd>, except that the only word 182 separating characters are whitespace characters. 183 184<kbd>ctrl</kbd>+<kbd>v</kbd> 185: Paste from clipboard into the search buffer. 186 187<kbd>shift</kbd>+<kbd>insert</kbd> 188: Paste from primary selection into the search buffer. 189 190<kbd>escape</kbd>, <kbd>ctrl</kbd>+<kbd>g</kbd> 191: Cancel the search 192 193<kbd>return</kbd> 194: Finish the search and copy the current match to the primary 195 selection 196 197### Mouse 198 199<kbd>left</kbd> - **single-click** 200: Drag to select; when released, the selected text is copied to the 201 _primary_ selection. This feature is **disabled** when client has 202 enabled _mouse tracking_. 203: Holding <kbd>shift</kbd> enables selection in mouse tracking enabled 204 clients. 205: Holding <kbd>ctrl</kbd> will create a block selection. 206 207<kbd>left</kbd> - **double-click** 208: Selects the _word_ (separated by spaces, period, comma, parenthesis 209 etc) under the pointer. Hold <kbd>ctrl</kbd> to select everything 210 under the pointer up to, and until, the next space characters. 211 212<kbd>left</kbd> - **triple-click** 213: Selects the entire row 214 215<kbd>middle</kbd> 216: Paste from _primary_ selection 217 218<kbd>right</kbd> 219: Extend current selection. Clicking immediately extends the 220 selection, while hold-and-drag allows you to interactively resize 221 the selection. 222 223<kbd>wheel</kbd> 224: Scroll up/down in history 225 226 227## Server (daemon) mode 228 229When run normally, **foot** is a single-window application; if you 230want another window, start another foot process. 231 232However, foot can also be run in a _server_ mode. In this mode, one 233process hosts multiple windows. All Wayland communication, VT parsing 234and rendering is done in the server process. 235 236New windows are opened by running `footclient`, which remains running 237until the terminal window is closed, at which point it exits with the 238exit value of the client process (typically the shell). 239 240The point of this mode is **a)** reduced memory footprint - all 241terminal windows will share fonts and glyph cache, and **b)** reduced 242startup time - loading fonts and populating the glyph cache takes 243time, but in server mode it only happens once. 244 245The downside is a performance penalty; all windows' input and output 246are multiplexed in the same thread (but each window will have its own 247set of rendering threads). This means that if one window is very busy 248with, for example, producing output, then other windows will suffer. 249 250And of course, should the server process crash, **all** windows will 251be gone. 252 253Typical usage would be to start the server process (`foot --server`) 254when starting your Wayland compositor (i.e. logging in to your 255desktop), and then run `footclient` instead of `foot` whenever you 256want to launch a new terminal. 257 258 259## URLs 260 261Foot supports URL detection. But, unlike many other terminal 262emulators, where URLs are highlighted when they are hovered and opened 263by clicking on them, foot uses a keyboard driven approach. 264 265Pressing <kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>u</kbd> enters _“URL 266mode”_, where all currently visible URLs are underlined, and is 267associated with a _“jump-label”_. The jump-label indicates the _key 268sequence_ (e.g. **”AF”**) to use to activate the URL. 269 270The key binding can, of course, be customized, like all other key 271bindings in foot. See `show-urls-launch` and `show-urls-copy` in the 272`foot.ini` man page. 273 274`show-urls-launch` by default opens the URL with `xdg-open`. This can 275be changed with the `url-launch` option. 276 277`show-urls-copy` is an alternative to `show-urls-launch`, that changes 278what activating an URL _does_; instead of opening it, it copies it to 279the clipboard. It is unbound by default. 280 281Jump label colors, the URL underline color, and the letters used in 282the jump label key sequences can be configured. 283 284 285## Alt/meta 286 287By default, foot prefixes _Meta characters_ with ESC. This corresponds 288to XTerm's `metaSendsEscape` option set to `true`. 289 290This can be disabled programmatically with `\E[?1036l` (and enabled 291again with `\E[?1036h`). 292 293When disabled, foot will instead set the 8:th bit of meta character 294and then UTF-8 encode it. This corresponds to XTerm's `eightBitMeta` 295option set to `true`. 296 297This can also be disabled programmatically with `rmm` (_reset meta 298mode_, `\E[?1034l`), and enabled again with `smm` (_set meta mode_, 299`\E[?1034h`). 300 301 302## Backspace 303 304Foot transmits DEL (`^?`) on <kbd>backspace</kbd>. This corresponds to 305XTerm's `backarrowKey` option set to `false`, and to DECBKM being 306_reset_. 307 308To instead transmit BS (`^H`), press 309<kbd>ctrl</kbd>+<kbd>backspace</kbd>. 310 311Note that foot does **not** implement DECBKM, and that the behavior 312described above **cannot** be changed. 313 314Finally, pressing <kbd>alt</kbd> will prefix the transmitted byte with 315ESC. 316 317 318## Keypad 319 320By default, <kbd>Num Lock</kbd> overrides the run-time configuration 321keypad mode; when active, the keypad is always considered to be in 322_numerical_ mode. This corresponds to XTerm's `numLock` option set to 323`true`. 324 325In this mode, the keypad keys always sends either numbers (<kbd>Num 326Lock</kbd> is **active**) or cursor movement keys (<kbd>Up</kbd>, 327<kbd>Down</kbd>, <kbd>Left</kbd>, <kbd>Right</kbd>, <kbd>Page 328Up</kbd>, <kbd>Page Down</kbd> etc). 329 330This can be disabled programmatically with `\E[?1035l` (and enabled 331again with `\E[?1035h`). 332 333When disabled, the keypad sends custom escape sequences instead of 334numbers, when in _application_ mode. 335 336 337## DPI and font size 338 339Font sizes are apparently a complex thing. Many applications use a 340fixed DPI of 96. They may also multiply it with the monitor's scale 341factor. 342 343This results in fonts with different **physical** sizes (i.e. if 344measured by a ruler) when rendered on screens with different DPI 345values. Even if the configured font size is the same. 346 347This is not how it is meant to be. Fonts are measured in _point sizes_ 348**for a reason**; a given point size should have the same height on 349all mediums, be it printers or monitors, regardless of their DPI. 350 351Foot’s default behavior is to use the monitor’s DPI to size fonts when 352output scaling has been disabled on **all** monitors. If at least one 353monitor has output scaling enabled, fonts will instead by sized using 354the scaling factor. 355 356This can be changed to either **always** use the monitor’s DPI 357(regardless of scaling factor), or to **never** use it, with the 358`dpi-aware` option in `foot.ini`. See the man page, **foot.ini**(5) 359for more information. 360 361When fonts are sized using the monitor’s DPI, glyphs should always 362have the same physical height, regardless of monitor. 363 364Furthermore, foot will re-size the fonts on-the-fly when the window is 365moved between screens with different DPIs values. If the window covers 366multiple screens, with different DPIs, the highest DPI will be used. 367 368_Note_: if you configure **pixelsize**, rather than **size**, then DPI 369changes will **not** change the font size. Pixels are always pixels. 370 371 372## Supported OSCs 373 374OSC, _Operating System Command_, are escape sequences that interacts 375with the terminal emulator itself. Foot implements the following OSCs: 376 377* `OSC 0` - change window icon + title (but only title is actually 378 supported) 379* `OSC 2` - change window title 380* `OSC 4` - change color palette 381* `OSC 7` - report CWD 382* `OSC 8` - hyperlink 383* `OSC 9` - desktop notification 384* `OSC 10` - change (default) foreground color 385* `OSC 11` - change (default) background color 386* `OSC 12` - change cursor color 387* `OSC 17` - change highlight (selection) background color 388* `OSC 19` - change highlight (selection) foreground color 389* `OSC 52` - copy/paste clipboard data 390* `OSC 104` - reset color palette 391* `OSC 110` - reset default foreground color 392* `OSC 111` - reset default background color 393* `OSC 112` - reset cursor color 394* `OSC 117` - reset highlight background color 395* `OSC 119` - reset highlight foreground color 396* `OSC 555` - flash screen (**foot specific**) 397* `OSC 777` - desktop notification (only the `;notify` sub-command of 398 OSC 777 is supported.) 399 400 401## Programmatically checking if running in foot 402 403Foot does **not** set any environment variables that can be used to 404identify foot (reading `TERM` is not reliable since the user may have 405chosen to use a different terminfo). 406 407You can instead use the escape sequences to read the _Secondary_ and 408_Tertiary Device Attributes_ (secondary/tertiary DA, for short). 409 410The tertiary DA response is always `\EP!|464f4f54\E\\`, where 411`464f4f54` is `FOOT` in hex. 412 413The secondary DA response is `\E[>1;XXYYZZ;0c`, where `XXYYZZ` is 414foot's major, minor and patch version numbers, in decimal, using two 415digits for each number. For example, foot-1.4.2 would respond with 416`\E[>1;010402;0c`. 417 418**Note**: not all terminal emulators implement tertiary DA. Most 419implement secondary DA, but not all. All _should_ however implement 420_Primary DA_. 421 422Thus, a safe way to query the terminal is to request the tertiary, 423secondary and primary DA all at once, in that order. All terminals 424should ignore escape sequences they do not recognize. You will have to 425parse the response (which in foot will consist of all three DA 426responses, all at once) to determine which requests the terminal 427emulator actually responded to. 428 429Starting with version 1.7.0, foot also implements `XTVERSION`, to 430which it will reply with `\EP>|foot(version)\E\\`. Version is 431e.g. “1.8.2” for a regular release, or “1.8.2-36-g7db8e06f” for a git 432build. 433 434 435# Credits 436 437* [Ordoviz](https://codeberg.org/Ordoviz), for designing and 438contributing foot's [logo](icons/hicolor/48x48/apps/foot.png). 439 440 441# Bugs 442 443Please report bugs to https://codeberg.org/dnkl/foot/issues 444 445Before you open a new issue, please search existing bug reports, both 446open **and** closed ones. Chances are someone else has already 447reported the same issue. 448 449The report should contain the following: 450 451- Foot version (`foot --version`). 452- Log output from foot (start foot from another terminal). 453- Which Wayland compositor (and version) you are running. 454- If reporting a crash, please try to provide a `bt full` backtrace 455 with symbols. 456- Steps to reproduce. The more details the better. 457 458 459# Contact 460 461## IRC 462 463Ask questions, hang out, sing praise or just say hi in the `#foot` 464channel on [irc.libera.chat](https://libera.chat). Logs are available 465at https://libera.irclog.whitequark.org/foot. 466 467 468## Mastodon 469 470Every now and then I post foot related updates on 471[@dnkl@linuxrocks.online](https://linuxrocks.online/@dnkl) 472 473 474# Sponsoring/donations 475 476* GitHub Sponsors: https://github.com/sponsors/dnkl 477 478 479# License 480 481Foot is released under the [MIT license](LICENSE). 482