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:

-c, --autostart PATH

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

-v, --version

print version and exit

--verbose

print verbose information to stderr

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:

  1. Frame contains windows:
    It shows some clients and arranges them next to each other. The current layout algorithms are:

    • Vertical (frame_layout = 0)

    • Horizontal (frame_layout = 1)

  2. 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 a new window appears, it is put in the currently focused frame. Only frames that have the type "contains windows" can be focused.

A frame can be removed, so it is 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 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.

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.

There is also a list of monitors. Each monitor displays exactly one tag on a specified rectangle on the screen.

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.

list_commands

lists all available commands.

list_monitors

list currently configured monitors with their index, area (as rectangle) and currently viewed tag.

keybind KEY COMMAND [ARGS …]

adds a key binding. When KEY is pressed, the internal COMMAND (with its ARGS) is executed. A Keybinding is a (possibly empty) list of modifiers (Mod4, Mod1, Alt, Super, 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

removes the key binding for KEY. Syntax for KEY is defined in keybind.

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 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

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 [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)

cycle_layout [DELTA]

cycles the layout algorithm in the current frame by DELTA. DELTA defaults to 1. Currently only 1 is useful because there are only two algorithms so far:

  • vertical (below each other)

  • horizontal (next to each other)

  • max (only show selected client in entire frame)

close

closes the focused window.

split ALIGN FACTION

splits the focused frame into two subframes with a specified FRACTION between 0 and 1. ALIGN can be horizontal or vertical (actually it only depends on the first letter of ALIGN). Example:

  • split horiz 0.3

  • split vertical 0.5

  • split h 0.8

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 is going as short as possible 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.

Tree:  V,0     Screen: .-----..-----. (before)
       / \             |  B  ||  C  |
      /   \            '-----''-----'
    H,1   H,0          .-----..-----.
    / \   / \          |  A* ||  D  |
   A*  B C   D         '-----''-----'
Tree:  V,0     Screen: .-----..-----. (after focus right)
       / \             |  B  ||  C* |
      /   \            '-----''-----'
    H,1   H,0          .-----..-----.
    / \   / \          |  A  ||  D  |
   A   B C*  D         '-----''-----'
raise [0xWINID]

raises the specified window, which is specified by hexadecimal 0xWINID. If no 0xWINID is given, the focused window will be raised. Its result is only visible in floating mode.

resize DIRECTION FRACTIONDELTA

changes the next fraction in specified DIRECTION by FRACTIONDELTA. DIRECTION is 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 [-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 focus_follows_shift is set, then focus stays in the window; otherwise it stays in the frame.

remove

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

set NAME VALUE

sets the specified setting NAME to VALUE. All SETTINGS are listed in the section below.

get NAME

prints the value of setting NAME. All SETTINGS are listed in the section below.

toggle NAME

toggles the setting NAME if it’s an integer setting: if value was 0, it becomes 1, else value becomes 0.

cycle_monitor [DELTA]

cycles monitor focused by DELTA. DELTA defaults to 1.

focus_monitor INDEX

puts focus to monitor with specified INDEX (as specified by the list_monitors command)

add TAG

creates a new empty tag named TAG.

use TAG

switches focused monitor to specified 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 OLDTAG NEWTAG

renames tag named OLDTAG to NEWTAG.

move TAG

moves the focused window to tag named TAG.

add_monitor RECT TAG [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]

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. The padding specifies extra space around the monitor for some statusbars/panels. If no or an empty padding is given, it is set to 0. Example:

  • add_monitor 1024x768-20+0 mynewtag 16

remove_monitor INDEX

removes the monitor with specified INDEX. Its INDEX can be found out via the list_monitors command.

move_monitor INDEX RECT [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]

moves the monitor with specified INDEX to rectangle RECT. INDEX and RECT are defined as in remove_monitor and add_monitor. If no or an empty pad is given, it is not changed.

pad INDEX [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]

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

layout [TAG]

prints the layout of TAG in a nice tree style. Its style is defined by the tree_style setting. If no TAG is given, current tag is used.
An example output is:

╾─┐horizontal 50% selection=1
  ├╼ vertical: 0xe00009
  └─┐vertical 50% selection=0
    ├╼ vertical: 0xa00009 [FOCUS]
    └╼ vertical: 0x1000009
dump [TAG]

prints the same information as the layout command but in a machine readable format. Its output can be read back with the load command.
An example output (formatted afterwards) is:

(split horizontal:0.500000:1
    (clients vertical:0 0xe00009)
    (splitvertical:0.500000:1
        (clients vertical:0 0xa00009)
        (clients vertical:0 0x1000009)))
load [TAG] LAYOUT

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 [COMMAND ARGS …]

prints the result of tab completion in partial written 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

emit_hook ARGS …

emits specified hook to all idling herbstclients.

tag_status [MONITOR]

print a tab separated list of all tags for 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 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, 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 on TAG.

SETTINGS

Settings configure the behaviour of herbstluftwm and can be controlled via the set, get and toggle command. 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.

window_gap (Integer)

the gap between frames 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 remainig gap if a dragged client snaps to an edge in floating mode. If snap_gap is set to 0, no gap will remain.

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_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, frames have transparent backgrounds.

frame_border_width (Integer)

border width of a frame

raise_on_focus (Integer)

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

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_active_color (String/Color)

border color of a focused window

window_border_normal_color (String/Color)

border color of an unfocused window

always_show_frame (Integer)

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

default_frame_layout (Integer)

sets the frame layout, if a new frame is created (by split or on a new tag).

  • 0 means vertical

  • 1 means horizontal

  • 2 means max

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.

focus_follows_shift (Integer)

If set, focus stays in the window, if window is shifted to another frame. If unset, focus stays in the frame.

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.

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, nothing will be swapped.

ignore_class (String/Regex)

If the class property of a new created window matches the ignore_class regex, then it will not be managed, i.e. will not be put in the layout or on tags. Example value: ^(Xfce4-notifyd|Conky)$

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:

X-.root
  #-.child 0
  | #* child 01
  | +* child 02
  +-.child 1
  : #* child 10
  : +* child 01

Useful values for tree_style are: ╾│ ├└╼─┐ or ╾│ ├╰╼─╮.

AUTOSTART FILE

There is no config 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.

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

HOOKS

On special events, herbstluftwm emits some hooks (with parameters). You can recieve 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:

tag_changed TAG MONITOR

the tag TAG was selected on MONITOR.

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].

ENVIRONTMENT VARIABLES

DISPLAY

specifies the DISPLAY to use.

EXIT STATUS

Always returns 0.

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.

RESOURCES

COPYING

Copyright 2011 Thorsten Wißmann. All rights reserved.

This software is licensed under the "Simplified BSD License". See LICENSE for details