Codebergdnkl

foot

master
ply5 git calls470 ms53 KiB3 cachedprotocol v2
2182 lines75 KiBRaw
1foot.ini(5)
3# NAME
5foot.ini - configuration file for *foot*(1)
7# DESCRIPTION
9*foot* uses the standard _unix configuration format_, with section based
10key/value pairs. The default section is usually unnamed, i.e. not prefixed
11with a _[section]_. However it can also be explicitly named _[main]_,
12say if it needs to be reopened after any of the other sections.
14foot will search for a configuration file in the following locations,
15in this order:
17 - *XDG_CONFIG_HOME/foot/foot.ini* (defaulting to
18 *$HOME/.config/foot/foot.ini* if unset)
19 - *XDG_CONFIG_DIRS/foot/foot.ini* (defaulting to
20 */etc/xdg/foot/foot.ini* if unset)
22An example configuration file containing all options with their default value
23commented out will usually be installed to */etc/xdg/foot/foot.ini*.
25Options are set using KEY=VALUE pairs:
27 *\[colors-dark\]*++
28*background=000000*++
29*foreground=ffffff*
31Empty values (*KEY=*) are not supported. String options do allow the
32empty string to be set, but it must be quoted: *KEY=""*
34# SECTION: main
36*shell*
37 Executable to launch. Typically a shell. Default: _$SHELL_ if set,
38 otherwise the user's default shell (as specified in
39 _/etc/passwd_). You can also pass arguments. For example
40 */bin/bash --norc*.
42*login-shell*
43 Boolean. If enabled, the shell will be launched as a login shell,
44 by prepending a '-' to argv[0]. Default: _no_.
46*term*
47 Value to set the environment variable *TERM* to. Default:
48 _@default_terminfo@_
50*font*, *font-bold*, *font-italic*, *font-bold-italic*
51 Comma separated list of fonts to use, in fontconfig format. That
52 is, a font name followed by a list of colon-separated
53 options. Most noteworthy is *:size=n* (or *:pixelsize=n*), which
54 is used to set the font size. Note that the font size is also
55 affected by the *dpi-aware* option.
57 Examples:
58 - Dina:weight=bold:slant=italic
59 - Courier New:size=12
60 - Fantasque Sans Mono:fontfeatures=ss01
61 - Iosevka:fontfeatures=cv01=1:fontfeatures=cv06=1
62 - Meslo LG S:size=12, Noto Color Emoji:size=12
63 - Courier New:pixelsize=8
65 Be aware that, depending on your setup, there may be global
66 FontConfig options that overrides options set here. If an option
67 appears to have no effect, ensure there is no global configuration
68 file that sets the same option with *assign* or *assign_replace*;
69 use one of the many *append* or possibly *prepend* modes.
71 For each option, the first font is the primary font. The remaining
72 fonts are fallback fonts that will be used whenever a glyph cannot
73 be found in the primary font.
75 The fallback fonts are searched in the order they appear. If a
76 glyph cannot be found in any of the fallback fonts, the dynamic
77 fallback list from fontconfig (for the primary font) is
78 searched.
80 *font-bold*, *font-italic* and *font-bold-italic* allow custom
81 fonts to be used for bold/italic/bold+italic fonts. If left
82 unconfigured, the bold/italic variants of the regular font(s)
83 specified in *font* are used. *Note*: you _may_ have to tweak the
84 size(s) of the custom bold/italic fonts to match the regular font.
86 To disable bold and/or italic fonts, set e.g. *font-bold* to
87 _exactly_ the same value as *font*.
89 **size** is in _points_ (as defined by the FontConfig format). To
90 set a _pixel_ size, use **pixelsize** instead. Note that pixel
91 sizes are unaffected by DPI aware rendering (see *dpi-aware*), but
92 are affected by desktop scaling.
94 Default: _monospace:size=8_ (*font*), _not set_ (*font-bold*,
95 *font-italic*, *font-bold-italic*).
97*font-size-adjustment*
98 Amount, in _points_, _pixels_ or _percent_, to increment/decrement
99 the font size when zooming in or out.
101 Examples:
102 ```
103 font-size-adjustment=0.5 # Adjust by 0.5 points
104 font-size-adjustment=10px # Adjust by 10 pixels
105 font-size-adjustment=7.5% # Adjust by 7.5 percent
106 ```
108 Default: _0.5_
110*include*
111 Absolute path to configuration file to import.
113 The import file has its own section scope. I.e. the including
114 configuration is still in the default section after the include,
115 regardless of which section the included file ends in.
117 - The path must be an absolute path, or start with *~/*.
118 - Multiple include directives are allowed, but only one path per
119 directive.
120 - Nested imports are allowed.
122 Default: _not set_.
124*line-height*
125 An absolute value, in _points_, that override line height from the
126 font metrics.
128 You can specify a height in _pixels_ by using the *px* suffix:
129 e.g. *line-height=12px*.
131 *Warning*: when changing the font size at runtime (i.e. zooming in
132 or out), foot will change the line height by the same
133 percentage. However, due to rounding, it is possible the line
134 height will be "too small" for some font sizes, causing
135 e.g. underscores to "disappear".
137 See also: *vertical-letter-offset*.
139 Default: _not set_.
141*letter-spacing*
142 Spacing between letters, in _points_. A positive value will
143 increase the cell size, and a negative value shrinks it.
145 You can specify a letter spacing in _pixels_ by using the *px*
146 suffix: e.g. *letter-spacing=2px*.
148 See also: *horizontal-letter-offset*.
150 Default: _0_.
152*horizontal-letter-offset*, *vertical-letter-offset*
153 Configure the horizontal and vertical offsets used when
154 positioning glyphs within cells, in _points_, relative to the top
155 left corner.
157 To specify an offset in _pixels_, append *px*:
158 e.g. *horizontal-letter-offset=2px*.
160 Default: _0_.
162*underline-offset*
163 Use a custom offset for underlines. The offset is, by default, in
164 _points_ and relative to the font's baseline. A positive value
165 positions the underline under the baseline, while a negative value
166 positions it above the baseline.
168 To specify an offset in _pixels_, append *px*:
169 *underline-offset=2px*.
171 If left unset (the default), the offset specified in the font is
172 used, or estimated by foot if the font lacks underline positioning
173 information.
175 Default: _unset_.
177*underline-thickness*
178 Use a custom thickness (height) for underlines. The thickness is, by
179 default, in _points_.
181 To specify a thickness in _pixels_, append *px*:
182 *underline-thickness=1px*.
184 If left unset (the default), the thickness specified in the font is
185 used.
187 Default: _unset_
189*strikeout-thickness*
190 Use a custom thickness (height) for strikeouts. The thickness is, by
191 default, in _points_.
193 To specify a thickness in _pixels_, append *px*:
194 *strikeout-thickness=1px*.
196 If left unset (the default), the thickness specified in the font is
197 used.
199 Default: _unset_
201*gamma-correct-blending*
202 Boolean. When enabled, foot will do gamma-correct blending in
203 linear color space. This is how font glyphs are supposed to be
204 rendered, but since nearly no applications or toolkits are doing
205 it on Linux, the result may not look like you are used to.
207 Compared to the default (disabled), bright glyphs on a dark
208 background will appear thicker, and dark glyphs on a light
209 background will appear thinner.
211 FreeType can limit the effect of the latter, with a technique
212 called stem darkening. It is only available for CFF fonts
213 (OpenType, .otf) and disabled by default (in FreeType). You can
214 enable it by setting the environment variable
215 *FREETYPE_PROPERTIES="cff:no-stem-darkening=0"* before starting
216 foot.
218 Also be aware that many fonts have been developed on systems that
219 do not do gamma-correct blending, and may therefore look thicker
220 than intended when rendered with gamma-correct blending, since the
221 font designer set the font weight based on incorrect rendering.
223 In order to represent colors faithfully, higher precision image
224 buffers are required. By default, foot will use either 16-bit, or
225 10-bit color channels, depending on availability, when
226 gamma-correct blending is enabled. However, the high precision
227 buffers are slow; if you want to use gamma-correct blending, but
228 prefer speed (throughput and input latency) over accurate colors,
229 you can force 8-bit color channels by setting
230 *tweak.surface-bit-depth=8-bit*.
232 Default: _no_.
234*uppercase-regex-insert*
235 Boolean. When enabled, inputting an uppercase hint character in
236 *show-urls-copy* or *regex-copy* mode will insert the selected
237 text into the prompt in addition to copying it to the clipboard.
239 Default: _yes_
241*box-drawings-uses-font-glyphs*
242 Boolean. When disabled, foot generates box/line drawing characters
243 itself. There are several advantages to doing this instead of using
244 font glyphs:
246 - No antialiasing effects where e.g. line endpoints appear
247 dimmed down, or blurred.
248 - Line- and box characters are guaranteed to span the entire cell,
249 resulting in a gap-less appearance.
250 - No alignment issues, i.e. lines are centered when they should be.
251 - Many fonts lack some, or all, of the line- and box drawing
252 characters, causing fallback fonts to be used, which results
253 in out-of-place looking glyphs (for example, badly sized).
255 When enabled, box/line drawing characters are rendered using font
256 glyphs. This may result in a more uniform look, in some use cases.
258 When disabled, foot will render the following Unicode codepoints
259 by itself:
261 - U+02500 - U+0259F
262 - U+02800 - U+028FF
263 - U+1CD00 - U+1CDE5
264 - U+1Fb00 - U+1FB9B
266 Default: _no_.
268*dpi-aware*
269 Boolean.
271 When set to *yes*, fonts are sized using the monitor's DPI, making
272 a font of a given size have the same physical size, regardless of
273 monitor. In other words, if you drag a foot window between
274 different monitors, the font size remains the same.
276 In this mode, the monitor's scaling factor is ignored; doubling
277 the scaling factor will *not* double the font size.
279 When set to *no*, the monitor's DPI is ignored. The font is
280 instead sized using the monitor's scaling factor; doubling the
281 scaling factor *does* double the font size.
283 Note that this option typically does not work with bitmap fonts,
284 which only contain a pre-defined set of sizes, and cannot be
285 dynamically scaled. Whichever size (of the available ones) that
286 best matches the DPI or scaling factor, will be used.
288 Also note that if the font size has been specified in pixels
289 (*:pixelsize=*_N_, instead of *:size=*_N_), DPI scaling
290 (*dpi-aware=yes*) will have no effect (the specified pixel size
291 will be used as is). But, if the monitor's scaling factor is used
292 to size the font (*dpi-aware=no*), the font's pixel size will be
293 multiplied with the scaling factor.
295 Default: _no_
297*pad*
298 Padding between border and glyphs, in pixels (subject to output
299 scaling), in the form
301 ```
302 _XxY_ [center | center-when-fullscreen | center-when-maximized-and-fullscreen]
303 ```
304 or
305 ```
306 RIGHTxTOPxLEFTxBOTTOM [center | center-when-fullscreen | center-when-maximized-and-fullscreen]
307 ```
309 - `_XxY_` adds _at least_:
310 - X pixels on the left and right sides.
311 - Y pixels on the top and bottom sides.
313 - `LEFTxTOPxRIGHTxBOTTOM` adds **at least**:
314 - LEFT pixels to the left
315 - TOP pixels to the top
316 - RIGHT pixels to the right
317 - BOTTOM pixels to the bottom
319 When no centering is specified, the grid content is anchored to
320 the top left corner. I.e. if the window manager forces an odd
321 window size on foot, the additional pixels will be added to the
322 right and bottom sides.
324 If *center* is specified, the grid content is instead
325 centered. This may cause "jumpiness" when resizing the window.
327 With *center-when-fullscreen* and
328 *center-when-maximized-and-fullscreen*, the grid is anchored to
329 the top left corner, unless the window is maximized, or
330 fullscreened.
332 Default: _0x0_ center-when-maximized-and-fullscreen.
334*resize-delay-ms*
336 Time, in milliseconds, of "idle time" before foot performs text
337 reflow, and sends the new window dimensions to the client
338 application while doing an interactive resize of a foot
339 window. Idle time in this context is a period of time where the
340 window size is not changing.
342 In other words, while you are fiddling with the window size, foot
343 does not send the updated dimensions to the client. It also does a
344 fast "truncating" resize of the grid, instead of actually
345 reflowing the contents. Only when you pause the fiddling for
346 *resize-delay-ms* milliseconds is the client updated, and the
347 contents properly reflowed.
349 Emphasis is on _while_ here; as soon as the interactive resize
350 ends (i.e. when you let go of the window border), the final
351 dimensions are sent to the client, without any delays.
353 Setting it to 0 disables the delay completely.
355 Default: _100_.
357*resize-by-cells*
358 Boolean.
360 When set to *yes*, the window size will be constrained to multiples
361 of the cell size (plus any configured padding). When set to *no*,
362 the window size will be unconstrained, and padding may be adjusted
363 as necessary to accommodate window sizes that are not multiples of
364 the cell size.
366 This option only applies to floating windows. Sizes of maximized, tiled
367 or fullscreen windows will not be constrained to multiples of the cell
368 size.
370 Default: _yes_
372*resize-keep-grid*
373 Boolean.
375 When set to *yes*, the window size will be adjusted with changes in font
376 size to preserve the dimensions of the text grid. When set to *no*, the
377 window size will remain constant and the text grid will be adjusted as
378 necessary to fit the window.
380 This option only applies to floating windows.
382 Default: _yes_
384*initial-color-theme*
385 Selects which color theme to use, *dark*, or *light*.
387 *dark* uses the colors defined in the *colors-dark* section, while
388 *light* uses the colors from the *colors-light* section.
390 Use the *color-theme-switch-dark*, *color-theme-switch-light* and
391 *color-theme-toggle* key bindings to switch between the two themes
392 at runtime, or send SIGUSR1/SIGUSR2 to the foot process (see
393 *foot*(1) for details).
395 Default: _dark_
397*initial-window-size-pixels*
398 Initial window width and height in _pixels_ (subject to output
399 scaling), in the form _WIDTHxHEIGHT_. The height _includes_ the
400 titlebar when using CSDs. Mutually exclusive to
401 *initial-window-size-chars*.
403 Note that this option may not work as expected if fractional
404 scaling is being used, due to the fact that many compositors do
405 not report the correct scaling factor until after a window has
406 been mapped.
408 Default: _700x500_.
410*initial-window-size-chars*
411 Initial window width and height in _characters_, in the form
412 _WIDTHxHEIGHT_. Mutually exclusive to
413 *initial-window-size-pixels*.
415 Note that if you have a multi-monitor setup, with different
416 scaling factors, there is a possibility the window size will not
417 be set correctly. If that is the case, use
418 *initial-window-size-pixels* instead.
420 And, just like *initial-window-size-pixels*, this option may not
421 work as expected if fractional scaling is being used (see
422 *initial-window-size-pixels* for details).
424 Default: _not set_.
426*initial-window-mode*
427 Initial window mode for each newly spawned window: *windowed*,
428 *maximized* or *fullscreen*. Default: _windowed_.
430*title*
431 Initial window title. Default: _foot_.
433*locked-title*
434 Boolean. If enabled, applications are not allowed to change the
435 title at run-time. Default: _no_.
437*app-id*
438 Value to set the *app-id* property on the Wayland window to. The
439 compositor can use this value to e.g. group multiple windows, or
440 apply window management rules. Default: _foot_ (normal mode), or
441 _footclient_ (server mode).
443*toplevel-tag*
444 Value to set the *toplevel-tag* property on the Wayland window
445 to. The compositor can use this value for session management,
446 window rules etc. Default: _not set_
448*bold-text-in-bright*
449 Semi-boolean. When enabled, bold text is rendered in a brighter
450 color (in addition to using a bold font). The color is brightened
451 by blending it with white.
453 If set to *palette-based*, rather than a simple *yes|true*, colors
454 matching one of the 8 regular palette colors will be brightened
455 using the corresponding bright palette color. Other colors will
456 not be brightened.
458 Default: _no_.
460*word-delimiters*
461 String of characters that act as word delimiters when selecting
462 text. Note that whitespace characters are _always_ word
463 delimiters, regardless of this setting. Default: _,│`|:"'()[]{}<>_
465*selection-target*
466 Clipboard target to automatically copy selected text to. One of
467 *none*, *primary*, *clipboard* or *both*. Default: _primary_.
469*workers*
470 Number of threads to use for rendering. Set to 0 to disable
471 multithreading. Default: the number of available logical CPUs
472 (including SMT). Note that this is not always the best value. In
473 some cases, the number of physical _cores_ is better.
475 In case you have a ridiculous amount of cores and/or threads,
476 consider limiting the number of *workers*, since foot cannot
477 parallelize more than the number of visible rows.
479*utmp-helper*
480 Path to utmp logging helper binary.
482 When starting foot, an utmp record is created by launching the
483 helper binary with the following arguments:
485 ```
486 @utmp_add_args@
487 ```
489 When foot is closed, the utmp record is removed by launching the
490 helper binary with the following arguments:
492 ```
493 @utmp_del_args@
494 ```
496 Set to *none* to disable utmp records. Default: _@utmp_helper_path@_.
498# SECTION: environment
500This section is used to define environment variables that will be set
501in the client application, in addition to the variables inherited from
502the terminal process itself.
504The format is simply:
506*name*=_value_
508Note: do not set *TERM* here; use the *term* option in the main
509(default) section instead.
511# SECTION: security
513*osc52*
515 Whether OSC-52 (clipboard access) is enabled or disabled. One of
516 *disabled*, *copy-enabled*, *paste-enabled* or *enabled*.
518 OSC-52 gives terminal application access to the host clipboard
519 (i.e. the Wayland clipboard). This is normally not a security
520 issue, since all applications can access the clipboard directly
521 over the Wayland socket.
523 However, when SSH:ing into a remote system, or accessing a
524 container etc, the terminal applications may be untrusted, and you
525 might consider disabling the host clipboard access.
527 - *disabled*: disables all clipboard access
528 - *copy-enabled*: applications can write to the clipboard, but not
529 read from it.
530 - *paste-enabled*: applications can read from the clipboard, but
531 not write to it.
532 - *enabled*: all applications have full access to the host
533 clipboard. This is the default.
535 Default: _enabled_
538# SECTION: bell
540*system*
541 Boolean, when set to _yes_, ring the system bell. The bell is rung
542 independent of whether the foot window has keyboard focus or
543 not. Exact behavior is compositor dependent.
545 Default: _yes_
547*urgent*
548 Boolean, when set to _yes_, foot will signal urgency to the
549 compositor through the XDG activation protocol whenever *BEL* is
550 received, and the window does NOT have keyboard focus.
552 If the compositor does not implement this protocol, the margins
553 will be painted in red instead.
555 Applications can enable/disable this feature programmatically with
556 the *CSI ? 1042 h* and *CSI ? 1042 l* escape sequences.
558 Default: _no_
560*notify*
561 Boolean, when set to _yes_, foot will emit a desktop notification
562 using the command specified in the *notify* option whenever *BEL*
563 is received. By default, bell notifications are shown only when
564 the window does *not* have keyboard focus. See
565 _desktop-notifications.inhibit-when-focused_.
567 Default: _no_
569*visual*
570 Boolean, when set to _yes_, foot will flash the terminal
571 window. Default: _no_
573*command*
574 When set, foot will execute this command when *BEL* is received.
575 Default: none
577*command-focused*
578 Boolean, whether to run the command on *BEL* even while
579 focused. Default: _no_
581# SECTION: desktop-notifications
583*command*
584 Command to execute to display a notification.
586 Template arguments
587 _${title}_ and _${body}_ will be replaced with the
588 notification's actual _title_ and _body_ (message content).
590 _${app-id}_ is replaced with the value of the command line
591 option _--app-id_, and defaults to *foot* (normal mode), or
592 *footclient* (server mode).
594 _${window-title}_ is replaced with the current window title.
596 _${icon}_ is replaced by the icon specified in the
597 notification request, or the empty string if no icon was
598 specified. Can be used with e.g. notify-send's *--icon*
599 option, or preferably, by setting the *image-path* hint (with
600 e.g. notify-send's *--hint* option).
602 _${category}_ is replaced by the notification's category. Can
603 be used together with e.g. notify-send's *--category* option.
605 _${urgency}_ is replaced with the notifications urgency;
606 *low*, *normal* or *critical*. Can be used together with
607 e.g. notify-send's *--urgency* option.
609 _${expire-time}_ is replaced with the notification specified
610 notification timeout. Can be used together with
611 e.g. notify-send's *--expire-time* option.
613 _${replace-id}_ is replaced by the notification daemon
614 assigned ID that the notification replaces/updates. For this
615 to work, foot needs to know the externally assigned IDs of
616 previously emitted notifications, see the 'stdout' section
617 below. Can be used together with e.g. notify-send's
618 *--replace-id* option.
620 _${muted}_ is replaced by either *true* or *false*, depending
621 on whether the notification has requested all notification
622 sounds be muted. It is intended to set the *suppress-sound*
623 hint (with e.g. notify-send's *--hint* option).
625 _${sound-name}_ is replaced by sound-name requested by the
626 notification. This should be a name from the freedesktop sound
627 naming specification, but this is not something that foot
628 enforces. It is intended to set the *sound-name* hint (with
629 e.g. notify-send's *--hint* option).
631 _${action-argument}_ will be expanded to the
632 *command-action-argument* option, for each notification
633 action. There will always be at least one action, the
634 "default" action. Foot uses this to enable window focusing,
635 and reporting notification activation to applications that
636 requested such events.
638 Applications can also define their own custom notification
639 actions. See the *command-action-argument* option for details.
641 Ways to trigger notifications
642 Applications can trigger notifications in the following ways:
644 - OSC 777: *\\e]777;notify;<title>;<body>\\e\\\\*
645 - OSC 99: *\\e]99;;<title>\\e\\\\* (this is just a bare bones
646 example; this protocol has lots of features, see
647 https://sw.kovidgoyal.net/kitty/desktop-notifications)
649 By default, notifications are *inhibited* if the foot window
650 has keyboard focus. See
651 _desktop-notifications.inhibit-when-focused_.
653 Window activation (focusing)
654 Foot can focus the window when the notification is
655 'activated'. It can also send an event back to the client
656 application, notifying it that the notification has been
657 'activated', This typically happens when the default action is
658 invoked, and/or when the notification is clicked, but exact
659 behavior depends on the notification daemon in use, and how it
660 has been configured.
662 For this to work, foot needs to know when the notification was
663 activated (as opposed to just dismissed), and it needs an XDG
664 activation token.
666 There are two parts to handle this. First, the notification
667 must define an action. For this purpose, foot will add a
668 "default" action to the notification (see the
669 *command-action-argument* option).
671 Second, foot needs to know when the notification is activated,
672 and it needs to get hold of the XDG activation token.
674 Both are expected to be printed on stdout.
676 Foot expects the action name (not label) to be printed on a
677 single line. No prefix, no postfix.
679 Foot expects the activation token to be printed on a single
680 line, prefixed with *xdgtoken=*.
682 Example:
683 default++
684xdgtoken=18179adf579a7a904ce73754964b1ec3
686 The expected format of stdout may change at any time. Please
687 read the changelog when upgrading foot.
689 *Note*: notify-send does not, out of the box, support
690 reporting the XDG activation token in any way. This means
691 window activation will not work by default.
693 Stdout
694 Foot recognizes the following things from the notification
695 helper's stdout:
697 - _id_: integer in base 10, daemon assigned notification ID
698 - *id=*_id_: same as plain _nnn_.
699 - *default*: the 'default' action was triggered
700 - *action=*_default_: same as _default_
701 - *action=*_n_: application custom action _n_ triggered
702 - _n_: integer in base 10, appearing after the ID; application
703 custom action _n_ triggered
704 - *xdgtoken=*_xyz_: XDG activation token.
706 Example #1:
707 17++
708action=default++
709xdgtoken=95ebdfe56e4f47ddb5bba9d7dc3a2c35
711 Foot recognizes this as:
712 - notification has the daemon assigned ID 17
713 - the user triggered the default action
714 - the notification sent an XDG activation token
716 Example #2:
717 17++
720 Foot recognizes this as:
721 - notification has the daemon assigned ID 17
722 - the user triggered the first custom action, "1"
724 Example #3:
725 id=17++
728 Foot recognizes this as:
729 - notification has the daemon assigned ID 17
730 - the user triggered the first custom action, "1"
732 Default: _notify-send++
733 --wait++
734 --app-name ${app-id}++
735 --icon ${app-id}++
736 --category ${category}++
737 --urgency ${urgency}++
738 --expire-time ${expire-time}++
739 --hint STRING:image-path:${icon}++
740 --hint BOOLEAN:suppress-sound:${muted}++
741 --hint STRING:sound-name:${sound-name}++
742 --replace-id ${replace-id}++
743 ${action-argument}++
744 --print-id++
745 -- ${title} ${body}_.
747 Alternative: **fyi** example configuration: _fyi++
748 --wait++
749 --app-name ${app-id}++
750 --icon ${app-id}++
751 --category ${category}++
752 --urgency ${urgency}++
753 --expire-time ${expire-time}++
754 --hint string:image-path:${icon}++
755 --hint boolean:suppress-sound:${muted}++
756 --hint string:sound-name:${sound-name}++
757 --replaces ${replace-id}++
758 ${action-argument}++
759 --print-token++
760 -- ${title} ${body}_.
763*command-action-argument*
764 String to use with *command* to enable passing action/button names
765 to the notification helper.
767 Foot will always configure a "default" action that can be used to
768 "activate" the notification, which in turn can cause the foot
769 window to be focused, or an escape to be sent to the terminal
770 application (depending on how the application generated the
771 notification).
773 Furthermore, the OSC-99 notifications protocol allows applications
774 to define their own actions. Foot uses a combination of the
775 *command* option, and the *command-action-argument* option to pass
776 the names of the actions to the notification helper.
778 This option has the following template arguments:
780 - _${action-name}_: the name of the action; *default* for the
781 default action configured by foot, and _n_, where _n_ is an
782 integer >= 1, for application defined actions.
783 - _${action-label}_: *Activate* for the default action, and a
784 free-form string for application defined actions.
786 For each notification action (remember, there will always be at
787 least one), *command-action-argument* will be expanded with the
788 action's name and label.
790 Then, _${action-argument}_ is expanded in *command* to the full list
791 of actions.
793 If *command-action-argument* is set to the empty string, no
794 actions will be passed to *command*. That is, _${action-argument}_
795 will be replaced with the empty string.
797 Example:
799 *command-action-argument=--action ${action-name}=${action-label}*++
800*command=notify-send ${action-argument} ...*
802 Assume the application defined two custom actions: *OK* and
803 *Cancel*.
805 Given the above, foot will execute:
807 notify-send++
808 --action default='Click to activate'++
809 --action 1=OK++
810 --action 2=Cancel++
811 ...
813 Default: _--action ${action-name}=${action-label}_
815*close*
816 Command to execute to close an existing notification.
818 _${id}_ is expanded to the ID of the notification that should be
819 closed. For example:
821 fyi --close ${id}
823 Closing a notification is only supported by the Kitty Desktop
824 Notification protocol, OSC-99.
826 If set to the empty string (the default), foot will instead try to
827 close the notification by sending SIGINT to the notification
828 helper process. For example, *notify-send --wait* (libnotify >=
829 0.8.0) responds to SIGINT by closing the notification.
831 Default: _not set_
833*inhibit-when-focused*
834 Boolean. If enabled, foot will not display notifications if the
835 terminal window has keyboard focus.
837 Default: _yes_
839# SECTION: scrollback
841*lines*
842 Number of scrollback lines. The maximum number of allocated lines
843 will be this value plus the number of visible lines, rounded up to
844 the nearest power of 2. Default: _1000_.
846*multiplier*
847 Amount to multiply mouse scrolling with. It is a decimal number,
848 i.e. fractions are allowed. Default: _3.0_.
850*indicator-position*
851 Configures the style of the scrollback position indicator. One of
852 *none*, *fixed* or *relative*. *none* disables the indicator
853 completely. *fixed* always renders the indicator near the top of
854 the window, and *relative* renders the indicator at the position
855 corresponding to the current scrollback position. Default:
856 _relative_.
858*indicator-format*
859 Which format to use when displaying the scrollback position
860 indicator. Either _percentage_, _line_, or a custom fixed
861 string. This option is ignored if
862 *indicator-position=none*. Default: _empty string_.
864# SECTION: url
866Note that you can also add custom regular expressions, see the 'regex'
867section.
869*launch*
870 Command to execute when opening URLs. _${url}_ will be replaced
871 with the actual URL. Default: _xdg-open ${url}_.
873*osc8-underline*
874 When to underline OSC-8 URLs. Possible values are *url-mode* and
875 *always*.
877 When set to *url-mode*, OSC-8 URLs are only highlighted in URL
878 mode, just like auto-detected URLs.
880 When set to *always*, OSC-8 URLs are always highlighted,
881 regardless of their other attributes (bold, italic etc). Note that
882 this does _not_ make them clickable.
884 Default: _url-mode_
886*style*
887 The underline style to use when rendering URL underlines. This
888 applies to both OSC-8 underlines when *osc8-underline=always*, and
889 all detected URLs in URL mode. One of *none*, *single*, *double*,
890 *curly*, *dotted* or *dashed*.
892 Default: _dotted_
894*label-letters*
895 String of characters to use when generating key sequences for URL
896 jump labels.
898 If you change this option to include the letter *t*, you should
899 also change the default *[url-bindings].toggle-url-visible* key
900 binding to avoid a clash.
902 Default: _sadfjklewcmpgh_.
904*regex*
905 Regular expression to use when auto-detecting URLs. The format is
906 "POSIX-Extended Regular Expressions". Note that the first marked
907 subexpression is used as the URL. In other words, if you want the
908 whole regex match to be used as an URL, surround all of it with
909 parenthesis: *(regex-pattern)*.
911 Default: _(((https?://|mailto:|ftp://|file:|ssh:|ssh://|git://|tel:|magnet:|ipfs://|ipns://|gemini://|gopher://|news:)|www\.)([0-9a-zA-Z:/?#@!$&\*+,;=.~\_%^'\-]+|\([]\["0-9a-zA-Z:/?#@!$&'\*+,;=.~\_%^\-]+\)|\[[\(\)"0-9a-zA-Z:/?#@!$&'\*+,;=.~\_%^\-]+\]|"[]\[\(\)0-9a-zA-Z:/?#@!$&'\*+,;=.~\_%^\-]+"|'[]\[\(\)0-9a-zA-Z:/?#@!$&\*+,;=.~\_%^\-]+')+([0-9a-zA-Z/#@$&\*+=~\_%^\-]|\([]\["0-9a-zA-Z:/?#@!$&'\*+,;=.~\_%^\-]+\)|\[[\(\)"0-9a-zA-Z:/?#@!$&'\*+,;=.~\_%^\-]+\]|"[]\[\(\)0-9a-zA-Z:/?#@!$&'\*+,;=.~\_%^\-]+"|'[]\[\(\)0-9a-zA-Z:/?#@!$&\*+,;=.~\_%^\-]+'))_
913# SECTION: regex
915Similar to the 'url' mode, but with custom defined regular expressions
916(and launchers).
918To use a custom defined regular expression, you also need to add a key
919binding for it. This is done in the *key-binding* section, see below
920for details. For example, a regex to detect hash digests (e.g. git
921commit hashes) could look like:
923```
924[regex:hashes]
925regex=([a-fA-F0-9]{7,128})
926launch=path-to-script-or-application ${match}
928[key-bindings]
929regex-launch=[hashes] Control+Shift+q
930regex-copy=[hashes] Control+Mod1+Shift+q
931```
933*launch*
934 Command to execute when "launching" a regex match. _${match}_ will
935 be replaced with the actual URL. Default: _not set_.
937*regex*
938 Regular expression to use when matching text. The format is
939 "POSIX-Extended Regular Expressions". Note that the first marked
940 subexpression is used as the match. In other words, if you want
941 the whole regex match to be used, surround all of it with
942 parenthesis: *(regex-pattern)*.
944 Default: _not set_.
947# SECTION: cursor
949This section controls the cursor style and color. Note that
950applications can change these at runtime.
952*style*
953 Configures the default cursor style, and is one of: *block*,
954 *beam*, *underline* or *hollow*. Note that this can be overridden
955 by applications. Default: _block_.
957*unfocused-style*
958 Configures how the cursor is rendered when the terminal window is
959 unfocused. Possible values are:
961 - unchanged: render cursor in exactly the same way as when the
962 window has focus.
963 - hollow: render a block cursor, but hollowed out.
964 - none: do not display any cursor at all.
966*blink*
967 Boolean. Enables blinking cursor. Note that this can be overridden
968 by applications. Related option: *blink-rate*. Default: _no_.
970*blink-rate*
971 The rate at which the cursor blinks, when cursor blinking has been
972 enabled. Expressed in milliseconds between each blink. Default:
973 _500_.
975*beam-thickness*
976 Thickness (width) of the beam styled cursor. The value is in
977 points, and its exact value thus depends on the monitor's DPI. To
978 instead specify a thickness in pixels, use the *px* suffix:
979 e.g. *beam-thickness=2px*. Default: _1.5_
981*underline-thickness*
982 Thickness (height) of the underline styled cursor. The value is in
983 points, and its exact value thus depends on the monitor's DPI.
985 To instead specify a thickness in pixels, use the *px* suffix:
986 e.g. *underline-thickness=2px*.
988 Note that if left unset, the cursor's thickness will scale with
989 the font size, while if set, the size is fixed.
991 Default: _font underline thickness_.
993# SECTION: mouse
995*hide-when-typing*
996 Boolean. When enabled, the mouse cursor is hidden while
997 typing. Default: _no_.
999*alternate-scroll-mode*
1000 Boolean. This option controls the initial value for the _alternate
1001 scroll mode_. When this mode is enabled, mouse scroll events are
1002 translated to _up_/_down_ key events when displaying the alternate
1003 screen.
1005 This lets you scroll with the mouse in e.g. pagers (like _less_)
1006 without enabling native mouse support in them.
1008 Alternate scrolling is *not* used if the application enables
1009 native mouse support.
1011 This option can be modified by applications at run-time using the
1012 escape sequences *CSI ? 1007 h* (enable) and *CSI ? 1007 l*
1013 (disable).
1015 Default: _yes_.
1017# SECTION: touch
1019*long-press-delay*
1020 Number of milliseconds to distinguish between a short press and
1021 a long press on the touchscreen.
1023 Default: _400_.
1025# SECTION: colors-dark, colors-light
1027These two sections controls the 16 ANSI colors, the default foreground
1028and background colors, and the extended 256 color palette. Note that
1029applications can change these at runtime.
1031The colors are in RRGGBB format (i.e. plain old 6-digit hex values,
1032without prefix). That is, they do *not* have an alpha component. You
1033can configure the background transparency with the _alpha_ option.
1035*colors-dark* is intended to define a dark color theme, and
1036*colors-light* is intended to define a light color theme. You can
1037switch between them using the *color-theme-switch-dark*,
1038*color-theme-switch-light* and *color-theme-toggle* key bindings, or
1039by sending SIGUSR1/SIGUSR2 to the foot process.
1041The default theme used is *colors-dark*, unless
1042*initial-color-theme=light* has been set.
1044*cursor*
1045 Two space separated RRGGBB values (i.e. plain old 6-digit hex
1046 values, without prefix) specifying the foreground (text) and
1047 background (cursor) colors for the cursor.
1049 Example: *ff0000 00ff00* (green cursor, red text)
1051 Default: current foreground and background colors, inversed.
1053*foreground*
1054 Default foreground color. This is the color used when no ANSI
1055 color is being used. Default: _839496_.
1057*background*
1058 Default background color. This is the color used when no ANSI
1059 color is being used. Default: _002b36_.
1061*regular0*, *regular1* *..* *regular7*
1062 The eight basic ANSI colors (Black, Red, Green, Yellow, Blue,
1063 Magenta, Cyan, White). Default: _242424_, _f62b5a_, _47b413_,
1064 _e3c401_, _24acd4_, _f2affd_, _13c299_, _e6e6e6_ (starlight
1065 theme, V4).
1067*bright0*, *bright1* *..* *bright7*
1068 The eight bright ANSI colors (Black, Red, Green, Yellow, Blue,
1069 Magenta, Cyan, White). Default: _616161_, _ff4d51_, _35d450_,
1070 _e9e836_, _5dc5f8_, _feabf2_, _24dfc4_, _ffffff_ (starlight
1071 theme, V4).
1073*dim0*, *dim1* *..* *dim7*
1074 Custom colors to use with dimmed colors. Dimmed colors do not have
1075 an entry in the color palette. Applications emit them by combining
1076 a color value, and a "dim" attribute.
1078 By default, foot implements this by blending the current color
1079 with black or white, depending on what the *dim-blend-towards*
1080 option is set to . This is a generic approach that applies to both
1081 colors from the 256-color palette, as well as 24-bit RGB colors.
1083 You can change this behavior by setting the *dimN* options. When
1084 set, foot will match the current color against the color palette,
1085 and if it matches one of the *regularN* colors, the corresponding
1086 *dimN* color will be used.
1088 If instead the current color matches one of the *brightN* colors,
1089 the corresponding *regularN* color will be used.
1091 If the current color does not match any known color, it is dimmed
1092 by blending with black (i.e. the same behavior as if the *dimN*
1093 options are unconfigured). 24-bit RGB colors will typically fall
1094 into this category.
1096 Note that applications can change the *regularN* and *brightN*
1097 colors at runtime. However, they have no way of changing the
1098 *dimN* colors. If an application has changed the *regularN*
1099 colors, foot will still use the corresponding *dimN* color, as
1100 configured in foot.ini.
1102 Default: _not set_.
1104*0* *..* *255*
1105 Arbitrary colors in the 256-color palette. Default: for *0* *..*
1106 *15*, see regular and bright defaults above; see
1107 https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit for an
1108 explanation of the remainder.
1110*sixel0* *..* *sixel15*
1111 The default sixel color palette. Default: _000000_, _3333cc_,
1112 _cc2121_, _33cc33_, _cc33cc_, _33cccc_, _cccc33_, _878787_,
1113 _424242_, _545499_, _994242_, _549954_, _995499_, _549999_,
1114 _999954_, _cccccc_.
1116*alpha*
1117 Background translucency. A value in the range 0.0-1.0, where 0.0
1118 means completely transparent, and 1.0 is opaque. Default: _1.0_.
1120*alpha-mode*
1121 Specifies when *alpha* is applied. One of *default*, *matching* or
1122 *all*.
1124 *default* applies *alpha* to cells with the default background
1125 color, excluding cells with the same RGB value as the default
1126 background color.
1128 *matching* is the same as *default*, but also applies *alpha* to
1129 cells with the same RGB value as the default background color.
1131 *all* applies *alpha* to all cells, regardless of background color.
1133 Default: _default_
1135*blur*
1136 Boolean. When enabled, foot will blur the background (main window
1137 only, not CSDs etc), when it is transparent. This feature requires
1138 the compositor to implement the _ext-background-effect-v1_
1139 protocol (and specifically, the _blur_ effect).
1141 Default: _no_
1143*dim-blend-towards*
1144 Which color to blend towards when "auto" dimming a color (see
1145 *dim0*..*dim7* above). One of *black* or *white*. Blending towards
1146 black makes the text darker, while blending towards white makes it
1147 whiter (but still dimmer than normal text).
1149 Default: _black_ (*colors-dark*), _white_ (*colors-light*)
1151*selection-foreground*, *selection-background*
1152 Foreground (text) and background color to use in selected
1153 text. Default: _inverse foreground/background_.
1155*jump-labels*
1156 Two color values specifying the foreground (text) and background
1157 colors to use when rendering jump labels in URL mode. Default:
1158 _regular0 regular3_.
1160*scrollback-indicator*
1161 Two color values specifying the foreground (text) and background
1162 (indicator itself) colors for the scrollback indicator. Default:
1163 _regular0 bright4_.
1165*search-box-no-match*
1166 Two color values specifying the foreground (text) and background
1167 colors for the scrollback search box, when there are no
1168 matches. Default: _regular0 regular1_.
1170*search-box-match*
1171 Two color values specifying the foreground (text) and background
1172 colors for the scrollback search box, when the search box is
1173 either empty, or there are matches. Default: _regular0 regular3_.
1175*urls*
1176 Color to use for the underline used to highlight URLs in URL
1177 mode. Default: _regular3_.
1179*flash*
1180 Color to use for the terminal window flash. Default: _7f7f00_.
1182*flash-alpha*
1183 Flash translucency. A value in the range 0.0-1.0, where 0.0 means
1184 completely transparent, and 1.0 is opaque. Default: _0.5_.
1186# SECTION: csd
1188This section controls the look of the _CSDs_ (Client Side
1189Decorations). Note that the default is to *not* use CSDs, but instead
1190to use _SSDs_ (Server Side Decorations) when the compositor supports
1191it.
1193Note that unlike the colors defined in the _colors_ section, the color
1194values here are in AARRGGBB (i.e. plain old 8-digit hex values)
1195format. I.e. they contain an alpha component - 00 means completely
1196transparent, and ff fully opaque.
1198Examples:
1200- ffffffff: white, fully opaque
1201- ff000000: black, fully opaque
1202- 7fffffff: white, semi-transparent
1203- ff00ff00: green, fully opaque
1205*preferred*
1206 Which type of window decorations to prefer: *client* (CSD),
1207 *server* (SSD) or *none*.
1209 Note that this is only a hint to the compositor. Depending on
1210 compositor support, and how it has been configured, it may
1211 instruct foot to use CSDs even though this option has been set to
1212 *server*, or render SSDs despite *client* or *none* being set.
1214 Default: _server_.
1216*size*
1217 Height, in pixels (subject to output scaling), of the
1218 titlebar. Setting it to 0 will hide the titlebar, while still
1219 showing the border (if *border-width* is set to a non-zero
1220 value). Default: _26_.
1222*color*
1223 Titlebar color. Default: use the default _foreground_ color.
1225*font*
1226 Font to use for the title bar. This is a list of fonts, similar to
1227 the main *font* option. Note that the font will be sized using the
1228 title bar size. That is, all *:size* and *:pixelsize* attributes
1229 will be ignored. Default: _primary font_.
1231*hide-when-maximized*
1232 Boolean. When enabled, the CSD titlebar is hidden when the window
1233 is maximized. To completely disable the titlebar, set *size* to 0
1234 instead. Default: _no_.
1236*double-click-to-maximize*
1237 Boolean. When enabled, double-clicking the CSD titlebar will
1238 (un)maximize the window. Default: _yes_.
1240*border-width*
1241 Width of the border, in pixels (subject to output scaling). Note
1242 that the border encompasses the entire window, including the title
1243 bar. Default: _0_.
1245*border-color*
1246 Color of border. By default, the title bar color is used. If the
1247 title bar color has not been set, the default foreground color
1248 (from the color scheme) is used. Default: _titlebar color_.
1250*button-width*
1251 Width, in pixels (subject to output scaling), of the
1252 minimize/maximize/close buttons. Default: _26_.
1254*button-color*
1255 Foreground color on the minimize/maximize/close buttons and the
1256 titlebar text. Default: use the default _background_ color.
1258*button-minimize-color*
1259 Minimize button's background color. Default: use the default
1260 _regular4_ color (blue).
1262*button-maximize-color*
1263 Maximize button's background color. Default: use the default
1264 _regular2_ color (green).
1266*button-close-color*
1267 Close button's background color. Default: use the default
1268 _regular1_ color (red).
1270# SECTION: key-bindings
1272This section lets you override the default key bindings.
1274The general format is _action=combo1...comboN_. That is, each action
1275may have one or more key combinations, space separated. Each
1276combination is in the form _mod1+mod2+key_. The names of the modifiers
1277and the key *must* be valid XKB key names.
1279Note that if *Shift* is one of the modifiers, the _key_ *must not* be
1280in upper case. For example, *Control+Shift+V* will never trigger, but
1281*Control+Shift+v* will.
1283The default key bindings all use "real" modifiers (*Mod1*, *Mod4*
1284etc), but "virtual" modifiers (*Alt*, *Super* etc) are allowed.
1286*xkbcli interactive-wayland* can be useful for finding keysym names.
1288When matching key presses to key bindings, foot uses a couple of
1289different approaches.
1291As an example, let's say you press ctrl+shift+c (assume plain us ASCII
1292layout). XKB will tell foot *Control+C* was pressed. Note the lack of
1293the shift modifier, and the upper case 'C'. Internally, this is called
1294the "translated" form.
1296The "untranslated" form (*Control+Shift+c*) is derived from the
1297translated form, and is what foot tries to match first.
1299If no "untranslated" key bindings can be found, foot proceeds to
1300checking the "translated" variant.
1302This means you can use either form in your foot configuration, and
1303that *Control+Shift+c* (and similar) has higher priority than
1304*Control+C*. Also note that while foot normally detects when the same
1305combination is assigned to multiple actions, it will not detect
1306*Control+C* vs. *Control+Shift+c* collisions. Call it a known bug...
1308Finally, foot tries to match the raw key code. Here, the primary
1309layout is queried for all key codes that generate a particular XKB
1310symbol, and the pressed key's code is matched against this. For
1311example, if you use the layouts *"us,de(neo)"*, the 'r' key generates
1312the symbol 'c' in the neo layout. I.e. to get a 'c', you press
1313'r'. The match logic described above will only match 'c' key bindings
1314(e.g. *Control+Shift+c*). The raw mode however, will match 'r' key
1315bindings (e.g. *Control+Shift+r*). This is useful for non-latin
1316layouts, where you would otherwise have to customize all key bindings.
1318A key combination can only be mapped to *one* action. Let's say you
1319want to bind *Control+Shift+R* to *fullscreen*. Since this is the
1320default shortcut for *search-start*, you first need to unmap the
1321default binding. This can be done by setting _action=none_;
1322e.g. *search-start=none*.
1324*noop*
1325 All key combinations listed here will not be sent to the
1326 application. Default: _none_.
1328*scrollback-up-page*
1329 Scrolls up/back one page in history. Default: _Shift+Page\_Up
1330 Shift+KP\_Page\_Up_.
1332*scrollback-up-half-page*
1333 Scrolls up/back half of a page in history. Default: _none_.
1335*scrollback-up-line*
1336 Scrolls up/back a single line in history. Default: _none_.
1338*scrollback-down-page*
1339 Scroll down/forward one page in history. Default:
1340 _Shift+Page\_Down Shift+KP\_Page\_Down_.
1342*scrollback-down-half-page*
1343 Scroll down/forward half of a page in history. Default: _none_.
1345*scrollback-down-line*
1346 Scroll down/forward a single line in history. Default: _none_.
1348*scrollback-home*
1349 Scroll to the beginning of the scrollback. Default: _none_.
1351*scrollback-end*
1352 Scroll to the end (bottom) of the scrollback. Default: _none_.
1354*clipboard-copy*
1355 Copies the current selection into the _clipboard_. Default: _Control+Shift+c_
1356 _XF86Copy_.
1358*clipboard-paste*
1359 Pastes from the _clipboard_. Default: _Control+Shift+v_ _XF86Paste_.
1361*primary-paste*
1362 Pastes from the _primary selection_. Default: _Shift+Insert_ (also
1363 defined in *mouse-bindings*).
1365*search-start*
1366 Starts a scrollback/history search. Default: _Control+Shift+r_.
1368*font-increase*
1369 Increases the font size by 0.5pt. Default: _Control+plus
1370 Control+equal Control+KP\_Add_ (also defined in *mouse-bindings*).
1372*font-decrease*
1373 Decreases the font size by 0.5pt. Default: _Control+minus
1374 Control+KP\_Subtract_ (also defined in *mouse-bindings*).
1376*font-reset*
1377 Resets the font size to the default. Default: _Control+0 Control+KP\_0_.
1379*spawn-terminal*
1380 Spawns a new terminal. If the shell has been configured to emit
1381 the OSC 7 escape sequence, the new terminal will start in the
1382 current working directory. Default: _Control+Shift+n_.
1384*minimize*
1385 Minimizes the window. Default: _none_.
1387*maximize*
1388 Toggle the maximized state. Default: _none_.
1390*fullscreen*
1391 Toggles the fullscreen state. Default: _none_.
1393*pipe-visible*, *pipe-scrollback*, *pipe-selected*, *pipe-command-output*
1394 Pipes the currently visible text, the entire scrollback, the
1395 currently selected text, or the last command's output to an
1396 external tool. The syntax for this option is a bit special; the
1397 first part of the value is the command to execute enclosed in
1398 "[]", followed by the binding(s).
1400 You can configure multiple pipes as long as the command strings
1401 are different and the key bindings are unique.
1403 Note that the command is *not* automatically run inside a shell;
1404 use *sh -c "command line"* if you need that.
1406 Example #1:
1407 # Extract currently visible URLs, let user choose one (via
1408 fuzzel), then launch firefox with the selected URL++
1409*pipe-visible=[sh -c "xurls | uniq | tac | fuzzel | xargs -r firefox"] Control+Print*
1411 Example #2:
1412 # Open scrollback contents in Emacs running in a new foot instance++
1413*pipe-scrollback=[sh -c "f=$(mktemp) && cat - > $f && foot emacsclient -t $f; rm $f"] Control+Shift+Print*
1415 Default: _none_
1417*show-urls-launch*
1418 Enter URL mode, where all currently visible URLs are tagged with a
1419 jump label with a key sequence that will open the URL (and exit
1420 URL mode). Default: _Control+Shift+o_.
1422*show-urls-persistent*
1423 Similar to *show-urls-launch*, but does not automatically exit URL
1424 mode after activating an URL. Default: _none_.
1426*show-urls-copy*
1427 Enter URL mode, where all currently visible URLs are tagged with a
1428 jump label with a key sequence that will place the URL in the
1429 clipboard. If the hint is completed with an uppercase character,
1430 the match will also be pasted. Default: _none_.
1432*regex-launch*
1433 Enter regex mode. This works exactly the same as URL mode; all
1434 regex matches are tagged with a jump label with a key sequence
1435 that will "launch" to match (and exit regex mode).
1437 The name of the regex section must be specified in the key
1438 binding:
1440 ```
1441 [regex:hashes]
1442 regex=([a-fA-F0-9]{7,128})
1443 launch=path-to-script-or-application ${match}
1445 [key-bindings]
1446 regex-launch=[hashes] Control+Shift+q
1447 regex-copy=[hashes] Control+Mod1+Shift+q
1448 ```
1450 Default: _none_.
1452*regex-copy*
1453 Same as *regex-launch*, but the match is placed in the clipboard,
1454 instead of "launched", upon activation. If the hint is completed
1455 with an uppercase character, the match will also be pasted.
1456 Default: _none_.
1458*prompt-prev*
1459 Jump to the previous, currently not visible, prompt (requires
1460 shell integration, see *foot*(1)). Default: _Control+Shift+z_.
1462*prompt-next*
1463 Jump to the next prompt (requires shell integration, see
1464 *foot*(1)). Default: _Control+Shift+x_.
1466*unicode-input*
1467 Input a Unicode character by typing its codepoint in hexadecimal,
1468 followed by *Enter* or *Space*.
1470 For example, to input the character _ö_ (LATIN SMALL LETTER O WITH
1471 DIAERESIS, Unicode codepoint 0xf6), you would first activate this
1472 key binding, then type: *f*, *6*, *Enter*.
1474 Another example: to input 😍 (SMILING FACE WITH HEART-SHAPED EYES,
1475 Unicode codepoint 0x1f60d), activate this key binding, then type:
1476 *1*, *f*, *6*, *0*, *d*, *Enter*.
1478 Recognized key bindings in Unicode input mode:
1480 - Enter, Space: commit the Unicode character, then exit this mode.
1481 - Escape, q, Ctrl+c, Ctrl+d, Ctrl+g: abort input, then exit this mode.
1482 - 0-9, a-f: append next digit to the Unicode's codepoint.
1483 - Backspace: undo the last digit.
1485 Note that there is no visual feedback while in this mode. This is
1486 by design; foot's Unicode input mode is considered to be a
1487 fallback. The preferred way of entering Unicode characters, emojis
1488 etc is by using an IME.
1490 Default: _Control+Shift+u_.
1492*color-theme-switch-dark*, *color-theme-switch-light*, *color-theme-toggle*
1493 Switch between the dark color theme (defined in the *colors-dark*
1494 section), and the light color theme (defined in the *colors-light*
1495 section).
1497 *color-theme-switch-dark* applies the dark color theme regardless
1498 of which color theme is currently active.
1500 *color-theme-switch-light* applies the light color theme
1501 regardless of which color theme is currently active.
1503 *color-theme-toggle* toggles between the primary and alternative
1504 color themes.
1506 Note: you can also send SIGUSR1/SIGUSR2 to the foot process to
1507 change the theme (see *foot*(1) for details.)
1509 Default: _none_
1511*quit*
1512 Quit foot. Default: _none_.
1514# SECTION: search-bindings
1516This section lets you override the default key bindings used in
1517scrollback search mode. The syntax is exactly the same as the regular
1518**key-bindings**.
1520*cancel*
1521 Aborts the search. The viewport is restored and the _primary
1522 selection_ is **not** updated. Default: _Control+g Control+c
1523 Escape_.
1525*commit*
1526 Exit search mode and copy current selection into the _primary
1527 selection_. Viewport is **not** restored. To copy the selection to
1528 the regular _clipboard_, use *Control+Shift+c*. Default: _Return
1529 KP_Enter_.
1531*find-prev*
1532 Search **backwards** in the scrollback history for the next
1533 match. Default: _Control+r_.
1535*find-next*
1536 Searches **forwards** in the scrollback history for the next
1537 match. Default: _Control+s_.
1539*cursor-left*
1540 Moves the cursor in the search box one **character** to the
1541 left. Default: _Left Control+b_.
1543*cursor-left-word*
1544 Moves the cursor in the search box one **word** to the
1545 left. Default: _Control+Left Mod1+b_.
1547*cursor-right*
1548 Moves the cursor in the search box one **character** to the
1549 right. Default: _Right Control+f_.
1551*cursor-right-word*
1552 Moves the cursor in the search box one **word** to the
1553 right. Default: _Control+Right Mod1+f_.
1555*cursor-home*
1556 Moves the cursor in the search box to the beginning of the
1557 input. Default: _Home Control+a_.
1559*cursor-end*
1560 Moves the cursor in the search box to the end of the
1561 input. Default: _End Control+e_.
1563*delete-prev*
1564 Deletes the **character before** the cursor. Default: _BackSpace_.
1566*delete-prev-word*
1567 Deletes the **word before** the cursor. Default: _Mod1+BackSpace
1568 Control+BackSpace_.
1570*delete-next*
1571 Deletes the **character after** the cursor. Default: _Delete_.
1573*delete-next-word*
1574 Deletes the **word after** the cursor. Default: _Mod1+d
1575 Control+Delete_.
1577*delete-to-start*
1578 Deletes search input before the cursor. Default: _Ctrl+u_.
1580*delete-to-end*
1581 Deletes search input after the cursor. Default: _Ctrl+k_.
1583*extend-char*
1584 Extend current selection to the right, by one character. Default:
1585 _Shift+Right_.
1587*extend-to-word-boundary*
1588 Extend current selection to the right, to the next word
1589 boundary. Default: _Control+w Control+Shift+Right_.
1591*extend-to-next-whitespace*
1592 Extend the current selection to the right, to the next
1593 whitespace. Default: _Control+Shift+w_.
1595*extend-line-down*
1596 Extend current selection down one line. Default: _Shift+Down_.
1598*extend-backward-char*
1599 Extend current selection to the left, by one character. Default:
1600 _Shift+Left_.
1602*extend-backward-to-word-boundary*
1603 Extend current selection to the left, to the next word
1604 boundary. Default: _Control+Shift+Left_.
1606*extend-backward-to-next-whitespace*
1607 Extend the current selection to the left, to the next
1608 whitespace. Default: _none_.
1610*extend-line-up*
1611 Extend current selection up one line. Default: _Shift+Up_.
1613*clipboard-paste*
1614 Paste from the _clipboard_ into the search buffer. Default:
1615 _Control+v Control+y Control+Shift+v XF86Paste_.
1617*primary-paste*
1618 Paste from the _primary selection_ into the search
1619 buffer. Default: _Shift+Insert_.
1621*unicode-input*
1622 Unicode input mode. See _key-bindings.unicode-input_ for
1623 details. Default: _none_.
1625*scrollback-up-page*
1626 Scrolls up/back one page in history. Default: _Shift+Page\_Up
1627 Shift+KP\_Page\_Up_.
1629*scrollback-up-half-page*
1630 Scrolls up/back half of a page in history. Default: _none_.
1632*scrollback-up-line*
1633 Scrolls up/back a single line in history. Default: _none_.
1635*scrollback-down-page*
1636 Scroll down/forward one page in history. Default:
1637 _Shift+Page\_Down Shift+KP\_Page\_Down_.
1639*scrollback-down-half-page*
1640 Scroll down/forward half of a page in history. Default: _none_.
1642*scrollback-down-line*
1643 Scroll down/forward a single line in history. Default: _none_.
1645*scrollback-home*
1646 Scroll to the beginning of the scrollback. Default: _none_.
1648*scrollback-end*
1649 Scroll to the end (bottom) of the scrollback. Default: _none_.
1651# SECTION: url-bindings
1653This section lets you override the default key bindings used in URL
1654mode. The syntax is exactly the same as the regular **key-bindings**.
1656Be careful; do not use single-letter keys that are also used in
1657*[url].label-letters*, as doing so will make some URLs inaccessible.
1659*cancel*
1660 Exits URL mode without opening a URL. Default: _Control+g
1661 Control+c Control+d Escape_.
1663*toggle-url-visible*
1664 By default, the jump label only shows the key sequence required to
1665 activate it. This is fine as long as the URL is visible in the
1666 original text.
1668 But with e.g. OSC-8 URLs (the terminal version of HTML anchors,
1669 i.e. "links"), the text on the screen can be something completely
1670 different than the URL.
1672 This action toggles between showing and hiding the URL on the jump
1673 label.
1675 Default: _t_.
1677# SECTION: text-bindings
1679This section lets you remap key combinations to custom escape
1680sequences.
1682The format is _text=combo1...comboN_. That is, the string to emit may
1683have one or more key combinations, space separated. Each combination
1684is in the form _mod1+mod2+key_. The names of the modifiers and the key
1685*must* be valid XKB key names.
1687The text string specifies the characters, or bytes, to emit when the
1688associated key combination(s) are pressed. There are two ways to
1689specify a character:
1691- Normal, printable characters are written as-is: *abcdef*.
1692- Bytes (e.g. ESC) are written as two-digit hexadecimal numbers, with
1693 a *\\x* prefix: *\\x1b*.
1695Example: you would like to remap _Super+k_ to the _Up_ key.
1697The escape sequence for the Up key is _ESC [ A_ (without the
1698spaces). Thus, we need to specify this in foot.ini (*Mod4* is the XKB
1699name for the Super/logo key):
1701*\\x1b[A = Mod4+k*
1703Another example: to remap _Super+c_ to _Control+c_:
1705*\\x03 = Mod4+c*
1707# SECTION: mouse-bindings
1709This section lets you override the default mouse bindings.
1711The general format is _action=combo1...comboN_. That is, each action
1712may have one or more key combinations, space separated. Each
1713combination is in the form _mod1+mod2+BTN\_<name>[-COUNT]_. The names
1714of the modifiers *must* be valid XKB key names, and the button name
1715*must* be a valid libinput name. You can find the button names using
1716*libinput debug-events*.
1718The trailing *COUNT* (number of times the button has to be clicked) is
1719optional and specifies the click count required to trigger the
1720binding. The default if *COUNT* is omitted is _1_.
1722To map wheel events (i.e. scrolling), use the button names
1723*BTN_WHEEL_BACK* (up) and *BTN_WHEEL_FORWARD* (down). Note that these
1724events never generate a *COUNT* larger than 1. That is,
1725*BTN_WHEEL_BACK+2*, for example, will never trigger.
1727Foot also recognizes tiltable wheels; to map these, use
1728*BTN_WHEEL_LEFT* and *BTN_WHEEL_RIGHT*.
1730A modifier+button combination can only be mapped to *one* action. Let's
1731say you want to bind *BTN\_MIDDLE* to *fullscreen*. Since
1732*BTN\_MIDDLE* is the default binding for *primary-paste*, you first
1733need to unmap the default binding. This can be done by setting
1734_action=none_; e.g. *primary-paste=none*.
1736*selection-override-modifiers*
1737 The modifiers set in this set (which may be set to any combination
1738 of modifiers, e.g. _mod1+mod2+mod3_, as well as _none_) are used
1739 to enable selecting text with the mouse irrespective of whether a
1740 client application currently has the mouse grabbed.
1741 Any combination of these modifiers cannot be used in mouse bindings.
1742 Because the order of bindings is significant, it is best to set
1743 this prior to any other mouse bindings that might use modifiers in
1744 the default set.
1745 Default: _Shift_
1747The actions to which mouse combos can be bound are listed below. All
1748actions listed under *key-bindings* can be used here as well.
1750*scrollback-up-mouse*
1751 Normal screen: scrolls up the contents.
1753 Alt screen: send fake _KeyUP_ events to the client application, if
1754 alternate scroll mode is enabled.
1756 Default: _BTN\_WHEEL\_BACK_
1758*scrollback-down-mouse*
1759 Normal screen: scrolls down the contents.
1761 Alt screen: send fake _KeyDOWN_ events to the client application, if
1762 alternate scroll mode is enabled.
1764 Default: _BTN\_WHEEL\_FORWARD_
1766*select-begin*
1767 Begin an interactive selection. The selection is finalized, and
1768 copied to the _primary selection_, when the button is
1769 released. Default: _BTN\_LEFT_.
1771*select-begin-block*
1772 Begin an interactive block selection. The selection is finalized,
1773 and copied to the _primary selection_, when the button is
1774 released. Default: _Control+BTN\_LEFT_.
1776*select-word*
1777 Begin an interactive word-wise selection, where words are
1778 separated by whitespace and all characters defined by the
1779 *word-delimiters* option. The selection is finalized, and copied
1780 to the _primary selection_, when the button is released. Default:
1781 _BTN\_LEFT-2_.
1783*select-word-whitespace*
1784 Same as *select-word*, but the characters in the *word-delimiters*
1785 option are ignored. I.e only whitespace characters act as
1786 delimiters. The selection is finalized, and copied to the _primary
1787 selection_, when the button is released. Default:
1788 _Control+BTN\_LEFT-2_.
1790*select-quote*
1791 Begin an interactive "quote" selection. This is similar to
1792 *select-word*, except an entire quote is selected (that is,
1793 everything inside the quote, excluding the quote
1794 characters). Recognized quote characters are: *"* and *'*.
1796 If a complete quote cannot be found on the current logical row
1797 (only one quote character, or none are found), the entire row is
1798 selected.
1800 The selection is finalized, and copied to the _primary selection_,
1801 when the button is released.
1803 After the initial selection has been made, it behaves like a
1804 normal word, or row selection, depending on whether a quote was
1805 found or not. This affects what happens when, for example,
1806 extending the selection.
1808 Notes:
1809 - Escaped quote characters are not supported (*"foo \\"bar"* will
1810 match *'foo \\'*, not *'foo "bar'*).
1811 - Foot does not try to handle mismatched quote characters; they
1812 will simply not match.
1813 - Nested quotes (using different quote characters) are supported.
1815 Default: _BTN\_LEFT-3_.
1817*select-row*
1818 Begin an interactive row-wise selection. The selection is
1819 finalized, and copied to the _primary selection_, when the button
1820 is released. Default: _BTN\_LEFT-4_.
1822*select-extend*
1823 Interactively extend an existing selection, using the original
1824 selection mode (normal, block, word-wise or row-wise). The
1825 selection is finalized, and copied to the _primary selection_,
1826 when the button is released. Default: _BTN\_RIGHT_.
1828*select-extend-character-wise*
1829 Same as *select-extend*, but forces the selection mode to _normal_
1830 (i.e. character wise). Note that this causes subsequent
1831 *select-extend* operations to be character wise. This action is
1832 ignored for block selections. Default: _Control+BTN\_RIGHT_.
1834*primary-paste*
1835 Pastes from the _primary selection_. Default: _BTN\_MIDDLE_.
1837*font-increase*
1838 Increases the font size by 0.5pt. Default:
1839 _Control+BTN\_WHEEL\_BACK_ (also defined in *key-bindings*).
1841*font-decrease*
1842 Decreases the font size by 0.5pt. Default:
1843 _Control+BTN\_WHEEL\_FORWARD_ (also defined in *key-bindings*).
1846# TWEAK
1848This section is for advanced users and describes configuration options
1849that can be used to tweak foot's low-level behavior.
1851These options are *not* included in the example configuration. You
1852should not change these unless you understand what they do.
1854Note that these options may change, or be removed at any time, without
1855prior notice.
1857When reporting bugs, please mention if, and to what, you have changed
1858any of these options.
1860*scaling-filter*
1861 Overrides the default scaling filter used when down-scaling bitmap
1862 fonts (e.g. emoji fonts). Possible values are *none*, *nearest*,
1863 *bilinear*, *impulse*, *box*, *linear*, *cubic*, *gaussian*,
1864 *lanczos2*, *lanczos3* or *lanczos3-stretched*.
1866 Default: _lanczos3_.
1868*overflowing-glyphs*
1869 Boolean. When enabled, glyphs wider than their cell(s) are allowed
1870 to render into one additional neighbouring cell.
1872 One use case for this are fonts with wide italic characters that
1873 "bend" into the next cell. Without this option, such glyphs will
1874 appear "cut off".
1876 Another use case are fonts with "icon" characters in the Unicode
1877 private usage area, e.g. Nerd Fonts, or Powerline Fonts and legacy
1878 emoji characters like *WHITE FROWNING FACE*.
1880 Note: might impact performance depending on the font used.
1881 Especially small font sizes can cause many overflowing glyphs
1882 because of subpixel rendering.
1884 Default: _yes_.
1886*render-timer*
1887 Enables a frame rendering timer, that prints the time it takes to
1888 render each frame, in microseconds, either on-screen, to stderr,
1889 or both. Valid values are *none*, *osd*, *log* and
1890 *both*. Default: _none_.
1892*box-drawing-base-thickness*
1893 Line thickness to use for *LIGHT* box drawing line characters, in
1894 points. This value is converted to pixels using the monitor's DPI,
1895 and then multiplied with the cell size. The end result is that a
1896 larger font (and thus larger cells) result in thicker
1897 lines. Default: _0.04_.
1899*box-drawing-solid-shades*
1900 Boolean. When enabled, box drawing "shades" (e.g. LIGHT SHADE,
1901 MEDIUM SHADE and DARK SHADE) are rendered as solid blocks using a
1902 darker variant of the current foreground color.
1904 When disabled, they are instead rendered as checker box pattern,
1905 using the current foreground color as is.
1907 Default: _yes_.
1909*delayed-render-lower*, *delayed-render-upper*
1910 These two values control the timeouts (in nanoseconds) that are
1911 used to mitigate screen flicker caused by clients writing large,
1912 non-atomic screen updates.
1914 If a client splits up a screen update over multiple *write*(3)
1915 calls, we may end up rendering an intermediate frame, quickly
1916 followed by another frame with the final screen content. For
1917 example, the client may erase part of the screen (or scroll) in
1918 one write, and then write new content in one or more subsequent
1919 writes. Rendering the frame when the screen has been erased, but
1920 not yet filled with new content will be perceived as screen
1921 flicker.
1923 The *real* solution to this is _Application Synchronized Updates_
1924 (https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/2).
1926 The problem with this is twofold - first, it has not yet been
1927 standardized, and thus there are not many terminal emulators that
1928 implement it (foot *does* implement it), and second, applications
1929 must be patched to use it.
1931 Until this has happened, foot offers an interim workaround; an
1932 attempt to mitigate the screen flicker *without* affecting either
1933 performance or latency.
1935 It is based on the fact that the screen is updated at a fixed
1936 interval (typically 60Hz). For us, this means it does not matter
1937 if we render a new frame at the *beginning* of a frame interval,
1938 or at the *end*. Thus, the goal is to introduce a delay between
1939 receiving client data and rendering the resulting state, but
1940 without causing a frame skip.
1942 While it should be possible to estimate the amount of time left
1943 until the next frame, foot's algorithm is currently not that
1944 advanced, but is based on statistics I guess you could say - the
1945 delay we introduce is so small that the risk of pushing the frame
1946 over to the next frame interval is also very small.
1948 Now, that was a lot of text. But what is it foot actually does?
1950 When receiving client data, it schedules a timer, the
1951 *delayed-render-lower*. If we do not receive any more client data
1952 before the timer has run out, we render the frame. If however, we
1953 do receive more data, the timer is re-scheduled. That is, each
1954 time we receive client data, frame rendering is delayed another
1955 *delayed-render-lower* nanoseconds.
1957 Now, while this works very well with most clients, it would be
1958 possible to construct a malicious client that keeps writing data
1959 at a slow pace. To the user, this would look like foot has frozen
1960 as we never get to render a new frame. To prevent this, an upper
1961 limit is set - *delayed-render-upper*. If this timer runs out, we
1962 render the frame regardless of what the client is doing.
1964 If changing these values, note that the lower timeout *must* be
1965 set lower than the upper timeout, but that this is not verified by
1966 foot. Furthermore, both values must be less than 16ms (that is,
1967 16000000 nanoseconds).
1969 You can disable the feature altogether by setting either value to
1970 0. In this case, frames are rendered "as soon as possible".
1972 Default: lower=_500000_ (0.5ms), upper=_8333333_ (8.3ms - half a
1973 frame interval).
1975*damage-whole-window*
1976 Boolean. When enabled, foot will 'damage' the entire window each
1977 time a frame has been rendered. This forces the compositor to
1978 redraw the entire window. If disabled, foot will only 'damage'
1979 updated rows.
1981 There is normally *no* reason to enable this. However, it has been
1982 seen to workaround an issue with _fractional scaling_ in _Gnome_.
1984 Note that enabling this option is likely to increase CPU and/or
1985 GPU usage (by the compositor, not by foot), and may have a
1986 negative impact on battery life.
1988 Default: _no_.
1990*grapheme-shaping*
1991 Boolean. When enabled, foot will use _utf8proc_ to do grapheme
1992 cluster segmentation while parsing "printed" text. Then, when
1993 rendering, it will use _fcft_ (if compiled with _HarfBuzz_
1994 support) to shape the grapheme clusters.
1996 This is required to render e.g. flag (emoji) sequences, keycap
1997 sequences, modifier sequences, zero-width-joiner (ZWJ) sequences
1998 and emoji tag sequences. It might also improve rendering of
1999 composed characters, depending on font.
2001 - foot must have been compiled with utf8proc support
2002 - fcft must have been compiled with HarfBuzz support
2004 This option can also be set runtime with DECSET/DECRST 2027.
2006 See also: *grapheme-width-method*.
2008 Default: _yes_
2010*grapheme-width-method*
2011 Selects which method to use when calculating the width
2012 (i.e. number of columns) of a grapheme cluster. One of
2013 *wcswidth*, *double-width* and *max*.
2015 *wcswidth* simply adds together the individual width of all
2016 codepoints making up the cluster.
2018 *double-width* does the same, but limits the maximum number of
2019 columns to 2. This is more correct, but may break some
2020 applications since applications typically use *wcswidth*(3)
2021 internally to calculate the width. This results in cursor
2022 de-synchronization issues.
2024 *max* uses the width of the largest codepoint in the cluster.
2026 Default: _double-width_
2028*font-monospace-warn*
2029 Boolean. When enabled, foot will use heuristics to try to verify
2030 the primary font is a monospace font, and warn if it is not.
2032 Disable this if you still want to use the font, even if foot
2033 thinks it is not monospaced.
2035 You may also want to disable it to get slightly faster startup times.
2037 Default: _yes_
2039*max-shm-pool-size-mb*
2040 This option controls the amount of virtual address space used by
2041 the pixmap memory to which the terminal screen content is
2042 rendered.
2044 It does not change how much physical memory foot uses.
2046 Foot uses a memory mapping trick to implement fast rendering of
2047 interactive scrolling (typically, but applies to "slow" scrolling
2048 in general). Example: holding down the 'up' or 'down' arrow key to
2049 scroll in a text editor.
2051 For this to work, it needs a large amount of virtual address
2052 space. Again, note that this is not physical memory.
2054 On a normal x64 based computer, each process has 128TB of virtual
2055 address space, and newer ones have 64PB. This is an insane amount
2056 and most applications do not use anywhere near that amount.
2058 Each foot terminal window can allocate up to 2GB of virtual
2059 address space. With 128TB of address space, that means a maximum
2060 of 65536 windows in server/daemon mode (for 2GB). That should be
2061 enough, yes?
2063 However, the Wayland compositor also needs to allocate the same
2064 amount of virtual address space. Thus, it has a slightly higher
2065 chance of running out of address space since it needs to host
2066 all running Wayland clients in the same way, at the same time.
2068 In the off chance that this becomes a problem for you, you can
2069 reduce the amount used with this option.
2071 Or, for optimal performance, you can increase it to the maximum
2072 allowed value, 2GB (but note that you most likely will not notice
2073 any difference compared to the default value).
2075 Setting it to 0 disables the feature.
2077 Limitations:
2078 - only supported on 64-bit architectures
2079 - only supported on Linux
2081 Default: _512_. Maximum allowed: _2048_ (2GB).
2083*min-stride-alignment*
2084 This option controls the minimum stride alignment, in bytes, when
2085 allocating SHM buffers.
2087 In some circumstances, a compositor can import foot's SHM buffers
2088 directly to the GPU, without copying the buffer to GPU memory
2089 (typically on integrated graphics). Different drivers have
2090 different requirements for this, and one of those requirements is
2091 typically the stride alignment. At the time of writing, AMD GPUs
2092 require 256-byte alignment.
2094 Note that doing a direct import typically disables immediate
2095 buffer release (if the compositor supports that), which means foot
2096 has to double buffer. This adds a performance penalty in foot, but
2097 the overall system performance should still be better.
2099 If you are not using integrated graphics, or if the compositor
2100 does not support GPU direct imports, this option has close to zero
2101 impact. You can save a small amount of memory by setting this to
2102 0.
2104 Ultimately, it is up to the compositor to decide whether to do
2105 immediate buffer releases, or try to optimize GPU imports.
2107 Default: _256_
2109*sixel*
2110 Boolean. When enabled, foot will process sixel images. Default:
2111 _yes_
2113*dim-amount*
2114 Amount by which dimmed text is darkened. Default: _1.5_.
2116*bold-text-in-bright-amount*
2117 Amount by which bold fonts are brightened when
2118 *bold-text-in-bright* is set to *yes* (the *palette-based* variant
2119 is not affected by this option). Default: _1.3_.
2121*surface-bit-depth*
2122 Selects which RGB bit depth to use for image buffers. One of
2123 *auto*, *8-bit*, *10-bit* or *16-bit*.
2125 *auto* chooses bit depth depending on other settings, and
2126 availability.
2128 *8-bit*, uses 8 bits for each color channel, alpha included. This
2129 is the default when *gamma-correct-blending=no*.
2131 *10-bit* uses 10 bits for each RGB channel, and 2 bits for the
2132 alpha channel. Thus, it provides higher precision color channels,
2133 but a lower precision alpha channel.
2135 *16-bit* 16 bits for each color channel, alpha included. If
2136 available, this is the default when *gamma-correct-blending=yes*.
2138 Note that both *10-bit* and *16-bit* are much slower than *8-bit*;
2139 if you want to use gamma-correct blending, and if you prefer speed
2140 (throughput and input latency) over accurate colors, you can set
2141 *surface-bit-depth=8-bit* explicitly.
2143 Default: _auto_
2145*pre-apply-damage*
2146 Boolean. When enabled, foot will attempt to "pre-apply" the damage
2147 from the last frame when foot is forced to double-buffer
2148 (i.e. when the compositor does not release SHM buffers
2149 immediately). All text after this assumes the compositor is not
2150 releasing buffers immediately.
2152 When this option is disabled, each time foot needs to render a
2153 frame, it has to first copy over areas that changed in the last
2154 frame (i.e. all changes between the last two frames). This is
2155 basically a *memcpy*(3), which can be slow if the changed area is
2156 large. It is also done on the main thread, which means foot cannot
2157 do anything else at the same time; no other rendering, no VT
2158 parsing. After the changes have been brought over to the new
2159 frame, foot proceeds with rendering the cells that has changed
2160 between the last frame and the new frame.
2162 When this option is enabled, the changes between the last two frames
2163 are brought over to what will become the next frame before foot
2164 starts rendering the next frame. As soon as the compositor
2165 releases the previous buffer (typically right after foot has
2166 pushed a new frame), foot kicks off a thread that copies over the
2167 changes to the newly released buffer. Since this is done in a
2168 thread, foot can continue processing input at the same
2169 time. Later, when it is time to render a new frame, the changes
2170 have already been transferred, and foot can immediately start with
2171 the actual rendering.
2173 Thus, having this option enabled improves both performance
2174 (copying the last two frames' changes is threaded), and improves
2175 input latency (rendering the next frame no longer has to first bring
2176 over the changes between the last two frames).
2178 Default: _yes_
2180# SEE ALSO
2182*foot*(1), *footclient*(1)
Diagnostics5 git calls · 470 ms
CallStatusSizeTime0470 ms
discover200178 B4 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=4
git.response.bytes=178
git.server.agent=git/2.56.1-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=178
git.pkt.payload.max=35
ls-refs20010 KiB448 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=376
git.response.bytes=10322
git.response.cache=EXPIRED
git.response.duration_ms=448
git.protocol.version=2
git.pkt.frames=108
git.pkt.data=107
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=10322
git.pkt.payload.max=106
git.ls_refs.count=107
git.ls_refs.head=refs/heads/master
fetchcombine:blob:none+tree:2 · deepen 12008.6 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=8830
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=c0d2c3e95d74cb60526ff28aec9f34ee3df545e0
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=8830
git.pkt.payload.max=8730
git.sideband.band1.bytes=8730
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=14
git.pack.bytes=8730
git.fetch.wide.objects=14
git.fetch.wide.extra_bytes=9909
git.fetch.wide.blobs=0
fetchtree:0 · deepen 102009.3 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=9489
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=c0d2c3e95d74cb60526ff28aec9f34ee3df545e0
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=9489
git.pkt.payload.max=9389
git.sideband.band1.bytes=9389
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=10
git.pack.bytes=9389
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=de930681b6073ba5b599a0f956bfbd114762ad5a
git.pack.full=10
Open pack map
fetch20025 KiB · hit19 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=19
git.response.bytes=25316
git.response.cache=HIT
git.response.duration_ms=19
git.fetch.wants=6edecd1ede794e2d7f0c8b7aaf436ec1523755d6
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=25316
git.pkt.payload.max=25289
git.sideband.band1.bytes=25289
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://codeberg.org/dnkl/foot
Ref
refs/heads/master
Commit
c0d2c3e95d74cb60526ff28aec9f34ee3df545e0
cf-ray
a5e31130c8babdc9
Request
fb4ac4ff…
Protocol
v2 · sha1
Agent
git/2.56.1-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format