path: root/doc/herbstluftwm.txt

herbstluftwm(1)
===============
:doctype: manpage
:man version: {herbstluftwmversion}


NAME
----
herbstluftwm - a manual tiling window manager for X


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,*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
    *-l*, *--locked*::
        set the monitors_locked setting initially to 1
    *--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:

[[LIST_LAYOUT_ALGORITHMS]]
    . 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,
        then 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, 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.

[[FRAME_INDEX]]
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 that has the focus
    * +/+: select the subtree that has not 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
--------
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 "" (an empty string) which represents the current monitor.
    * by its name.


[[COMMANDS]]
COMMANDS
--------
// TODO examples in fixed font in html output
*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.

list_commands::
    Lists all available commands.

[[list_monitors]]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 it's id, 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'. Syntax for 'KEY' is defined in *keybind*.
    If *-F* or *--all* is given, then all key bindings will be removed.

mousebind 'BUTTON' 'ACTION'::
    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 the bottom right corner
        * +zoom+: Resizes the window into all four directions by keeping the
          center of the window constant.
 ::
    E.g.: +mousebind Mod1-Button3 zoom+

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 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
      * Rotate the layout clockwise: +
        chain .-. lock .-. rotate .-. rotate .-. rotate .-. unlock

 ::
    Counterexamples are:

      * This will only create a tag called "foo,": +
        chain , add foo, use foo
      * Separator "." defined, but "," is used: +
        chain . add foo , use foo

and 'SEPARATOR' ['COMMANDS' ...]::
    "and" behaves like the chain command but only executes the specified
    'COMMANDS' while the commands return the exit code 0.

or 'SEPARATOR' ['COMMANDS' ...]::
    "or" behaves like the chain command but only executes the specified
    'COMMANDS' until one command returns the exit code 0.

! 'COMMAND'::
    "!" executes the provided command, but inverts its return value. If the
    provided command returns a nonzero, "!" returns a 0, if the command returns
    a zero, "!" returns a 1.

focus_nth 'INDEX'::
    Focuses 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.

cycle_layout ['DELTA' ['LAYOUTS' ...]]::
    Cycles the layout algorithm in the current frame by 'DELTA'. 'DELTA'
    defaults to 1. You can find a <<LIST_LAYOUT_ALGORITHMS,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:

      * cycle_layout -1
      * cycle_layout 1 vertical grid

set_layout 'LAYOUT'::
    Sets the layout algorithm in the current frame to 'LAYOUT'.  For the list of
    layouts, check the <<LIST_LAYOUT_ALGORITHMS,list of layout algorithms
    above>>.

close::
    Closes the focused 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. '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]

// small hack to fix indentation of "If ..."
 ::
    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         '-----''-----'
----

focus_edge ['-i'|'-e'] 'DIRECTION'::
    Focuses the window on the edge of the tag in the specified 'DIRECTION'. The
    'DIRECTIONS' and 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 [urgent|'0xWINID']::
    Raises the specified window, which is an arbitrary urgent window or
    specified by the hexadecimal '0xWINID'. If no or an empty argument is given,
    the focused window will be raised. 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 urgent|'0xWINID'::
    Puts the focus to the specified window, which is an arbitrary urgent window
    or specified by the hexadecimal '0xWINID'.

bring urgent|'0xWINID'::
    Moves the specified window to the current frame and focuses it. The window
    is an arbitrary urgent window or specified by the hexadecimal '0xWINID'.

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

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.

set 'NAME' 'VALUE'::
    Sets the specified setting 'NAME' to 'VALUE'. All <<SETTINGS,*SETTINGS*>>
    are listed in the <<SETTINGS, section below>>.

get 'NAME'::
    Prints the value of setting 'NAME'. All <<SETTINGS,*SETTINGS*>>
    are listed in the <<SETTINGS, section below>>.

toggle 'NAME'::
    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 'NAME' 'VALUES' ...::
    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 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 'OLDTAG' 'NEWTAG'::
    Renames tag named 'OLDTAG' to 'NEWTAG'.

move 'TAG'::
    Moves the focused window to 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 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.

        * E.g. +disjoin_rects 600x400+0+0 600x400+300+250+ prints this:
+
----
300x150+300+250
600x250+0+0
300x150+0+250
300x150+600+250
600x250+300+400
----
+
        * In the above example two monitors are split into 5 monitors, which
          graphically means:
+
----
11111111                 11111111
1  222222222             333222224444
1  2   1   2   disjoin   3 32   24  4
11121111   2  -------->  333222224444
   2       2                555555555
   222222222                555555555
----

set_monitors 'RECTS' ...::
    Sets the list of monitors *exactly* to the list of given rectangles:

        * The i'th existing monitor is moved to the i'th given 'RECT'
        * New monitors are created if there are more 'RECTS' then monitors
        * Existing monitors are deleted if there are more monitors then 'RECTS'

detect_monitors::
    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.

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 'MONITOR' 'RECT' ['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 'MONITOR' 'NAME'::
    (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 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' in 'TAG', in a nice tree style.
    Its style is defined by the 'tree_style' setting. If no 'TAG' is given,
    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:
+
----
╾─┐ horizontal 50% selection=1
  ├─╼ vertical: 0xe00009
  └─┐ vertical 50% selection=0
    ├─╼ vertical: 0xa00009 [FOCUS]
    └─╼ vertical: 0x1000009
----

dump ['TAG' ['INDEX']]::
    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

complete_shell 'POSITION' ['COMMAND' 'ARGS ...']::
    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.
        * The 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 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, 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'.

rule [\[--]'FLAG'|\[--]'ID'|\[--]'CONDITION'|\[--]'CONSEQUENCE' ...]::
    Defines a rule which will be applied to all new clients. Its behaviour is
    described in the <<RULES,*RULES section*>>.

unrule 'ID'|*--all*|*-F*::
    Removes all rules named 'ID'. 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.

getenv 'NAME'::
    Gets the value of the environment variable 'NAME'.

setenv 'NAME' 'VALUE'::
    Set the value of the environment variable 'NAME' to 'VALUE'.

unsetenv 'NAME'::
    Unsets the environment variable 'NAME'.

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

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, frames have transparent backgrounds. *Warning:* Results in ugly
    artifacts when used together with a compositing manager. Use
    'frame_active_opacity' and 'frame_normal_opacity' in this case.

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.

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

frame_active_opacity (Integer)::
    Focused frame opacity in percent. Requires a running compositing manager to
    take actual effect.

frame_normal_opacity (Integer)::
    Unfocused frame opacity in percent. Requires a running compositing manager
    to take actual effect.

default_frame_layout (Integer)::
    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_LAYOUT_ALGORITHMS,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 when there's no ambiguity
    regarding the focused window.

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

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:
+
----
X-.root
  #-. child 0
  | #-* child 01
  | +-* child 02
  +-. child 1
  : #-* child 10
  : +-* child 01
----
+
Useful values for 'tree_style' are: +╾│ ├└╼─┐+ or +-| |'--.+ or +╾│ ├╰╼─╮+.

wmname (String)::
    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

[[RULES]]
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 'CONSEQUENCE'##s##). A rule can be defined
with this command:

+rule+ [\[--]'FLAG'|\[--]'ID'|\[--]'CONDITION'|\[--]'CONSEQUENCE' ...]

Each rule consists of a list of 'FLAG'##s##, 'CONDITION'##s## 'CONSEQUENCE'##s##
and, optionally, an 'ID'. (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 identifier by specifying the 'ID' property:

    * +[--]id+='VALUE'

If multiple id properties are specified, the last one in the list will be
applied. If no ID is given, then the rule will be given an integer name that
represents the index of the rule since the last 'unrule -F' or 'reload' command.

TIP: Rule ID's default to an incremental index. These default IDs should be
unique, unless you assign a different rule a custom integer ID. Defaulted IDs
can be captured with the 'printid' flag.

WARNING: The interface for rule ids may change before the next stable release,
so check the docs after updating the next time.

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 the pid to the _NET_WM_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'.

+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,*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 +rule+ 'VALUE' 'WINID' 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.

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).
    * +printid+: prints the id of the newly created rule to stdout.

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.

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] 'WINID' 'STATE'::
    The fullscreen state of window 'WINID' was changed to [on|off].

tag_changed 'TAG' 'MONITOR'::
    The tag 'TAG' was selected on 'MONITOR'.

focus_changed 'WINID' 'TITLE'::
    The window 'WINID' was focused. Its window title is 'TITLE'.

window_title_changed 'WINID' 'TITLE'::
    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 'NAME' 'WINID'::
    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]]
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 contain:

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

RESOURCES
---------
Gitweb: <http://git.cs.fau.de/?p=re06huxa/herbstluftwm>

Homepage: <http://git.cs.fau.de/~re06huxa/herbstluftwm>

Patch submission and bug reporting:

    herbstluftwm-devel@lists.sourceforge.net

COPYING
-------
Copyright 2011-2013 Thorsten Wißmann. All rights reserved.

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

// vim: tw=80 ft=asciidoc