SYNOPSIS
herbstluftwm [OPTION …]
DESCRIPTION
Starts the herbstluftwm window manager on DISPLAY. It also listens for calls from herbstclient(1) and executes them. The list of available COMMANDS is listed below.
OPTION can be:
- -v, --version
-
print version and exit
- -h, --help
-
print a short help and exit
- -c, --autostart PATH
-
use PATH as autostart file instead of the one in $XDG_CONFIG_HOME
- -l, --locked
-
Initially set the monitors_locked setting to 1
- --exit-on-xerror
-
Make herbstluftwm exit whenever xlib reports an error. This may only be activated for automated testing and never for actual sessions.
- --no-tag-import
-
Do not preserve the tags (virtual desktops) from a previous running window manager.
- --verbose
-
print verbose information to stderr. This can be switched at run-time by the verbose setting.
This manual documents the scripting and configuration interface. For a more verbose introduction see herbstluftwm-tutorial(7).
TILING ALGORITHM
The basic tiling concept is that the layout is represented by a binary tree. On startup you see one big frame across the entire screen. A frame fulfills exactly one of the following conditions:
-
Frame contains windows:
It shows some clients and arranges them. The current layout algorithms are:-
0: vertical - clients are placed below each other
-
1: horizontal - clients are placed next to each other
-
2: max - all clients are maximized in this frame
-
3: grid - clients are arranged in an almost quadratic grid
-
-
Frame is split into subframes:
It is split into exactly two subframes in a configurable fraction either in a vertical or horizontal way. So it produces two frames which fulfill the same conditions (new frames always are about to contain windows). If you split a frame that already contains windows, the windows are inherited by the first new child frame.
If a new window appears, it is put in the currently focused frame. Only the leaves of the frame tree can be focused.
A frame can be removed, it is then merged with its neighbour frame. Due to the layout structure of a binary tree, each frame (i.e. node in binary tree) has exactly one neighbour.
The analogy to a binary tree is explained the best way with a small example: On startup you have a simple binary tree, with one frame that can contain clients:
C
When splitting it (e.g. with the command split vertical 0.5) you will get this:
V
/ \
C C
You also can split the left frame horizontally and you will get:
V
/ \
H C
/ \
C C
If you change the focus to the client on the right and remove this frame, it will be merged with the left subtree and you will get:
H
/ \
C C
The layout command prints the current layout of all tags as a tree.
FRAME INDEX
The exact position of a frame in the layout tree may be described by its index which is just a string of characters. The lookup algorithm starts at the root frame and interprets the index string character by character as follows:
-
0: select the first subtree -
1: select the second subtree -
.: select the subtree having the focus -
/: select the subtree not having the focus -
@: select the frame having the focus. In contrast to., this passes multiple layers all down to the focused leaf of the frame tree. -
p: select the parent tree -
e: finds a suitable empty frame: if the focused frame is not empty, this selects the closest frame that is empty (in any subtree)
For example:
-
An empty string refers to the root frame
-
00refers to the first subtree of the first subtree of the root frame. -
1erefers to the first empty frame in the second subtree. -
/@refers to the focused frame within the unfocused "half" of the frame tree -
@p/refers to the sibling of the focused frame
TAGS
Tags are very similar to workspaces, virtual desktops or window groups. Each tag has one layout. There is a list of tags. You can add or remove tags dynamically.
MONITORS
Monitors in herbstluftwm are totally independent of the actual physical screens. This means you can for example split your screen in two virtual monitors to view two tags at once on a big screen.
Each monitor displays exactly one tag on a specified rectangle on the screen.
Each monitor may have a name, which can be set via add_monitor and
rename_monitor. It can be unset with the rename_monitor command. A monitor
name is an arbitrary non-empty string which must not start with +, - or any
digit.
A monitor can be referenced in different ways:
-
by its absolute index as listed in the list_monitors command.
-
by its relative index: a
+or-followed by a delta, e.g.: +3 -
by its relative position to the focused monitor.
-ldenotes the monitor left of the focused monitor,-rright of,-uabove of, and-dbelow of, respectively. -
by "" (an empty string) which represents the current monitor.
-
by its name.
COMMANDS
herbstluftwm is controlled by internal commands, which can be executed via herbstclient(1) or via keybindings.
- quit
-
Quits herbstluftwm.
- reload
-
Executes the autostart file.
- version
-
Prints the version of the running herbstluftwm instance.
- echo [ARGS …]
-
Prints all given ARGS separated by a single space and a newline afterwards.
- true
-
Ignores all arguments and always returns success, i.e. 0.
- false
-
Ignores all arguments and always returns failure, i.e. 1.
- help [OBJECT|ATTRIBUTE]
-
Print help on a given object or attribute.
- list_commands
-
Lists all available commands.
- list_monitors
-
List currently configured monitors with their index, area (as rectangle), name (if named) and currently viewed tag.
- list_rules
-
Lists all active rules. Each line consists of all the parameters the rule was called with, plus its label, separated by tabs.
- list_keybinds
-
Lists all bound keys with their associated command. Each line consists of one key combination and the command with its parameters separated by tabs.
|
Warning
|
Tabs within command parameters are not escaped! |
- lock
-
Increases the monitors_locked setting. Use this if you want to do multiple window actions at once (i.e. without repainting between the single steps). See also: unlock
- unlock
-
Decreases the monitors_locked setting. If monitors_locked is changed to 0, then all monitors are repainted again. See also: lock
- keybind KEY COMMAND [ARGS …]
-
Adds a key binding. When KEY is pressed, the internal COMMAND (with its ARGS) is executed. A key binding is a (possibly empty) list of modifiers (Mod1, Mod2, Mod3, Mod4, Mod5, Alt, Super, Control/Ctrl, Shift) and one key (see keysymdef.h for a list of keys). Modifiers and the key are concatenated with - or + as separator. If there is already a binding for this KEY, it will be overwritten. Examples:
-
keybind Mod4+Ctrl+q quit
-
keybind Mod1-i toggle always_show_frame
-
keybind Mod1-Shift-space cycle_layout -1
-
- keyunbind KEY|-F|--all
-
Removes the key binding for KEY. The syntax for KEY is defined in keybind. If -F or --all is given, then all key bindings will be removed.
- mousebind BUTTON ACTION [COMMAND …]
-
Adds a mouse binding for the floating mode. When BUTTON is pressed, the specified ACTION will be performed. BUTTON has a similar syntax to the KEY argument of keybind: It consists of a list of modifiers (separated by - or +, valid modifiers are listed in the description of keybind) and exactly one button name:
-
B1orButton1 -
B2orButton2 -
B3orButton3 -
B4orButton4 -
B5orButton5
-
-
ACTION must be one of the following actions:
-
move: Moves the window by dragging the cursor. -
resize: Resizes the window by dragging a corner. -
zoom: Resizes the window into all four directions while keeping the center of the window constant. -
call: Only calls the specified COMMAND whileclient.draggedlinks to the client on which the BUTTON has been performed.
-
-
While an ACTION is performed,
client.draggedis the client which is dragged. E.g.:-
mousebind Mod1-Button3 zoom -
mousebind Mod1-B4 call substitute WID clients.dragged.winid spawn transset-df --inc -i WID 0.05 -
mousebind Mod1-B5 call substitute WID clients.dragged.winid spawn transset-df --dec -i WID -m 0.2 0.05
-
- drag WINID ACTION
-
Starts dragging the specified client window WINID with the specified ACTION (see mousebind). E.g.
drag '' resizestarts resizing the focused window. - mouseunbind
-
Removes all mouse bindings.
- spawn EXECUTABLE [ARGS …]
-
Spawns an EXECUTABLE with its ARGS. For details see man 3 execvp. Example:
-
spawn xterm -e man 3 execvp
-
- wmexec [WINDOWMANAGER [ARGS …]]
-
Executes the WINDOWMANAGER with its ARGS. This is useful to k">
> mousebind < BUT NOT with its
witul> e man 3 execvp
-u above of,wmexec [WINDOWMAute WID c>