foot - Man Page

Wayland terminal emulator

Synopsis

foot [Options]
foot [Options] <command> [COMMAND Options]

All trailing (non-option) arguments are treated as a command, and its arguments, to execute (instead of the default shell).

Description

foot is a Wayland terminal emulator. Running it without arguments will start a new terminal window with your default shell.

You can override the default shell by appending a custom command to the foot command line

foot sh -c "echo hello world && sleep 5"

Options

-c,--config=PATH

Path to configuration file. Default: $XDG_CONFIG_HOME/foot/foot.ini.

-C,--check-config

Verify configuration and then exit with 0 if ok, otherwise exit with 230 (see Exit Status).

-o,--override=[SECTION.]KEY=VALUE

Override an option set in the configuration file. If SECTION is not given, defaults to main.

-f,--font=FONT

Comma separated list of fonts to use, in fontconfig format (see Font Format).

The first font is the primary font. The remaining fonts are fallback fonts that will be used whenever a glyph cannot be found in the primary font.

The fallback fonts are searched in the order they appear. If a glyph cannot be found in any of the fallback fonts, the dynamic fallback list from fontconfig (for the primary font) is searched.

Default: monospace.

-w,--window-size-pixels=WIDTHxHEIGHT

Set initial window width and height, in pixels. Default: 700x500.

-W,--window-size-chars=WIDTHxHEIGHT

Set initial window width and height, in characters. Default: not set.

-t,--term=TERM

Value to set the environment variable TERM to (see Terminfo and Environment). Default: foot.

-T,--title=TITLE

Initial window title. Default: foot.

-a,--app-id=ID

Value to set the app-id property on the Wayland window to. Default: foot.

-m,--maximized

Start in maximized mode. If both --maximized and --fullscreen are specified, the last one takes precedence.

-F,--fullscreen

Start in fullscreen mode. If both --maximized and --fullscreen are specified, the last one takes precedence.

-L,--login-shell

Start a login shell, by prepending a '-' to argv[0].

-D,--working-directory=DIR

Initial working directory for the client application. Default: CWD of foot.

-s,--server[=PATH]

Run as a server. In this mode, a single foot instance hosts multiple terminals (windows). Use footclient(1) to launch new terminals.

This saves some memory since for example fonts and glyph caches can be shared between the terminals.

It also saves upstart time since the config has already been loaded and parsed, and most importantly, fonts have already been loaded (and their glyph caches are likely to already have been populated).

Each terminal will have its own rendering threads, but all Wayland communication, as well as input/output to the shell, is multiplexed in the main thread. Thus, this mode might result in slightly worse performance when multiple terminals are under heavy load.

Also be aware that should one terminal crash, it will take all the others with it.

The default path is $XDG_RUNTIME_DIR/foot-$WAYLAND_DISPLAY.sock.

If $XDG_RUNTIME_DIR is not set, the default path is instead /tmp/foot.sock.

If $XDG_RUNTIME_DIR is set, but $WAYLAND_DISPLAY is not, the default path is $XDG_RUNTIME_DIR/foot.sock.

Note that if you change the default, you will also need to use the --server-socket option in footclient(1) and point it to your custom socket path.

-H,--hold

Remain open after child process exits.

-p,--print-pid=FILE|FD

Print PID to this file, or FD, when successfully started. The file (or FD) is closed immediately after writing the PID. When a FILE as been specified, the file is unlinked at exit.

This option can only be used in combination with -s,--server.

-d,--log-level={info,warning,error,none}

Log level, used both for log output on stderr as well as syslog. Default: info.

-l,--log-colorize=[{never,always,auto}]

Enables or disables colorization of log output on stderr. Default: auto.

-S,--log-no-syslog

Disables syslog logging. Logging is only done on stderr. This option can only be used in combination with -s,--server.

-v,--version

Show the version number and quit.

Exit Status

Foot will exit with code 230 if there is a failure in foot itself.

In all other cases, the exit code is that of the client application (i.e. the shell).

Keyboard Shortcuts

The following keyboard shortcuts are available.

Normal Mode

Note that these are just the defaults; they can be changed in foot.ini(5).

shift+page up/page down

Scroll up/down in history

ctrl+shift+c

Copy selected text to the clipboard

ctrl+shift+v

Paste from clipboard

shift+insert

Paste from the primary selection.

ctrl+shift+r

Start a scrollback search

ctrl++, ctrl+=

Increase font size by 1pt

ctrl+-

Decrease font size by 1pt

ctrl+0

Reset font size

ctrl+shift+n

Spawn a new terminal. If the shell has been configured to emit the OSC 7 escape sequence, the new terminal will start in the current working directory.

Mouse Shortcuts

left, single-click

Drag to select; when released, the selected text is copied to the primary selection. This feature is normally disabled whenever the client has enabled mouse tracking, but can be forced by holding shift.

Holding ctrl will create a block selection.

left, double-click

Selects the word (separated by spaces, period, comma, parenthesis etc) under the pointer. Hold ctrl to select everything under the pointer up to, and until, the next space characters.

left, triple-click

Selects the entire row

middle

Paste from the primary selection

right

Extend current selection. Clicking immediately extends the selection, while hold-and-drag allows you to interactively resize the selection.

wheel

Scroll up/down in history

Font Format

The font is specified in FontConfig syntax. That is, a colon-separated list of font name and font options.

Examples:
  • Dina:weight=bold:slant=italic
  • Courier New:size=12

URLs

Foot supports URL detection. But, unlike many other terminal emulators, where URLs are highlighted when they are hovered and opened by clicking on them, foot uses a keyboard driven approach.

Pressing ctrl+shift+u enters “URL mode”, where all currently visible URLs are underlined, and is associated with a “jump-label”. The jump-label indicates the key sequence (e.g. ”AF”) to use to activate the URL.

The key binding can, of course, be customized, like all other key bindings in foot. See show-urls-launch and show-urls-copy in foot.ini(5).

show-urls-launch by default opens the URL with xdg-open. This can be changed with the url-launch option.

show-urls-copy is an alternative to show-urls-launch, that changes what activating an URL does; instead of opening it, it copies it to the clipboard. It is unbound by default.

Jump label colors, the URL underline color, and the letters used in the jump label key sequences can be configured.

Alt/Meta Characters

By default, foot prefixes meta characters with ESC. This corresponds to XTerm's metaSendsEscape option set to true.

This can be disabled programmatically with E[?1036l (and enabled again with E[?1036h).

When disabled, foot will instead set the 8:th bit of meta character and then UTF-8 encode it. This corresponds to XTerm's eightBitMeta option set to true.

This can also be disabled programmatically with rmm (Reset Meta Mode, E[?1034l), and enabled again with smm (Set Meta Mode, E[?1034h).

Backspace

Foot transmits DEL (^?) on backspace. This corresponds to XTerm's backarrowKey option set to false, and to DECBKM being reset.

To instead transmit BS (^H), press ctrl+backspace.

Note that foot does not implement DECBKM, and that the behavior described above cannot be changed.

Finally, pressing alt will prefix the transmitted byte with ESC.

Keypad

By default, Num Lock overrides the run-time configuration keypad mode; when active, the keypad is always considered to be in numerical mode. This corresponds to XTerm's numLock option set to true.

In this mode, the keypad keys always sends either numbers (Num Lock is active) or cursor movement keys (up, down, left, right, page up, page down etc).

This can be disabled programmatically with E[?1035l (and enabled again with E[?1035h).

When disabled, the keypad sends custom escape sequences instead of numbers, when in application mode.

Configuration

See foot.ini(5)

Terminfo

Client applications use the terminfo identifier specified by the environment variable TERM (set by foot) to determine terminal capabilities.

Foot has two terminfo definitions: foot and foot-direct, with foot being the default.

The difference between the two is in the number of colors they describe; foot describes 256 colors and foot-direct 16.7 million colors (24-bit truecolor).

Note that using the foot terminfo does not limit the number of usable colors to 256; applications can still use 24-bit RGB colors. In fact, most applications work best with foot (including 24-bit colors)). Using *-direct terminfo entries has been known to crash some ncurses applications even.

There are however applications that need a *-direct terminfo entry for 24-bit support. Emacs is one such example.

While using either foot or foot-direct is strongly recommended, it is possible to use e.g. xterm-256color as well. This can be useful when remoting to a system where foot's terminfo entries cannot easily be installed.

Note that terminfo entries can be installed in the user's home directory. I.e. if you do not have root access, or if there is no distro package for foot's terminfo entries, you can install foot's terminfo entries manually, by copying foot and foot-direct to ~/.terminfo/f/.

Environment

The following environment variables are used by foot:

SHELL

The default child process to run, when no command argument is specified and the shell option in foot.ini(5) is not set.

XDG_CONFIG_HOME

Used to determine the default location of foot.ini(5).

XDG_CONFIG_DIRS

Used to determine the default fallback location of foot.ini(5), when not found in ${XDG_CONFIG_HOME:-~/.config}.

XDG_RUNTIME_DIR

Used to construct the default PATH for the --server option, when no explicit argument is given (see above).

WAYLAND_DISPLAY

Used to construct the default PATH for the --server option, when no explicit argument is given (see above).

XCURSOR_THEME

The name of the Xcursor(3) theme to use for pointers (typically set by the Wayland compositor).

XCURSOR_SIZE

The size to use for Xcursor(3) pointers (typically set by the Wayland compositor).

The following environment variables are set in the child process:

TERM

terminfo/termcap identifier. This is used by client applications to determine which capabilities a terminal supports. The value is set according to either the --term command-line option or the term config option in foot.ini(5).

COLORTERM

This variable is set to truecolor, to indicate to client applications that 24-bit RGB colors are supported.

Bugs

Please report bugs to https://codeberg.org/dnkl/foot/issues

The report should contain the following:

  • Which Wayland compositor (and version) you are running
  • Foot version (foot --version)
  • Log output from foot (start foot from another terminal)
  • If reporting a crash, please try to provide a bt full backtrace with symbols
  • Steps to reproduce. The more details the better

IRC

#foot on irc.libera.chat

See Also

foot.ini(5), footclient(1)

Referenced By

footclient(1), foot.ini(5).

2021-07-20