herbstluftwm

SYNOPSIS

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:

-c, --autostartPATH

use PATH as autostart file instead of the one in $XDG_CONFIG_HOME

-v, --version

print version and exit

-l, --locked

Initially set the monitors_locked setting to 1

--verbose

print verbose information to stderr

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 selects one of its two subtrees according to the each
character in the index.

The characters are interpreted 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

Thus an empty string refers to the root frame, and "00" refers to the first
subtree of the first subtree of the root frame.

As a special case, the string "@" always refers to the currently 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. -l denotes the monitor
left of the focused monitor, -r right of, -u above of, and -d below
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.

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 KEYCOMMAND [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 BUTTONACTION [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:

B1 or Button1

B2 or Button2

B3 or Button3

B4 or Button4

B5 or Button5

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 while client.dragged
links to the client on which the BUTTON has been performed.

While an ACTION is performed, client.dragged is the client which is
dragged. E.g.:

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 switch the
window manager in the running session without restarting the session. If no
or an invalid WINDOWMANAGER is given, then herbstluftwm is restarted. For
details see man 3 execvp. Example:

wmexec openbox

chain SEPARATOR [COMMANDS …]

chain expects a SEPARATOR and a list of COMMANDS with arguments. The
commands have to be separated by the specified SEPARATOR. The SEPARATOR
can by any word and only is recognized as the separator between commands if
it exactly matches SEPARATOR. "chain" outputs the appended outputs of all
commands and returns the exit code of the last executed command. Examples
are:

Create a tag called "foo" and directly use it:
chain , add foo , use foo

"silent" executes the provided command, but discards its output and only
returns its exit code.

focus_nth INDEX

Focuses the nth window in a frame. The first window has INDEX 0. If
INDEX is negative or greater than the last window index, then the last
window is focused.

cycle [DELTA]

Cycles the selection within the current frame by DELTA. If DELTA is
omitted, DELTA = 1 will be used. DELTA can be negative; DELTA = -1
means: cycle in the opposite direction by 1.

cycle_all [--skip-invisible] [DIRECTION]

Cycles through all windows and frames on the current tag. DIRECTION = 1
means forward, DIRECTION = -1 means backward, DIRECTION = 0 has no
effect. DIRECTION defaults to 1. If there are multiple windows within on
frame, then it acts similar to the cycle command. (The cycle_all command
focuses the next/previous leave in the layout tree.). If
--skip-invisible is given, then this only cycles through all visible
windows and skips invisible windows in the max layout. The focused window
is raised.

Cycles the layout algorithm in the current frame by DELTA. DELTA
defaults to 1. You can find a list of layout algorithms above. If a list of LAYOUTS is given, cycle_layout will cycle
through those instead of the default layout algorithm list. Each layout name
should occur at most once. Example:

Closes the specified window gracefully or the focused window if none is
given explicitly. See the section on WINDOW IDS how to
reference a certain window.

close_or_remove

Closes the focused window or removes the current frame if no window is
focused.

split ALIGN [FRACTION]

Splits the focused frame into two subframes with a specified FRACTION
between 0 and 1 which defaults to 0.5. ALIGN is one of

top

bottom (= vertical)

left,

right (= horizontal)

explode

auto (split along longest side)
It specifies which of the two halves will be empty
after the split. The other half will be occupied by the currently focused
frame. After splitting, the originally focuse frame will stay focused.
One special ALIGN mode is explode, which splits the frame in such a way
that the window sizes and positions are kept as much as possible. If no
FRACTION is given to explode mode an optimal fraction is picked
automatically. Example:

split explode

split bottom 0.5

split horiz 0.3

split vertical 0.5

split h

focus [-i|-e] DIRECTION

Moves the focus from current frame to the next frame or client in
DIRECTION which is in:

l[eft]

r[ight]

u[p]

d[own]

If -i (internal) is given or default_direction_external_only is unset,
then the next client in DIRECTION can also be within the same frame. If
there is no client within this frame or -e (external) is given, then the
next frame in specified DIRECTION will be focused.

The direction between frames is defined as follows: The focus is in a leaf
of the binary tree. Each inner node in the tree remembers the last focus
direction (child 0 or child 1). The algorithm uses the shortest possible way
from the leaf (the currently focused frame) to the root until it is possible
to change focus in the specified DIRECTION. From there the focus goes back
to the leaf.

Example: The focus is at frame A. After executing focus right focus will
be at frame C.

If the currently focused client is floated, then the next floating window in
the specified direction is focused and raised.

If focus_crosses_monitor_boundaries is set and no client or frame is found
in the specified DIRECTION, then the next monitor in that DIRECTION is
focused.

focus_edge [-i|-e] DIRECTION

Focuses the window on the edge of the tag in the specified DIRECTION. The
DIRECTIONS and -e behave as specified at the focus command.

If -i (internal) is given or default_direction_external_only is unset,
then the window on the edge of the tag will be focused. Else, only the frame
on the edge of the tag will be focused, and the window that was last focused
in that frame will be focused.

raise WINID

Raises the specified window. See the section on WINDOW IDS
on how to reference a certain window. Its result is only visible in floating
mode.

Tip

The WINID also can specify an unmanaged window, although the completion
for the raise command does not list the IDs of unmanaged windows.

jumpto WINID

Puts the focus to the specified window. See the section on WINDOW IDS on how to reference a certain window.

bring WINID

Moves the specified window to the current frame and focuses it. See the
section on WINDOW IDS on how to reference a certain window.

resize DIRECTIONFRACTIONDELTA

Changes the next fraction in specified DIRECTION by FRACTIONDELTA.
DIRECTION behaves as specified at the focus command. You should not omit
the sign - or +, because in future versions, the behaviour may change if
the sign is omitted. Example:

resize right +0.05

resize down -0.1

shift_edge [-i|-e] DIRECTION

Shifts the focused window to the the edge of a tag in the specified
DIRECTION. The DIRECTIONS behave as specified at the focus command and
-i and -e behave as specified at the focus_edge command.

shift [-i|-e] DIRECTION

Shifts the focused window to the next frame in the specified DIRECTION.
The DIRECTIONS and -i|-e behave as specified at the focus command.
If the focused client is floated instead of being tiled, then client is
shifted to the next window or screen edge.

shift_to_monitor MONITOR

Moves the focused window to the tag on the specified MONITOR.

remove

Removes focused frame and merges its windows to its neighbour frame.

rotate

Rotates the layout on the focused tag counterclockwise by 90 degrees. This
only manipulates the alignment of frames, not the content of them.

Toggles the setting NAME if it’s an integer setting: If its value is
unequal to 0, it becomes 0; else its previous value (which was unequal to 0)
is restored.

cycle_value NAMEVALUES …

Cycles value of the setting NAME through VALUES: I.e. it searches the
first occurrence of the current value in VALUES and changes the value to
the next in the list or to the first one if the end is reached or current
value wasn’t found. Example:

cycle_value frame_gap 0 5 10 15

cycle_value frame_bg_normal_color red green blue

cycle_monitor [DELTA]

Cycles monitor focused by DELTA. DELTA defaults to 1.

focus_monitor MONITOR

Puts focus to the specified monitor.

add TAG

Creates a new empty tag named TAG.

use TAG

Switches the focused monitor to specified TAG.

use_index INDEX [--skip-visible]

Switches the focused monitor to the TAG with the specified INDEX. If
INDEX starts with + or -, then INDEX is treated relative to the
current TAG. If --skip-visible is passed and INDEX is relative, then
tags that are already visible on a monitor are skipped. E.g. this cycles
backwards through the tags:

use_index -1 --skip-visible

use_previous

Switches the focused monitor to the previously viewed tag.

merge_tag TAG [TARGET]

Removes tag named TAG and moves all its windows to tag TARGET. If
TARGET is omitted, the focused tag will be used.

rename OLDTAGNEWTAG

Renames tag named OLDTAG to NEWTAG.

move TAG

Moves the focused window to the tag named TAG.

move_index INDEX [--skip-visible]

Moves the focused window to the tag specified by INDEX. Analogical to the
argument for use_index: If INDEX starts with + or -, then it is
treated relative. If --skip-visible is passed with a relative index, then
already visible tags are skipped.

lock_tag [MONITOR]

Lock the tag switching on the specified monitor. If no
argument is given, the currently focused monitor is used. When the
tag switching is disabled for a monitor, the commands use and
use_index have no effect when executed there. When
swap_monitors_to_get_tag is enabled, switching to a tag which
is located on a locked monitor, switches to that monitor instead of
stealing it from there. The lock state of a monitor is indicated
by "[LOCKED]" in the list_monitors output.

unlock_tag [MONITOR]

Re-enables the tag switching on the specified monitor. If no argument is
given, the currently focused monitor is used. This is the reverse operation
to lock_tag and has no further side effects but removing this lock.

disjoin_rects RECTS …

Takes a list of rectangles and splits them into smaller pieces until all
rectangles are disjoint, the result rectangles are printed line by line.
This command does not modify the current list of monitors! So this can be
useful in combination with the set_monitors command.

Sets the list of monitors to the available Xinerama monitors. If the
Xinerama extension is missing, it will fall back to one monitor across the
entire screen. If the detected monitors overlap, the will be split into more
monitors that are disjoint but cover the same area using disjoin_rects.
If -l or --list is passed, the list of rectangles of detected pyhsical
monitors is printed. So hc detect_monitors is equivalent to the bash
command hc set_monitors $(hc disjoin_rects $(hc detect_monitors -l)).

add_monitor RECT [TAG [NAME]]

Adds a monitor on the specified rectangle RECT and displays TAG on it.
TAG currently must not be displayed on any other monitor. RECT is a
string of the form WxH±X±Y. If no or an empty TAG is given, then any
free tag will be chosen. If a NAME is given, you can reference to this
monitor by its name instead of using an index. Example:

add_monitor 1024x768-20+0 mynewtag main

remove_monitor MONITOR

Removes the specified monitor.

move_monitor MONITORRECT [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]

Moves the specified monitor to rectangle RECT. RECT is defined as in
add_monitor. If no or an empty pad is given, it is not changed.

raise_monitor [MONITOR]

Raises the specified monitor or the current one if MONITOR is
omitted.

rename_monitor MONITORNAME

(Re)names an already existing monitor. If NAME is empty, it removes the
monitor’s name.

stack

Prints the stack of monitors with the visible tags and their layers as a
tree. The order of the printed stack is top to bottom. The style is
configured by the tree_style setting.

monitor_rect [[-p] MONITOR]

Prints the rectangle of the specified monitor in the format: X Y W H
If no MONITOR or cur is given, then the current monitor is used. If -p
is supplied, then the remaining rect without the pad around this monitor
is printed.

pad MONITOR [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]

Sets the pad of specified monitor to the specified padding. If no or an
empty padding is given, it is not changed.

list_padding [MONITOR]

Lists the padding of the specified monitor, or the currently focused monitor
if no monitor is given.

layout [TAG [INDEX]]

Prints the layout of frame with INDEX on TAG, in a nice tree style.
Its style is defined by the tree_style setting. If no TAG is given,
the current tag is used. If no INDEX is given, the root frame is used. To
specify INDEX without specifying TAG (i.e. use current tag), pass an
empty string as TAG.
An example output is:

Loads a given LAYOUT description to specified TAG or current tag if no
TAG is given.

Caution

LAYOUT is exactly one parameter. If you are calling it manually
from your shell or from a script, quote it properly!

complete POSITION [COMMANDARGS …]

Prints the result of tab completion for the partial COMMAND with optional
ARGS. You usually do not need this, because there is already tab
completion for bash. Example:

complete 0 m
prints all commands beginning with m

complete 1 toggle fra
prints all settings beginning with fra that can be toggled

complete_shell POSITION [COMMANDARGS …]

Behaves like complete with the following extras, useful for completion on
posix shells:

Escape sequences are removed in COMMAND and ARGS.

A space is appended to each full completion result.

Special characters will be escaped in the output.

emit_hook ARGS …

Emits a custom hook to all idling herbstclients.

tag_status [MONITOR]

Print a tab separated list of all tags for the specified MONITOR index. If
no MONITOR index is given, the focused monitor is used. Each tag name is
prefixed with one char, which indicates its state:

. the tag is empty

: the tag is not empty

+ the tag is viewed on the specified MONITOR, but this monitor is
not focused.

# the tag is viewed on the specified MONITOR and it is focused.

- the tag is viewed on a different MONITOR, but this monitor is
not focused.

% the tag is viewed on a different MONITOR and it is focused.

! the tag contains an urgent window

Warning

If you use a tab in one of the tag names, then tag_status is probably
quite useless for you.

floating [[TAG] on|off|toggle|status]

Changes the current tag to floating/tiling mode on specified TAG or prints
it current status. If no TAG is given, the current tag is used. If no
argument is given, floating mode is toggled. If status is given, then on
or off is printed, depending of the floating state of TAG.

rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE …]

Defines a rule which will be applied to all new clients. Its behaviour is
described in the RULES section.

unrule LABEL|--all|-F

Removes all rules named LABEL. If --all or -F is passed, then all rules
are removed.

fullscreen [on|off|toggle]

Sets or toggles the fullscreen state of the focused client. If no argument
is given, fullscreen mode is toggled.

pseudotile [on|off|toggle]

Sets or toggles the pseudotile state of the focused client. If a client is
pseudotiled, then in tiling mode the client is only moved but not resized -
the client size will stay the floating size. The only reason to resize the
client is to ensure that it fits into its tile. If no argument is given,
pseudotile mode is toggled.

object_tree [PATH]

Prints the tree of objects. If the object path PATH is given, only the
subtree starting at PATH is printed. See the OBJECTS section
for more details.

attr [PATH [NEWVALUE]

Prints the children and attributes of the given object addressed by PATH.
If PATH is an attribute, then print the attribute value. If NEWVALUE is
given, assign NEWVALUE to the attribute given by PATH. See the
OBJECTS section for more details.

get_attr ATTRIBUTE

Print the value of the specified ATTRIBUTE as described in the
OBJECTS section.

set_attr ATTRIBUTENEWVALUE

Assign NEWVALUE to the specified ATTRIBUTE as described in the
OBJECTS section.

new_attr [bool|color|int|string|uint] PATH

Creates a new attribute with the name and in the object specified by PATH.
Its type is specified by the first argument. The attribute name has to begin
with my_.

remove_attr PATH

Removes the user defined attribute PATH.

substitute IDENTIFIERATTRIBUTECOMMAND [ARGS …]

Replaces all exact occurrences of IDENTIFIER in COMMAND and its ARGS
by the value of the ATTRIBUTE. Note that the COMMAND also is replaced by
the attribute value if it equals IDENTIFIER. The replaced command with its
arguments then is executed. Example:

substitute MYTITLE clients.focus.title echo MYTITLE

Prints the title of the currently focused window.

sprintf IDENTIFIERFORMAT [ATTRIBUTES …] COMMAND [ARGS …]

Replaces all exact occurrences of IDENTIFIER in COMMAND and its ARGS
by the string specified by FORMAT. Each %s in FORMAT stands for the
value of the next attribute in ATTRIBUTES, similar to the printf(1)
command. The replaced command with its arguments then is executed.
Examples:

sprintf STR title=%s clients.focus.title echo STR

Prints the title of the currently focused window prepended by
title=.

sprintf X tag=%s tags.focus.name rule once X

Moves the next client that appears to the tag that is currently
focused.

sprintf X %s/%s tags.focus.index tags.count echo X

Tells which tag is focused and how many tags there are

sprintf l somelongstring echo l l l

Prints somelongstring three times, separated by spaces.

mktemp [bool|int|string|uint] IDENTIFIERCOMMAND [ARGS …]

Creates a temporary attribute with the given type and replaces all
occurrences of IDENTIFIER in COMMAND and ARGS by by the path of the
temporary attribute. The replaced command with its arguments is executed
then. The exit status of COMMAND is returned.

compare ATTRIBUTEOPERATORVALUE

Compares the value of ATTRIBUTE with VALUE using the comparation method
OPERATOR. If the comparation succeeds, it returns 0, else 1. The operators
are:

=: ATTRIBUTE's value equals VALUE

!=: ATTRIBUTE's value does not equal VALUE

le: ATTRIBUTE's value <= VALUE

lt: ATTRIBUTE's value < VALUE

ge: ATTRIBUTE's value >= VALUE

gt: ATTRIBUTE's value > VALUE

The OPERATORsle,lt,ge,gt can only be used if ATTRIBUTE is of
the type integer or unsigned integer. Note that the first parameter must
always be an attribute and the second a constant value. If you want to
compare two attributes, use the substitute command:

It returns success if there are more clients on the focused tag than frames.

getenv NAME

Gets the value of the environment variable NAME.

setenv NAMEVALUE

Set the value of the environment variable NAME to VALUE.

unsetenv NAME

Unsets the environment variable NAME.

SETTINGS

Settings configure the behaviour of herbstluftwm and can be controlled via the
set, get and toggle commands. There are two types of settings: Strings and
integer values. An integer value is set, if its value is 1 or another value
unequal to 0. An integer value is unset, if its value is 0.

frame_gap (Integer)

The gap between frames in the tiling mode.

frame_padding (Integer)

The padding within a frame in the tiling mode, i.e. the space between the
border of a frame and the windows within it.

window_gap (Integer)

The gap between windows within one frame in the tiling mode.

snap_distance (Integer)

If a client is dragged in floating mode, then it snaps to neighbour clients
if the distance between them is smaller then snap_distance.

snap_gap (Integer)

Specifies the remaining gap if a dragged client snaps to an edge in floating
mode. If snap_gap is set to 0, no gap will remain.

mouse_recenter_gap (Integer)

Specifies the gap around a monitor. If the monitor is selected and
the mouse position would be restored into this gap, it is set to
the center of the monitor. This is useful, when the monitor was
left via mouse movement, but is reselected by keyboard. If the gap
is 0 (default), the mouse is never recentered.

frame_border_active_color (String/Color)

The border color of a focused frame.

frame_border_normal_color (String/Color)

The border color of an unfocused frame.

frame_border_inner_color (String/Color)

The color of the inner border of a frame.

frame_bg_active_color (String/Color)

The fill color of a focused frame.

frame_bg_normal_color (String/Color)

The fill color of an unfocused frame (It is only visible if
always_show_frame is set).

frame_bg_transparent (Integer)

If set, the background of frames are transparent. That means a rectangle is
cut out frome the inner such that only the frame border and a stripe of
width frame_transparent_width can be seen. Use frame_active_opacity and
frame_normal_opacity for real transparency.

frame_transparent_width (Integer)

Specifies the width of the remaining frame colored with
frame_bg_active_color if frame_bg_transparent is set.

frame_border_width (Integer)

Border width of a frame.

frame_border_inner_width (Integer)

The width of the inner border of a frame. Must be less than
frame_border_width, since it does not add to the frame border width but is a
part of it.

focus_crosses_monitor_boundaries (Integer)

If set, the focus command crosses monitor boundaries. If there is no
client in the direction given to focus, then the monitor in the specified
direction is focused.

raise_on_focus (Integer)

If set, a window is raised if it is focused. The value of this setting is
only used in floating mode.

raise_on_focus_temporarily (Integer)

If set, a window is raised temporarily if it is focused on its tag.
Temporarily in this case means that the window will return to its previous
stacking position if another window is focused.

raise_on_click (Integer)

If set, a window is raised if it is clicked. The value of this setting is
only noticed in floating mode.

window_border_width (Integer)

Border width of a window.

window_border_inner_width (Integer)

The width of the inner border of a window. Must be less than
window_border_width, since it does not add to the window border width but is
a part of it.

window_border_active_color (String/Color)

Border color of a focused window.

window_border_normal_color (String/Color)

Border color of an unfocused window.

window_border_urgent_color (String/Color)

Border color of an unfocused but urgent window.

window_border_inner_color (String/Color)

Color of the inner border of a window.

always_show_frame (Integer)

If set, all frames are displayed. If unset, only frames with focus or with
windows in it are displayed.

Index of the frame layout, which is used if a new frame is created (by split
or on a new tag). For a list of valid indices and their meanings, check the
list of layout algorithms above.

default_direction_external_only (Integer)

This setting controls the behaviour of focus and shift if no -e or -i
argument is given. if set, then focus and shift changes the focused frame
even if there are other clients in this frame in the specified DIRECTION.
Else, a client within current frame is selected if it is in the specified
DIRECTION.

gapless_grid (Integer)

This setting affects the size of the last client in a frame that is arranged
by grid layout. If set, then the last client always fills the gap within
this frame. If unset, then the last client has the same size as all other
clients in this frame.

smart_frame_surroundings (Integer)

If set, frame borders and gaps will be removed when there’s no ambiguity
regarding the focused frame.

smart_window_surroundings (Integer)

If set, window borders and gaps will be removed and minimal when there’s no
ambiguity regarding the focused window. This minimal window decoration can
be configured by the theme.minimal object.

focus_follows_mouse (Integer)

If set and a window is focused by mouse cursor, this window is focused (this
feature is also known as sloppy focus). If unset, you need to click to
change the window focus by mouse.

If another window is hidden by the focus change (e.g. when having
pseudotiled windows in the max layout) then an extra click is required to
change the focus.

focus_stealing_prevention (Integer)

If set, only pagers and taskbars are allowed to change the focus. If unset,
all applications can request a focus change.

monitors_locked (Integer)

If greater than 0, then the clients on all monitors aren’t moved or resized
anymore. If it is set to 0, then the arranging of monitors is enabled again,
and all monitors are rearranged if their content has changed in the
meantime. You should not change this setting manually due to concurrency
issues; use the commands lock and unlock instead.

swap_monitors_to_get_tag (Integer)

If set: If you want to view a tag, that already is viewed on another
monitor, then the monitor contents will be swapped and you see the wanted
tag on the focused monitor. If not set, the other monitor is focused if it
shows the desired tag.

auto_detect_monitors (Integer)

If set, detect_monitors is automatically executed every time a monitor is
connected, disconnected or resized.

tree_style (String)

It contains the chars that are used to print a nice ascii tree. It must
contain at least 8 characters. e.g. X|:#+*-. produces a tree like:

It controls the value of the _NET_WM_NAME property on the root window,
which specifies the name of the running window manager. The value of this
setting is not updated if the actual _NET_WM_NAME property on the root
window is changed externally. Example usage:

cycle_value wmname herbstluftwm LG3D

pseudotile_center_threshold (Int)

If greater than 0, it specifies the least distance between a centered
pseudotile window and the border of the frame or tile it is assigned to. If
this distance is lower than pseudotile_center_threshold, it is aligned to
the top left of the client’s tile.

update_dragged_clients (Int)

If set, a client’s window content is resized immediately during resizing
it with the mouse. If unset, the client’s content is resized after the mouse
button are released.

RULES

Rules are used to change default properties for certain clients when they
appear. Each rule matches against a certain subset of all clients and defines a
set of properties for them (called CONSEQUENCEs). A rule can be defined
with this command:

rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE …]

Each rule consists of a list of FLAGs, CONDITIONs, CONSEQUENCEs
and, optionally, a LABEL. (each of them can be optionally prefixed with two
dashes (--) to provide a more iptables(8)-like feeling).

Each rule can be given a custom label by specifying the LABEL property:

[--]label=VALUE

If multiple labels are specified, the last one in the list will be applied. If
no label is given, then the rule will be given an integer name that represents
the index of the rule since the last unrule -F command (which is triggered in
the default autostart).

Tip

Rule labels default to an incremental index. These default labels are
unique, unless you assign a different rule a custom integer LABEL. Default
labels can be captured with the printlabel flag.

If a new client appears, herbstluftwm tries to apply each rule to this new
client as follows: If each CONDITION of this rule matches against this client,
then every CONSEQUENCE is executed. (If there are no conditions given, then
this rule is executed for each client)

Each CONDITION consists of a property name, an operator and a value. Valid
operators are:

~ matches if client’s property is matched by the regex value.

= matches if client’s properly string is equal to value.

Valid properties are:

instance

the first entry in client’s WM_CLASS.

class

the second entry in client’s WM_CLASS.

title

client’s window title.

pid

the client’s process id (Warning: the pid is not available for every client.
This only matches if the client sets _NET_WM_PID to the pid itself).

maxage

matches if the age of the rule measured in seconds does not exceed value.
This condition only can be used with the = operator. If maxage already is
exceeded (and never will match again), then this rule is removed. (With this
you can build rules that only live for a certain time.)

windowtype

matches the _NET_WM_WINDOW_TYPE property of a window.

windowrole

matches the WM_WINDOW_ROLE property of a window if it is set by the window.

Each CONSEQUENCE consists of a NAME=VALUE pair. Valid NAMES are:

tag

moves the client to tag VALUE.

monitor

moves the client to the tag on monitor VALUE. If the tag consequence was
also specified, and switchtag is set for the client, move the client to that
tag, then display that tag on monitor VALUE. If the tag consequence was
specified, but switchtag was not, ignore this consequence.

focus

decides whether the client gets the input focus on his tag. The default is
off. VALUE can be on, off or toggle.

switchtag

if focus is activated and the client is put to a not focused tag, then
switchtag tells whether the client’s tag will be shown or not. If the tag
is shown on any monitor but is not focused, the client’s tag only is brought
to the current monitor if swap_monitors_to_get_tag is activated. VALUE
can be on, off or toggle.

manage

decides whether the client will be managed or not. The default is on.
VALUE can be on, off or toggle.

index

moves the window to a specified index in the tree. VALUE is a
frame index.

pseudotile

sets the pseudotile state of the client. VALUE can be on, off or
toggle.

ewmhrequests

sets whether the window state (the fullscreen state and the demands
attention flag) can be changed by the application via ewmh itself. This does
not affect the initial fullscreen state requested by the window. VALUE can
be on, off or toggle, it defaults to on.

ewmhnotify

sets whether hlwm should let the client know about EMWH changes (currently
only the fullscreen state). If this is set, applications do not change to
their fullscreen-mode while still being fullscreen. VALUE can be on,
off or toggle, it defaults to on.

fullscreen

sets the fullscreen flag of the client. VALUE can be on, off or
toggle.

hook

emits the custom hook ruleVALUEWINID when this rule is triggered by
a new window with the id WINID. This consequence can be used multiple
times, which will cause a hook to be emitted for each occurrence of a hook
consequence.

keymask

Sets the keymask for an client. A keymask is an regular expression that is
matched against the string represenation (see list_keybinds). If it matches
the keybinding is active when this client is focused, otherwise it is
disabled. The default keymask is an empty string (""), which does not
disable any keybinding.

A rule’s behaviour can be configured by some special FLAGS:

not: negates the next CONDITION.

!: same as not.

once: only apply this rule once (and delete it afterwards).

printlabel: prints the label of the newly created rule to stdout.

prepend: prepend the rule to the list of rules instead of appending it.
So its consequences may be overwritten by already existing rules.

Examples:

rule --class=Netscape --tag=6 --focus=off

Moves all Netscape instances to tag 6, but doesn’t give focus to them.

rule not class~.*[Tt]erm tag=2

Moves all clients to tag 2, if their class does not end with term or
Term.

rule class=Thunderbird index=/0
Insert all Thunderbird instances in the tree that has no focus and there
in the first child.

rule --windowtype=_NET_WM_WINDOW_TYPE_DIALOG --focus=on
Sets focus to new dialogs which set their _NET_WM_WINDOW_TYPE correctly.

WINDOW IDS

Several commands accept a window as reference, e.g. close. The syntax is as
follows:

an empty string — or missing argument — references the currently focused
window.

urgent references some window that is urgent.

0xHEXID — where HEXID is some hexadecimal number — references the
window with hexadecimal X11 window id is HEXID.

DECID — where DECID is some decimal number — references the window
with the decimal X11 window id DECID.

OBJECTS

Warning

The object tree is not stable yet, i.e. its interface may change until
the next stable release. So check this documentation again after upgrading the
next time.

The object tree is a collection of objects with attributes similar to /sys
known from the Linux kernel. Many entities (like tags, monitors, clients, …)
have objects to access their attributes directly. The tree is printed by the
object_tree command and looks more or less as follows:

Setting an attribute of the theme object just propagates the value to the
respective attribute of the tiling and the floating object.

tiling configures the decoration of tiled clients, setting one of its
attributes propagates the respective attribute of the active, normal
and urgent child objects.

active configures the decoration of focused and tiled clients

normal configures the decoration of unfocused and tiled clients

urgent configures the decoration of urgent and tiled clients

floating behaves analogously to tiling

minimal behaves analogously to tiling and configures those minimal
decorations triggered by smart_window_surroundings.

active propagates the attribute values to tiling.active and
floating.active

normal propagates the attribute values to tiling.normal and
floating.normal

urgent propagates the attribute values to tiling.urgent and
floating.urgent

AUTOSTART FILE

There is no configuration file but an autostart file, which is executed on
startup. It is also executed on command reload. If not specified by the
--autostart argument, autostart file is located at
$XDG_CONFIG_HOME/herbstluftwm/autostart or at
~/.config/herbstluftwm/autostart. Normally it consists of a few herbstclient
calls. If executing the autostart file in a user’s home fails the global
autostart file (mostly placed at /etc/xdg/herbstluftwm/autostart) is executed as
a fallback.

For a quick install, copy the default autostart file to
~/.config/herbstluftwm/.

HOOKS

On special events, herbstluftwm emits some hooks (with parameters). You can
receive or wait for them with herbstclient(1). Also custom hooks can be
emitted with the emit_hook command. The following hooks are emitted by
herbstluftwm itself:

fullscreen [on|off] WINIDSTATE

The fullscreen state of window WINID was changed to [on|off].

tag_changed TAGMONITOR

The tag TAG was selected on MONITOR.

focus_changed WINIDTITLE

The window WINID was focused. Its window title is TITLE.

window_title_changed WINIDTITLE

The title of the focused window was changed. Its window id is WINID and
its new title is TITLE.

tag_flags

The flags (i.e. urgent or filled state) have been changed.

tag_added TAG

A tag named TAG was added.

tag_removed TAG

The tag named TAG was removed.

urgent [on|off] WINID

The urgent state of client with given WINID has been changed to [on|off].

rule NAMEWINID

A window with the id WINID appeared which triggerd a rule with the
consequence hook=NAME.

There are also other useful hooks, which never will be emitted by herbstluftwm
itself, but which can be emitted with the emit_hook command:

quit_panel

Tells a panel to quit. The default panel.sh quits on this hook. Many
scripts are using this hook.

reload

Tells all daemons that the autostart file is reloaded — and tells them
to quit. This hook should be emitted in the first line of every autostart
file.

STACKING

Every tag has its own stack of clients that are on this tag. Similar to the EWMH
specification each tag stack contains several layers, which are from top to
bottom:

the focused client (if raise_on_focus_temporarily is enabled)

clients in fullscreen

normal clients

frame decorations

All monitors are managed in one large stack which only consists of the stacks of
the visible tags put above each other. The stacking order of these monitors is
independent from their indices and can be modified using the raise_monitor
command. The current stack is illustrated by the stack command.

ENVIRONMENT VARIABLES

DISPLAY

Specifies the DISPLAY to use.

EXIT STATUS

Returns 0 on success. Returns EXIT_FAILURE if it cannot startup or if
wmexec fails.

BUGS

See the herbstluftwm distribution BUGS file.

COMMUNITY

Feel free to join the IRC channel #herbstluftwm on irc.freenode.net.

AUTHOR

herbstluftwm was written by Thorsten Wißmann. All contributors are listed in
the herbstluftwm distribution AUTHORS file.