1foot.ini(5) File Formats Manual foot.ini(5)
2
6 foot.ini - configuration file for foot(1)
7
9 foot uses the standard unix configuration format, with section based
10 key/value pairs. The default section is usually unnamed, i.e. not pre‐
11 fixed with a [section]. However it can also be explicitly named [main],
12 say if it needs to be reopened after any of the other sections.
13 foot will search for a configuration file in the following locations,
15 in this order:
16 • XDG_CONFIG_HOME/foot/foot.ini
18 • ~/.config/foot/foot.ini
19 • XDG_CONFIG_DIRS/foot/foot.ini
20
23 shell
24 Executable to launch. Typically a shell. Default: $SHELL if set,
25 otherwise the user's default shell (as specified in /etc/passwd).
26 You can also pass arguments. For example /bin/bash --norc.
27 login-shell
29 Boolean. If enabled, the shell will be launched as a login shell,
30 by prepending a '-' to argv[0]. Default: no.
31 term
33 Value to set the environment variable TERM to. Default: foot
34 font, font-bold, font-italic, font-bold-italic
36 Comma separated list of fonts to use, in fontconfig format. That
37 is, a font name followed by a list of colon-separated options. Most
38 noteworthy is :size=n, which is used to set the font size. Note
39 that the font size is also affected by the dpi-aware option.
40 Examples:
42 • Dina:weight=bold:slant=italic
43 • Courier New:size=12
44 • Fantasque Sans Mono:fontfeatures=ss01
45 For each option, the first font is the primary font. The remaining
48 fonts are fallback fonts that will be used whenever a glyph cannot
49 be found in the primary font.
50 The fallback fonts are searched in the order they appear. If a
52 glyph cannot be found in any of the fallback fonts, the dynamic
53 fallback list from fontconfig (for the primary font) is searched.
54 font-bold, font-italic and font-bold-italic allow custom fonts to
56 be used for bold/italic/bold+italic fonts. If left unconfigured,
57 the bold/italic variants of the regular font(s) specified in font
58 are used. Note: you may have to tweak the size(s) of the custom
59 bold/italic fonts to match the regular font.
60 To disable bold and/or italic fonts, set e.g. font-bold to exactly
62 the same value as font.
63 Default: monospace:size=8 (font), not set (font-bold, font-italic,
65 font-bold-italic).
66 include
68 Absolute path to configuration file to import.
69 The import file has its own section scope. I.e. the including con‐
71 figuration is still in the default section after the include, re‐
72 gardless of which section the included file ends in.
73 • The path must be an absolute path, or start with ~/.
75 • Multiple include directives are allowed, but only one path
76 per directive.
77 • Nested imports are allowed.
78 Default: not set.
81 line-height
83 An absolute value, in points, that override line height from the
84 font metrics.
85 You can specify a height in pixels by using the px suffix: e.g.
87 line-height=12px.
88 See also: vertical-letter-offset.
90 Default: not set.
92 letter-spacing
94 Spacing between letters, in points. A positive value will increase
95 the cell size, and a negative value shrinks it.
96 You can specify a letter spacing in pixels by using the px suffix:
98 e.g. letter-spacing=2px.
99 See also: horizontal-letter-offset.
101 Default: 0.
103 horizontal-letter-offset, vertical-letter-offset
105 Configure the horizontal and vertical offsets used when positioning
106 glyphs within cells, in points, relative to the top left corner.
107 To specify an offset in pixels, append px: e.g. horizontal-letter-
109 offset=2px.
110 Default: 0.
112 underline-offset
114 Use a custom offset for underlines. The offset is, by default, in
115 points and relative the font's baseline. A positive value positions
116 the underline under the baseline, while a negative value positions
117 it above the baseline.
118 To specify an offset in pixels, append px: underline-offset=2px.
120 If left unset (the default), the offset specified in the font is
122 used, or estimated by foot if the font lacks underline positioning
123 information.
124 Default: unset.
126 box-drawings-uses-font-glyphs Boolean. When disabled, foot generates
128 box/line drawing characters itself. The are several advantages to
129 doing this instead of using font glyphs:
130 • No antialiasing effects where e.g. line endpoints appear
132 dimmed down, or blurred.
133 • Line- and box characters are guaranteed to span the entire
134 cell, resulting in a gap-less appearance.
135 • No alignment issues, i.e. lines are centered when they
136 should be.
137 • Many fonts lack some, or all, of the line- and box drawing
138 characters, causing fallback fonts to be used, which re‐
139 sults in out-of-place looking glyphs (for example, badly
140 sized).
141 When enabled, box/line drawing characters are rendered using font
144 glyphs. This may result in a more uniform look, in some use cases.
145 Default: no.
147 dpi-aware
149 auto, yes, or no.
150 When set to yes, fonts are sized using the monitor's DPI, making a
152 font of a given size have the same physical size, regardless of
153 monitor. In other words, if you drag a foot window between differ‐
154 ent monitors, the font size remains the same.
155 In this mode, the monitor's scaling factor is ignored; doubling the
157 scaling factor will not double the font size.
158 When set to no, the monitor's DPI is ignored. The font is instead
160 sized using the monitor's scaling factor; doubling the scaling fac‐
161 tor does double the font size.
162 Finally, if set to auto, fonts will be sized using the monitor's
164 DPI if all monitors have a scaling factor of 1. If at least one
165 monitor as a scaling factor larger than 1 (regardless of whether
166 the foot window is mapped on that monitor or not), fonts will be
167 scaled using the scaling factor.
168 Note that this option typically does not work with bitmap fonts,
170 which only contains a pre-defined set of sizes, and cannot be dy‐
171 namically scaled. Whichever size (of the available ones) that best
172 matches the DPI or scaling factor, will be used.
173 Also note that if the font size has been specified in pixels (:pix‐
175 elsize=N, instead of :size=N), DPI scaling (dpi-aware=yes) will
176 have no effect (the specified pixel size will be used as is). But,
177 if the monitor's scaling factor is used to size the font (dpi-
178 aware=no), the font's pixel size will be multiplied with the scal‐
179 ing factor.
180 Default: auto
182 pad
184 Padding between border and glyphs, in pixels (subject to output
185 scaling), on the form XxY.
186 This will add at least X pixels on both the left and right sides,
188 and Y pixels on the top and bottom sides. The grid content will be
189 anchored in the top left corner. I.e. if the window manager forces
190 an odd window size on foot, the additional pixels will be added to
191 the right and bottom sides.
192 To instead center the grid content, append center (e.g. pad=5x5
194 center).
195 Default: 2x2.
197 resize-delay-ms
199 Time, in milliseconds, of "idle time" before foot sends the new
200 window dimensions to the client application while doing an interac‐
201 tive resize of a foot window. Idle time in this context is a period
202 of time where the window size is not changing.
203 In other words, while you are fiddling with the window size, foot
205 does not send the updated dimensions to the client. Only when you
206 pause the fiddling for resize-delay-ms milliseconds is the client
207 updated.
208 Emphasis is on while here; as soon as the interactive resize ends
210 (i.e. when you let go of the window border), the final dimensions
211 is sent to the client, without any delays.
212 Setting it to 0 disables the delay completely.
214 Default: 100.
216 initial-window-size-pixels
218 Initial window width and height in pixels (subject to output scal‐
219 ing), on the form WIDTHxHEIGHT. The height includes the titlebar
220 when using CSDs. Mutually exclusive to initial-window-size-chars.
221 Default: 700x500.
222 initial-window-size-chars
224 Initial window width and height in characters, on the form WIDTHx‐
225 HEIGHT. Mutually exclusive to initial-window-size-pixels.'
226 Note that if you have a multi-monitor setup, with different scaling
228 factors, there is a possibility the window size will not be set
229 correctly. If that is the case, use initial-window-size-pixels in‐
230 stead.
231 Default: not set.
233 initial-window-mode
235 Initial window mode for each newly spawned window: windowed, maxi‐
236 mized or fullscreen. Default: windowed.
237 title
239 Initial window title. Default: foot.
240 locked-title
242 Boolean. If enabled, applications are not allowed to change the ti‐
243 tle at run-time. Default: no.
244 app-id
246 Value to set the app-id property on the Wayland window to. The com‐
247 positor can use this value to e.g. group multiple windows, or apply
248 window management rules. Default: foot.
249 bold-text-in-bright
251 Semi-boolean. When enabled, bold text is rendered in a brighter
252 color (in addition to using a bold font). The color is brightened
253 by increasing its luminance.
254 If set to palette-based, rather than a simple yes|true, colors
256 matching one of the 8 regular palette colors will be brightened us‐
257 ing the corresponding bright palette color. Other colors will not
258 be brightened.
259 Default: no.
261 word-delimiters
263 String of characters that act as word delimiters when selecting
264 text. Note that whitespace characters are always word delimiters,
265 regardless of this setting. Default: ,│`|:"'()[]{}<>
266 notify
268 Command to execute to display a notification. ${title} and ${body}
269 will be replaced with the notification's actual title and body
270 (message content).
271 ${app-id} is replaced with the value of the command line option
273 --app-id, and defaults to foot.
274 ${window-title} is replaced with the current window title.
276 Applications can trigger notifications in the following ways:
278 • OSC 777: \e]777;notify;<title>;<body>\e\\
280 By default, notifications are inhibited if the foot window has key‐
283 board focus. See notify-focus-inhibit.
284 Default: notify-send -a ${app-id} -i ${app-id} ${title} ${body}.
286 notify-focus-inhibit
288 Boolean. If enabled, foot will not display notifications if the
289 terminal window has keyboard focus.
290 Default: yes
292 selection-target
294 Clipboard target to automatically copy selected text to. One of
295 none, primary, clipboard or both. Default: primary.
296 workers
298 Number of threads to use for rendering. Set to 0 to disable multi‐
299 threading. Default: the number of available logical CPUs (including
300 SMT). Note that this is not always the best value. In some cases,
301 the number of physical cores is better.
302
304 urgent
305 When set to yes, foot will signal urgency to the compositor through
306 the XDG activation protocol whenever BEL is received, and the win‐
307 dow does NOT have keyboard foccus.
308 If the compositor does not implement this protocol, the margins
310 will be painted in red instead.
311 Applications can enable/disable this feature programmatically with
313 the CSI ? 1042 h and CSI ? 1042 l escape sequences.
314 Default: no
316 notify
318 When set to yes, foot will emit a desktop notification using the
319 command specified in the notify option whenever BEL is received. By
320 default, bell notifications are shown only when the window does not
321 have keyboard focus. See notify-focus-inhibit.
322 Default: no
324 command
326 When set, foot will execute this command when BEL is received. De‐
327 fault: none
328 command-focused
330 Whether to run the command on BEL even while focused. Default: no
331
333 lines
334 Number of scrollback lines. The maximum number of allocated lines
335 will be this value plus the number of visible lines, rounded up to
336 the nearest power of 2. Default: 1000.
337 multiplier
339 Amount to multiply mouse scrolling with. It is a decimal number,
340 i.e. fractions are allowed. Default: 3.0.
341 indicator-position
343 Configures the style of the scrollback position indicator. One of
344 none, fixed or relative. none disables the indicator completely.
345 fixed always renders the indicator near the top of the window, and
346 relative renders the indicator at the position corresponding to the
347 current scrollback position. Default: relative.
348 indicator-format
350 Which format to use when displaying the scrollback position indica‐
351 tor. Either percentage, line, or a custom fixed string. This option
352 is ignored if indicator-position=none. Default: empty string.
353
355 launch
356 Command to execute when opening URLs. ${url} will be replaced with
357 the actual URL. Default: xdg-open ${url}.
358 osc8-underline
360 When to underline OSC-8 URLs. Possible values are url-mode and al‐
361 ways.
362 When set to url-mode, OSC-8 URLs are only highlighted in URL mode,
364 just like auto-detected URLs.
365 When set to always, OSC-8 URLs are always highlighted, regardless
367 of their other attributes (bold, italic etc). Note that this does
368 not make them clickable.
369 Default: url-mode
371 label-letters
373 String of characters to use when generating key sequences for URL
374 jump labels.
375 If you change this option to include the letter t, you should also
377 change the default [url-bindings].toggle-url-visible key binding to
378 avoid a clash.
379 Default: sadfjklewcmpgh.
381 protocols
383 Comma separated list of protocols (schemes) that should be recog‐
384 nized in URL mode. Note that only auto-detected URLs are affected
385 by this option. OSC-8 URLs are always enabled, regardless of proto‐
386 col. Default: http, https, ftp, ftps, file, gemini, gopher.
387 uri-characters
389 Set of characters allowed in auto-detected URLs. Any character not
390 included in this set constitutes an URL delimiter.
391 Default: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTU‐
393 VWXYZ0123456789-_.,~:;/?#@!$&%*+="'.
394
396 This section controls the cursor style and color. Note that applica‐
397 tions can change these at runtime.
398 style
400 Configures the default cursor style, and is one of: block, beam or
401 underline. Note that this can be overridden by applications. De‐
402 fault: block.
403 blink
405 Boolean. Enables blinking cursor. Note that this can be overridden
406 by applications. Default: no.
407 color
409 Two RRGGBB values (i.e. plain old 6-digit hex values, without pre‐
410 fix) specifying the foreground (text) and background (cursor) col‐
411 ors for the cursor.
412 Default: inversed foreground and background colors.
414 Note that this value only applies to the block cursor. The other
416 cursor styles are always rendered with the foreground color.
417 beam-thickness
419 Thickness (width) of the beam styled cursor. The value is in
420 points, and its exact value thus depends on the monitor's DPI. To
421 instead specify a thickness in pixels, use the px suffix: e.g.
422 beam-thickness=2px. Default: 1.5
423 underline-thickness
425 Thickness (height) of the underline styled cursor. The value is in
426 points, and its exact value thus depends on the monitor's DPI.
427 To instead specify a thickness in pixels, use the px suffix: e.g.
429 underline-thickness=2px.
430 Note that if left unset, the cursor's thickness will scale with the
432 font size, while if set, the size is fixed.
433 Default: font underline thickness.
435
437 hide-when-typing
438 Boolean. When enabled, the mouse cursor is hidden while typing. De‐
439 fault: no.
440 alternate-scroll-mode
442 Boolean. This option controls the initial value for the alternate
443 scroll mode. When this mode is enabled, mouse scroll events are
444 translated to up/down key events when displaying the alternate
445 screen.
446 This lets you scroll with the mouse in e.g. pagers (like less)
448 without enabling native mouse support in them.
449 Alternate scrolling is not used if the application enables native
451 mouse support.
452 This option can be modified by applications at run-time using the
454 escape sequences CSI ? 1007 h (enable) and CSI ? 1007 l (disable).
455 Default: yes.
457
459 This section controls the 16 ANSI colors, the default foreground and
460 background colors, and the extended 256 color palette. Note that appli‐
461 cations can change these at runtime.
462 The colors are in RRGGBB format (i.e. plain old 6-digit hex values,
464 without prefix). That is, they do not have an alpha component. You can
465 configure the background transparency with the alpha option.
466 foreground
468 Default foreground color. This is the color used when no ANSI color
469 is being used. Default: dcdccc.
470 background
472 Default background color. This is the color used when no ANSI color
473 is being used. Default: 111111.
474 regular0, regular1 .. regular7
476 The eight basic ANSI colors. Default: 222222, cc9393, 7f9f7f,
477 d0bf8f, 6ca0a3, dc8cc3, 93e0e3 and dcdccc (a variant of the zenburn
478 theme).
479 bright0, bright1 .. bright7
481 The eight bright ANSI colors. Default: 666666, dca3a3, bfebbf,
482 f0dfaf, 8cd0d3, fcace3, b3ffff and ffffff (a variant of the zenburn
483 theme).
484 dim0, dim1 .. dim7
486 Custom colors to use with dimmed colors. Dimmed colors do not have
487 an entry in the color palette. Applications emit them by combining
488 a color value, and a "dim" attribute.
489 By default, foot implements this by reducing the luminance of the
491 current color. This is a generic approach that applies to both col‐
492 ors from the 256-color palette, as well as 24-bit RGB colors.
493 You can change this behavior by setting the dimN options. When set,
495 foot will match the current color against the color palette, and if
496 it matches one of the regularN colors, the corresponding dimN color
497 will be used.
498 If instead the current color matches one of the brightN colors, the
500 corresponding regularn color will be used.
501 If the current color does not match any known colors, it is dimmed
503 by reducing the luminance (i.e. the same behavior as if the dimN
504 options are unconfigured). 24-bit RGB colors will typically fall
505 into this category.
506 Note that applications can change the regularN and brighN colors at
508 runtime. However, they have no way of changing the dimN colors. If
509 an application has changed the regularN colors, foot will still use
510 the corresponding dimN color, as configured in foot.ini.
511 Default: not set.
513 0 .. 255
515 Arbitrary colors in the 256-color palette. Default: for 0 .. 15,
516 see regular and bright defaults above; see
517 https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit for an expla‐
518 nation of the remainder.
519 alpha
521 Background translucency. A value in the range 0.0-1.0, where 0.0
522 means completely transparent, and 1.0 is opaque. Default: 1.0.
523 selection-foreground, selection-background
525 Foreground (text) and background color to use in selected text.
526 Note that both options must be set, or the default will be used.
527 Default: inverse foreground/background.
528 jump-labels
530 To color values specifying the foreground (text) and background
531 colors to use when rendering jump labels in URL mode. Default: reg‐
532 ular0 regular3.
533 scrollback-indicator
535 Two color values specifying the foreground (text) and background
536 (indicator itself) colors for the scrollback indicator.
537 Default: first regular color (black) for foreground, and fifth
539 bright color (light blue) for background.
540 urls
542 Color to use for the underline used to highlight URLs in URL mode.
543 Default: regular3.
544
546 This section controls the look of the CSDs (Client Side Decorations).
547 Note that the default is to not use CSDs, but instead to use SSDs
548 (Server Side Decorations) when the compositor supports it.
549 Note that unlike the colors defined in the colors section, the color
551 values here are in AARRGGBB (i.e. plain old 8-digit hex values) format.
552 I.e. they contain an alpha component - 00 means completely transparent,
553 and ff fully opaque.
554 Examples:
556 • ffffffff: white, fully opaque
558 • ff000000: black, fully opaque
559 • 7fffffff: white, semi-transparent
560 • ff00ff00: green, fully opaque
561 preferred
564 Which type of window decorations to prefer: client (CSD), server
565 (SSD) or none.
566 Note that this is only a hint to the compositor. Depending on com‐
568 positor support, and how it has been configured, it may instruct
569 foot to use CSDs even though this option has been set to server, or
570 render SSDs despite client or none being set.
571 Default: server.
573 size
575 Height, in pixels (subject to output scaling), of the titlebar. De‐
576 fault: 26.
577 color
579 Titlebar color. Default: use the default foreground color.
580 font
582 Font to use for the title bar. This is a list of fonts, similar to
583 the main font option. Note that the font will be sized using the
584 title bar size. That is, all :size and :pixelsize attributes will
585 be ignored. Default: primary font.
586 border-width
588 Width of the border, in pixels (subject to output scaling). Note
589 that the border encompasses the entire window, including the title
590 bar. Default: 0.
591 border-color
593 Color of border. By default, the title bar color is used. If the
594 title bar color has not been set, the default foreground color
595 (from the color scheme) is used. Default: titlebar color.
596 button-width
598 Width, in pixels (subject to output scaling), of the minimize/maxi‐
599 mize/close buttons. Default: 26.
600 button-color
602 Foreground color on the minimize/maximize/close buttons. Default:
603 use the default background color.
604 button-minimize-color
606 Minimize button's background color. Default: use the default regu‐
607 lar4 color (blue).
608 button-maximize-color
610 Maximize button's background color. Default: use the default regu‐
611 lar2 color (green).
612 button-close-color
614 Close button's background color. Default: use the default regular1
615 color (red).
616
618 This section lets you override the default key bindings.
619 The general format is action=combo1...comboN. That is, each action may
621 have one or more key combinations, space separated. Each combination is
622 on the form mod1+mod2+key. The names of the modifiers and the key must
623 be valid XKB key names.
624 Note that if Shift is one of the modifiers, the key must not be in up‐
626 per case. For example, Control+Shift+V will never trigger, but Con‐
627 trol+Shift+v will.
628 Note that Alt is usually called Mod1.
630 xkbcli interactive-wayland can be useful for finding keysym names.
632 A key combination can only be mapped to one action. Lets say you want
634 to bind Control+Shift+R to fullscreen. Since this is the default short‐
635 cut for search-start, you first need to unmap the default binding. This
636 can be done by setting action=none; e.g. search-start=none.
637 noop
639 All key combinations listed here will not be sent to the applica‐
640 tion. Default: not bound.
641 scrollback-up-page
643 Scrolls up/back one page in history. Default: Shift+Page_Up.
644 scrollback-up-half-page
646 Scrolls up/back half of a page in history. Default: not bound.
647 scrollback-up-line
649 Scrolls up/back a single line in history. Default: not bound.
650 scrollback-down-page
652 Scroll down/forward one page in history. Default: Shift+Page_Down.
653 scrollback-down-half-page
655 Scroll down/forward half of a page in history. Default: not bound.
656 scrollback-down-line
658 Scroll down/forward a single line in history. Default: not bound.
659 clipboard-copy
661 Copies the current selection into the clipboard. Default: Con‐
662 trol+Shift+c.
663 clipboard-paste
665 Pastes from the clipboard. Default: Control+Shift+v.
666 primary-paste
668 Pastes from the primary selection. Default: Shift+Insert (also de‐
669 fined in mouse-bindings).
670 search-start
672 Starts a scrollback/history search. Default: Control+Shift+r.
673 font-increase
675 Increases the font size by 0.5pt. Default: Control+plus Con‐
676 trol+equal Control+KP_Add.
677 font-decrease
679 Decreases the font size by 0.5pt. Default: Control+minus Con‐
680 trol+KP_Subtract.
681 font-reset
683 Resets the font size to the default. Default: Control+0 Con‐
684 trol+KP_0.
685 spawn-terminal
687 Spawns a new terminal. If the shell has been configured to emit the
688 OSC 7 escape sequence, the new terminal will start in the current
689 working directory. Default: Control+Shift+n.
690 minimize
692 Minimizes the window. Default: not bound.
693 maximize
695 Toggle the maximized state. Default: not bound.
696 fullscreen
698 Toggles the fullscreen state. Default: not bound.
699 pipe-visible, pipe-scrollback, pipe-selected
701 Pipes the currently visible text, the entire scrollback, or the
702 currently selected text to an external tool. The syntax for this
703 option is a bit special; the first part of the value is the command
704 to execute enclosed in "[]", followed by the binding(s).
705 You can configure multiple pipes as long as the command strings are
707 different and the key bindings are unique.
708 Note that the command is not automatically run inside a shell; use
710 sh -c "command line" if you need that.
711 Example:
713 pipe-visible=[sh -c "xurls | uniq | tac | fuzzel | xargs -r
714 firefox"] Control+Print
715 Default: not bound
717 show-urls-launch
719 Enter URL mode, where all currently visible URLs are tagged with a
720 jump label with a key sequence that will open the URL. Default:
721 Control+Shift+u.
722 show-urls-copy
724 Enter URL mode, where all currently visible URLs are tagged with a
725 jump label with a key sequence that will place the URL in the clip‐
726 board. Default: none.
727
729 This section lets you override the default key bindings used in scroll‐
730 back search mode. The syntax is exactly the same as the regular key-
731 bindings.
732 cancel
734 Aborts the search. The viewport is restored and the primary selec‐
735 tion is not updated. Default: Control+g Control+c Escape.
736 commit
738 Exit search mode and copy current selection into the primary selec‐
739 tion. Viewport is not restored. To copy the selection to the regu‐
740 lar clipboard, use Control+Shift+c. Default: Return.
741 find-prev
743 Search backwards in the scrollback history for the next match. De‐
744 fault: Control+r.
745 find-next
747 Searches forwards in the scrollback history for the next match. De‐
748 fault: Control+s.
749 cursor-left
751 Moves the cursor in the search box one character to the left. De‐
752 fault: Left Control+b.
753 cursor-left-word
755 Moves the cursor in the search box one word to the left. Default:
756 Control+Left Mod1+b.
757 cursor-right
759 Moves the cursor in the search box one character to the right. De‐
760 fault: Right Control+f.
761 cursor-right-word
763 Moves the cursor in the search box one word to the right. Default:
764 Control+Right Mod1+f.
765 cursor-home
767 Moves the cursor in the search box to the beginning of the input.
768 Default: Home Control+a.
769 cursor-end
771 Moves the cursor in the search box to the end of the input. De‐
772 fault: End Control+e.
773 delete-prev
775 Deletes the character before the cursor. Default: BackSpace.
776 delete-prev-word
778 Deletes the word before the cursor. Default: Mod1+BackSpace Con‐
779 trol+BackSpace.
780 delete-next
782 Deletes the character after the cursor. Default: Delete.
783 delete-next-word
785 Deletes the word after the cursor. Default: Mod1+d Control+Delete.
786 extend-to-word-boundary
788 Extend current selection to the next word boundary. Default: Con‐
789 trol+w.
790 extend-to-next-whitespace
792 Extend the current selection to the next whitespace. Default: Con‐
793 trol+Shift+w.
794 clipboard-paste
796 Paste from the clipboard into the search buffer. Default: Control+v
797 Control+y.
798 primary-paste
800 Paste from the primary selection into the search buffer. Default:
801 Shift+Insert.
802
804 This section lets you override the default key bindings used in URL
805 mode. The syntax is exactly the same as the regular key-bindings.
806 Be careful; do not use single-letter keys that are also used in
808 [url].label-letters, as doing so will make some URLs inaccessible.
809 cancel
811 Exits URL mode without opening an URL. Default: Control+g Control+c
812 Control+d Escape.
813 toggle-url-visible
815 By default, the jump label only shows the key sequence required to
816 activate it. This is fine as long as the URL is visible in the
817 original text.
818 But with e.g. OSC-8 URLs (the terminal version of HTML anchors,
820 i.e. "links"), the text on the screen can be something completey
821 different than the URL.
822 This action toggles between showing and hiding the URL on the jump
824 label.
825 Default: t.
827
829 This section lets you override the default mouse bindings.
830 The general format is action=combo1...comboN. That is, each action may
832 have one or more key combinations, space separated. Each combination is
833 on the form mod1+mod2+BTN_<name>[-COUNT]. The names of the modifiers
834 must be valid XKB key names, and the button name must be a valid libin‐
835 put name. You can find the button names using libinput debug-events.
836 Note that Shift cannot be used as a modifier in mouse bindings since it
838 is used to enable selection when the client application is grabbing the
839 mouse.
840 The trailing COUNT is optional and specifies the click count required
842 to trigger the binding. The default if COUNT is omitted is 1.
843 A modifier+button combination can only be mapped to one action. Lets
845 say you want to bind BTN_MIDDLE to fullscreen. Since BTN_MIDDLE is the
846 default binding for primary-paste, you first need to unmap the default
847 binding. This can be done by setting action=none; e.g. primary-
848 paste=none.
849 All actions listed under key-bindings can be used here as well.
851 select-begin
853 Begin an interactive selection. The selection is finalized, and
854 copied to the primary selection, when the button is released. De‐
855 fault: BTN_LEFT.
856 select-begin-block
858 Begin an interactive block selection. The selection is finalized,
859 and copied to the primary selection, when the button is released.
860 Default: Control+BTN_LEFT.
861 select-word
863 Begin an interactive word-wise selection, where words are separated
864 by whitespace and all characters defined by the word-delimiters op‐
865 tion. The selection is finalized, and copied to the primary selec‐
866 tion, when the button is released. Default: BTN_LEFT-2.
867 select-word-whitespace
869 Same as select-word, but the characters in the word-delimiters op‐
870 tion are ignored. I.e only whitespace characters act as delimiters.
871 The selection is finalized, and copied to the primary selection,
872 when the button is released. Default: Control+_BTN_LEFT-2.
873 select-row
875 Begin an interactive row-wise selection. The selection is final‐
876 ized, and copied to the primary selection, when the button is re‐
877 leased. Default: BTN_LEFT-3.
878 select-extend
880 Interactively extend an existing selection, using the original se‐
881 lection mode (normal, block, word-wise or row-wise). The selection
882 is finalized, and copied to the primary selection, when the button
883 is released. Default: BTN_RIGHT.
884 select-extend-character-wise
886 Same as select-extend, but forces the selection mode to normal
887 (i.e. character wise). Note that this causes subsequent select-ex‐
888 tend operations to be character wise. This action is ignored for
889 block selections. Default: Control+BTN_RIGHT.
890 primary-paste
892 Pastes from the primary selection. Default: BTN_MIDDLE.
893
895 This section is for advanced users and describes configuration options
896 that can be used to tweak foot's low-level behavior.
897 These options are not included in the example configuration. You should
899 not change these unless you understand what they do.
900 Note that these options may change, or be removed at any time, without
902 prior notice.
903 When reporting bugs, please mention if, and to what, you have changed
905 any of these options.
906 scaling-filter
908 Overrides the default scaling filter used when down-scaling bitmap
909 fonts (e.g. emoji fonts). Possible values are none, nearest, bilin‐
910 ear, cubic or lanczos3. cubic and lanczos3 produce the best re‐
911 sults, but are slower (with lanczos3 being the best and slowest).
912 Default: lanczos3.
914 overflowing-glyphs
916 Boolean. When enabled, glyphs wider than their cell(s) are allowed
917 to render into one additional neighbouring cell.
918 One use case for this are fonts with wide italic characters that
920 "bend" into the next cell. Without this option, such glyphs will
921 appear "cut off".
922 Another use case are fonts with "icon" characters in the Unicode
924 private usage area, e.g. Nerd Fonts, or Powerline Fonts and legacy
925 emoji characters like WHITE FROWNING FACE.
926 Note: might impact performance depending on the font used. Espe‐
928 cially small font sizes can cause many overflowing glyphs because
929 of subpixel rendering.
930 Default: yes.
932 render-timer
934 Enables a frame rendering timer, that prints the time it takes to
935 render each frame, in microseconds, either on-screen, to stderr, or
936 both. Valid values are none, osd, log and both. Default: none.
937 box-drawing-base-thickness
939 Line thickness to use for LIGHT box drawing line characters, in
940 points. This value is converted to pixels using the monitor's DPI,
941 and then multiplied with the cell size. The end result is that a
942 larger font (and thus larger cells) result in thicker lines. De‐
943 fault: 0.04.
944 box-drawing-solid-shades
946 Boolean. When enabled, box drawing "shades" (e.g. LIGHT SHADE,
947 MEDIUM SHADE and DARK SHADE) are rendered as solid blocks using a
948 darker variant of the current foreground color.
949 When disabled, they are instead rendered as checker box pattern,
951 using the current foreground color as is.
952 Default: yes.
954 delayed-render-lower, delayed-render-upper
956 These two values control the timeouts (in nanoseconds) that are
957 used to mitigate screen flicker caused by clients writing large,
958 non-atomic screen updates.
959 If a client splits up a screen update over multiple write(3) calls,
961 we may end up rendering an intermediate frame, quickly followed by
962 another frame with the final screen content. For example, the
963 client may erase part of the screen (or scroll) in one write, and
964 then write new content in one or more subsequent writes. Rendering
965 the frame when the screen has been erased, but not yet filled with
966 new content will be perceived as screen flicker.
967 The real solution to this is Application Synchronized Updates
969 (https://gitlab.freedesktop.org/terminal-wg/specifica‐
970 tions/-/merge_requests/2).
971 The problem with this is twofold - first, it has not yet been stan‐
973 dardized, and thus there are not many terminal emulators that im‐
974 plement it (foot does implement it), and second, applications must
975 be patched to use it.
976 Until this has happened, foot offers an interim workaround; an at‐
978 tempt to mitigate the screen flicker without affecting neither per‐
979 formance nor latency.
980 It is based on the fact that the screen is updated at a fixed in‐
982 terval (typically 60Hz). For us, this means it does not matter if
983 we render a new frame at the beginning of a frame interval, or at
984 the end. Thus, the goal is to introduce a delay between receiving
985 client data and rendering the resulting state, but without causing
986 a frame skip.
987 While it should be possible to estimate the amount of time left un‐
989 til the next frame, foot's algorithm is currently not that ad‐
990 vanced, but is based on statistics I guess you could say - the de‐
991 lay we introduce is so small that the risk of pushing the frame
992 over to the next frame interval is also very small.
993 Now, that was a lot of text. But what is it foot actually does?
995 When receiving client data, it schedules a timer, the delayed-ren‐
997 der-lower. If we do not receive any more client data before the
998 timer has run out, we render the frame. If however, we do receive
999 more data, the timer is re-scheduled. That is, each time we receive
1000 client data, frame rendering is delayed another delayed-render-
1001 lower nanoseconds.
1002 Now, while this works very well with most clients, it would be pos‐
1004 sible to construct a malicious client that keeps writing data at a
1005 slow pace. To the user, this would look like foot has frozen as we
1006 never get to render a new frame. To prevent this, an upper limit is
1007 set - delayed-render-upper. If this timer runs out, we render the
1008 frame regardless of what the client is doing.
1009 If changing these values, note that the lower timeout must be set
1011 lower than the upper timeout, but that this is not verified by
1012 foot. Furthermore, both values must be less than 16ms (that is,
1013 16000000 nanoseconds).
1014 You can disable the feature altogether by setting either value to
1016 0. In this case, frames are rendered "as soon as possible".
1017 Default: lower=500000 (0.5ms), upper=8333333 (8.3ms - half a frame
1019 interval).
1020 damage-whole-window
1022 Boolean. When enabled, foot will 'damage' the entire window each
1023 time a frame has been rendered. This forces the compositor to re‐
1024 draw the entire window. If disabled, foot will only 'damage' up‐
1025 dated rows.
1026 There is normally no reason to enable this. However, it has been
1028 seen to workaround an issue with fractional scaling in Gnome.
1029 Note that enabling this option is likely to increase CPU and/or GPU
1031 usage (by the compositor, not by foot), and may have a negative im‐
1032 pact on battery life.
1033 Default: no.
1035 grapheme-shaping
1037 Boolean. When enabled, foot will use utf8proc to do grapheme clus‐
1038 ter segmentation while parsing "printed" text. Then, when render‐
1039 ing, it will use fcft (if compiled with HarfBuzz support) to shape
1040 the grapheme clusters.
1041 This is required to render e.g. flag (emoji) sequences, keycap se‐
1043 quences, modifier sequences, zero-width-joiner (ZWJ) sequences and
1044 emoji tag sequences. It might also improve rendering of composed
1045 characters, depending on font.
1046 • foot must have been compiled with utf8proc support
1048 • fcft must have been compiled with HarfBuzz support
1049 See also: grapheme-width-method.
1052 Default: yes
1054 grapheme-width-method
1056 Selects which method to use when calculating the width (i.e. number
1057 of columns) of a grapheme cluster. One of double-width and wc‐
1058 swidth.
1059 wcswidth simply adds together the individual width of all code‐
1061 points making up the cluster.
1062 double-width does the same, but limits the maximum number of col‐
1064 umns to 2. This is more correct, but may break some applications
1065 since applications typically use wcswidth(3) internally to calcu‐
1066 late the width. This results in cursor de-synchronization issues.
1067 Default: wcswidth
1069 font-monospace-warn
1071 Boolean. When enabled, foot will use heuristics to try to verify
1072 the primary font is a monospace font, and warn if it is not.
1073 Disable this if you still want to use the font, even if foot thinks
1075 it is not monospaced.
1076 You may also want to disable it to get slightly faster startup
1078 times.
1079 Default: yes
1081 max-shm-pool-size-mb
1083 This option controls the amount of virtual address space used by
1084 the pixmap memory to which the terminal screen content is rendered.
1085 It does not change how much physical memory foot uses.
1087 Foot uses a memory mapping trick to implement fast rendering of in‐
1089 teractive scrolling (typically, but applies to "slow" scrolling in
1090 general). Example: holding down the 'up' or 'down' arrow key to
1091 scroll in a text editor.
1092 For this to work, it needs a large amount of virtual address space.
1094 Again, note that this is not physical memory.
1095 On a normal x64 based computer, each process has 128TB of virtual
1097 address space, and newer ones have 64PB. This is an insane amount
1098 and most applications do not use anywhere near that amount.
1099 Each foot terminal window can allocate up to 2GB of virtual address
1101 space. With 128TB of address space, that means a maximum of 65536
1102 windows in server/daemon mode (for 2GB). That should be enough,
1103 yes?
1104 However, the Wayland compositor also needs to allocate the same
1106 amount of virtual address space. Thus, it has a slightly higher
1107 chance of running out of address space since it needs to host all
1108 running Wayland clients in the same way, at the same time.
1109 In the off chance that this becomes a problem for you, you can re‐
1111 duce the amount used with this option.
1112 Or, for optimal performance, you can increase it to the maximum al‐
1114 lowed value, 2GB (but note that you most likely will not notice any
1115 difference compared to the default value).
1116 Setting it to 0 disables the feature.
1118 Limitations:
1120 • only supported on 64-bit architectures
1121 • only supported on Linux
1122 Default: 512. Maximum allowed: 2048 (2GB).
1125
1127 foot(1), footclient(1)
1128 2021-11-22 foot.ini(5)