foot(1) | General Commands Manual | foot(1) |
NAME¶
foot - 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
OPTIONS¶
-c,--config=PATH
-C,--check-config
-o,--override=[SECTION.]KEY=VALUE
-f,--font=FONT
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
-W,--window-size-chars=WIDTHxHEIGHT
-t,--term=TERM
-T,--title=TITLE
-a,--app-id=ID
-m,--maximized
-F,--fullscreen
-L,--login-shell
--pty
This option is not currently supported in combination with -s,--server.
-D,--working-directory=DIR
-s,--server[=PATH|FD]
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.
If the argument is a number, foot will interpret it as the file descriptor of a socket provided by a supervision daemon (such as systemd or s6), and use that socket as it's own.
Two systemd units (foot-server.{service,socket}) are provided to use that feature with systemd. To use socket activation, only enable the socket unit.
Note that starting foot --server as a systemd service will use the environment of the systemd user instance; thus, you'll need to import $WAYLAND_DISPLAY in it using systemctl --user import-environment WAYLAND_DISPLAY.
-H,--hold
-p,--print-pid=FILE|FD
This option can only be used in combination with -s,--server.
-d,--log-level={info,warning,error,none}
-l,--log-colorize=[{never,always,auto}]
-S,--log-no-syslog
-v,--version
-e
This option was added in response to several program launchers passing -e to arbitrary terminals, under the assumption that they all implement the same semantics for it as xterm(1). Ignoring it allows foot to be invoked as e.g. foot -e man foot with the same results as with xterm, instead of producing an "invalid option" error.
KEYBOARD SHORTCUTS¶
The following keyboard shortcuts are available by default. They can be changed in foot.ini(5). There are also more actions (disabled by default) available; see foot.ini(5).
NORMAL MODE¶
shift+page up/page down
ctrl+shift+c, XF86Copy
ctrl+shift+v, XF86Paste
shift+insert
ctrl+shift+r
ctrl++, ctrl+=
ctrl+-
ctrl+0
ctrl+shift+n
ctrl+shift+o
ctrl+shift+u
ctrl+shift+z
ctrl+shift+x
SCROLLBACK SEARCH¶
ctrl+r
ctrl+s
ctrl+w
ctrl+shift+w
ctrl+v, ctrl+shift+v, ctrl+y, XF86Paste
shift+insert
escape, ctrl+g, ctrl+c
return
URL MODE¶
t
escape, ctrl+g, ctrl+c, ctrl+d
MOUSE SHORTCUTS¶
left, single-click
Holding ctrl will create a block selection.
left, double-click
left, triple-click
left, quad-click
middle
right
ctrl+right
wheel
ctrl+wheel
TOUCHSCREEN¶
tap
drag
Holding for a while before dragging (time delay can be configured) emulates mouse dragging with left button held.
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+o enters "Open 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 a 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¶
foot will search for a configuration file in the following locations, in this order:
- XDG_CONFIG_HOME/foot/foot.ini (defaulting to $HOME/.config/foot/foot.ini if unset)
- XDG_CONFIG_DIRS/foot/foot.ini (defaulting to /etc/xdg/foot/foot.ini if unset)
An example configuration file containing all options with their default value commented out will usually be installed to /etc/xdg/foot/foot.ini.
For more information, see foot.ini(5).
SHELL INTEGRATION¶
Current working directory¶
New foot terminal instances (bound to ctrl+shift+n by default) will open in the current working directory, if the shell in the "parent" terminal reports directory changes.
This is done with the OSC-7 escape sequence. Most shells can be scripted to do this, if they do not support it natively. See the wiki (https://codeberg.org/dnkl/foot/wiki#user-content-spawning-new-terminal-instances-in-the-current-working-directory) for details.
Jumping between prompts¶
Foot can move the current viewport to focus prompts of already executed commands (bound to ctrl+shift+z/x by default).
For this to work, the shell needs to emit an OSC-133;A (\E]133;A\E\\) sequence before each prompt.
In zsh, one way to do this is to add a precmd hook:
See the wiki (https://codeberg.org/dnkl/foot/wiki#user-content-jumping-between-prompts) for details, and examples for other shells.
Piping last command's output¶
The key binding pipe-command-output can pipe the last command's output to an application of your choice (similar to the other pipe-* key bindings):
pipe-command-output=[sh -c "f=$(mktemp); cat - > $f; footclient emacsclient -nw $f; rm $f"] Control+Shift+g
When pressing ctrl+shift+g, the last command's output is written to a temporary file, then an emacsclient is started in a new footclient instance. The temporary file is removed after the footclient instance has closed.
For this to work, the shell must emit an OSC-133;C (\E]133;C\E\\) sequence before command output starts, and an OSC-133;D (\E]133;D\E\\) when the command output ends.
In fish, one way to do this is to add preexec and postexec hooks:
function foot_cmd_end --on-event fish_postexec
See the wiki (https://codeberg.org/dnkl/foot/wiki#user-content-piping-last-commands-output) for details, and examples for other shells
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/.
XTGETTCAP¶
XTGETTCAP is an escape sequence initially introduced by XTerm, and also implemented (and extended, to some degree) by Kitty.
It allows querying the terminal for terminfo classic, file-based, terminfo definition. For example, if all applications used this feature, you would no longer have to install foot's terminfo on remote hosts you SSH into.
XTerm's implementation (as of XTerm-370) only supports querying key (as in keyboard keys) capabilities, and three custom capabilities:
- TN - terminal name
- Co - number of colors (alias for the colors capability)
- RGB - number of bits per color channel (different semantics from the RGB capability in file-based terminfo definitions!).
Kitty has extended this, and also supports querying all integer and string capabilities.
Foot supports this, and extends it even further, to also include boolean capabilities. This means foot's entire terminfo can be queried via XTGETTCAP.
Note that both Kitty and foot handles responses to multi-capability queries slightly differently, compared to XTerm.
XTerm will send a single DCS reply, with ;-separated capability/value pairs. There are a couple of issues with this:
- The success/fail flag in the beginning of the response is always 1 (success), unless the very first queried capability is invalid.
- XTerm will not respond at all to an invalid capability, unless it's the first one in the XTGETTCAP query.
- XTerm will end the response at the first invalid capability.
In other words, if you send a large multi-capability query, you will only get responses up to, but not including, the first invalid capability. All subsequent capabilities will be dropped.
Kitty and foot on the other hand, send one DCS response for each capability in the multi query. This allows us to send a proper success/fail flag for each queried capability. Responses for all queried capabilities are always sent. No queries are ever dropped.
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).
ENVIRONMENT¶
Variables used by foot¶
SHELL
HOME
XDG_CONFIG_HOME
XDG_CONFIG_DIRS
XDG_RUNTIME_DIR
WAYLAND_DISPLAY
XCURSOR_THEME
XCURSOR_SIZE
Variables set in the child process¶
TERM
COLORTERM
PWD
SHELL
In addition to the variables listed above, custom environment variables may be defined in foot.ini(5).
Variables *unset* in the child process¶
TERM_PROGRAM TERM_PROGRAM_VERSION
In addition to the variables listed above, custom environment variables to unset may be defined in foot.ini(5).
BUGS¶
Please report bugs to https://codeberg.org/dnkl/foot/issues
Before you open a new issue, please search existing bug reports, both open and closed ones. Chances are someone else has already reported the same issue.
The report should contain the following:
- Foot version (foot --version).
- Log output from foot (run foot -d info from another terminal).
- Which Wayland compositor (and version) you are running.
- 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¶
2024-08-14 |