BSPWM(1)

NAME
bspwm - Binary space partitioning window manager

SYNOPSIS

bspwm [-h|-v|-c CONFIG_PATH]

bspc DOMAIN [SELECTOR] COMMANDS

DESCRIPTION

bspwm is a tiling window manager that represents windows as the leaves of a full binary tree.

It is controlled and configured via bspc.

OPTIONS

-h
    Print the synopsis and exit.

-v
    Print the version and exit.

-c CONFIG_PATH
    Use the given configuration file.

COMMON DEFINITIONS

    DIR         := north | west | south | east
    CYCLE_DIR   := next | prev

SELECTORS

Selectors are used to select a target node, desktop, or monitor. A selector can either describe the target relatively or name it globally.

Selectors consist of a descriptor and any number of non-conflicting modifiers as follows:

    DESCRIPTOR(.MODIFIER)*

An exclamation mark can be prepended to certain modifiers in order to reverse their meaning.

  Node

Select a node.

    NODE_SEL := (<node_id>|PATH|DIR|CYCLE_DIR|last|older|newer|biggest|focused)[.[!]focused][.[!]automatic][.[!]local][.[!]leaf][.[!]STATE][.[!]FLAG][.[!]LAYER][.[!]same_class]
    STATE := tiled|pseudo_tiled|floating|fullscreen
    FLAG := urgent|sticky|private|locked
    LAYER := below|normal|above
    PATH := @[DESKTOP_SEL:][[/]JUMP](/JUMP)*
    JUMP := first|1|second|2|brother|parent|DIR

Descriptors

    <node_id>
        Selects the node with the given ID.

    PATH
        Selects the node at the given path.

    DIR
        Selects the window in the given (spacial) direction relative to the active node.

    CYCLE_DIR
        Selects the window in the given (cyclic) direction.

    biggest
        Selects the biggest window on the current desktop.

    last
        Selects the previously focused node.

    focused
        Selects the currently focused node.

    older
        Selects the node older than the focused node in the history.

    newer
        Selects the node newer than the focused node in the history.

Path Jumps

    The initial node is the focused node (or the root if the path starts with /) of the focused desktop (or the selected desktop if the path has a DESKTOP_SEL prefix).

    1|first
        Jumps to the first child.

    2|second
        Jumps to the second child.

    brother
        Jumps to the brother node.

    parent
        Jumps to the parent node.

    DIR
        Jumps to the node holding the edge in the given direction.

Modifiers

    [!]focused
        Only consider focused or unfocused nodes.

    [!]automatic
        Only consider nodes in automatic or manual insertion mode.

    [!]local
        Only consider nodes in or not in the current desktop.

    [!]leaf
        Only consider leaves or internal nodes.

    [!](tiled|pseudo_tiled|floating|fullscreen)
        Only consider windows in or not in the given state.

    [!]same_class
        Only consider windows that have or don’t have the same class as the current window.

    [!](private|urgent|sticky|locked)
        Only consider windows that have or don’t have the given flag set.

    [!](below|normal|above)
        Only consider windows in or not in the given layer.

  Desktop

Select a desktop.

    DESKTOP_SEL := (<desktop_name>|[MONITOR_SEL:](focused|^<n>)CYCLE_DIR|last|older|newer)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]

Descriptors

    <desktop_name>
        Selects the desktop with the given name.

    ^<n>
        Selects the nth desktop.

    CYCLE_DIR
        Selects the desktop in the given direction relative to the active desktop.

    last
        Selects the previously focused desktop.

    focused
        Selects the currently focused desktop.

    older
        Selects the desktop older than the focused desktop in the history.

    newer
        Selects the desktop newer than the focused desktop in the history.

Modifiers

    [!]occupied
        Only consider occupied or free desktops.

    [!]focused
        Only consider focused or unfocused desktops.

    [!]urgent
        Only consider urgent or non urgent desktops.

    [!]local
        Only consider inside or outside of the current monitor.

  Monitor

Select a monitor.

    MONITOR_SEL := (<monitor_name>|^<n>|DIR|CYCLE_DIR|last|primary|focused|older|newer)[.[!]occupied][.[!]focused]

Descriptors

    <monitor_name>
        Selects the monitor with the given name.

    ^<n>
        Selects the nth monitor.

    DIR
        Selects the monitor in the given (spacial) direction relative to the active monitor.

    CYCLE_DIR
        Selects the monitor in the given (cyclic) direction relative to the active monitor.

    primary
        Selects the primary monitor.

    last
        Selects the previously focused monitor.

    focused
        Selects the currently focused monitor.

    older
        Selects the monitor older than the focused monitor in the history.

    newer
        Selects the monitor newer than the focused monitor in the history.

Modifiers

    [!]occupied
        Only consider monitors where the focused desktop is occupied or free.

    [!]focused
        Only consider focused or unfocused monitors.

WINDOW STATES

tiled
    Its size and position are determined by the splitting type and ratio of each node of its path in the window tree.

pseudo_tiled
    Has an unrestricted size while being centered in its tiling space.

floating
    Can be moved/resized freely. Although it doesn’t occupy any tiling space, it is still part of the window tree.

fullscreen
    Fills its monitor rectangle and has no borders. It is send in the ABOVE layer by default.

NODE FLAGS

locked
    Ignores the node --close message.

sticky
    Stays in the focused desktop of its monitor.

private
    Tries to keep the same tiling position/size.

urgent
    Has its urgency hint set. This flag is set externally.

STACKING LAYERS

There’s three stacking layers: BELOW, NORMAL and ABOVE.

In each layer, the window are orderered as follow: tiled & pseudo-tiled < fullscreen < floating.

DOMAINS

  Node

General Syntax

    node [NODE_SEL] COMMANDS

Commands

    -f, --focus [NODE_SEL]
        Focus the selected or given node.

    -a, --activate [NODE_SEL]
        Activate the selected or given node.

    -d, --to-desktop DESKTOP_SEL
        Send the selected node to the given desktop.

    -m, --to-monitor MONITOR_SEL
        Send the selected node to the given monitor.

    -n, --to-node NODE_SEL
        Transplant the selected node to the given node.

    -s, --swap NODE_SEL
        Swap the selected node with the given node.

    -p, --presel-dir [~]DIR|cancel
        Preselect the splitting area of the selected node (or cancel the preselection). If ~ is prepended to DIR and the current preselection direction matches DIR, then the argument is interpreted as cancel.

    -o, --presel-ratio RATIO
        Set the splitting ratio of the preselection area.

    -r, --ratio RATIO|(+|-)PIXELS
        Set the splitting ratio of the selected node (0 < RATIO < 1).

    -R, --rotate 90|270|180
        Rotate the tree rooted at the selected node.

    -F, --flip horizontal|vertical
        Flip the the tree rooted at selected node.

    -E, --equalize
        Reset the split ratios of the tree rooted at the selected node to their default value.

    -B, --balance
        Adjust the split ratios of the tree rooted at the selected node so that all windows occupy the same area.

    -C, --circulate forward|backward
        Circulate the windows of the tree rooted at the selected node.

    -t, --state [~](tiled|pseudo_tiled|floating|fullscreen)
        Set the state of the selected window. If ~ is present and the current state matches the given state, then the argument is interpreted as the last state.

    -g, --flag locked|sticky|private[=on|off]
        Set or toggle the given flag for the selected node.

    -l, --layer below|normal|above
        Set the stacking layer of the selected window.

    -c, --close
        Close the windows rooted at the selected node.

    -k, --kill
        Kill the windows rooted at the selected node.

  Desktop

General Syntax

    desktop [DESKTOP_SEL] COMMANDS

COMMANDS

    -f, --focus [DESKTOP_SEL]
        Focus the selected or given desktop.

    -a, --activate [DESKTOP_SEL]
        Activate the selected or given desktop.

    -m, --to-monitor MONITOR_SEL
        Send the selected desktop to the given monitor.

    -l, --layout CYCLE_DIR|monocle|tiled
        Set or cycle the layout of the selected desktop.

    -n, --rename <new_name>
        Rename the selected desktop.

    -s, --swap DESKTOP_SEL
        Swap the selected desktop with the given desktop.

    -b, --bubble CYCLE_DIR
        Bubble the selected desktop in the given direction.

    -r, --remove
        Remove the selected desktop.

  Monitor

General Syntax

    monitor [MONITOR_SEL] COMMANDS

Commands

    -f, --focus [MONITOR_SEL]
        Focus the selected or given monitor.

    -a, --add-desktops <name>...
        Create desktops with the given names in the selected monitor.

    -r, --remove-desktops <name>...
        Remove desktops with the given names.

    -o, --reorder-desktops <name>...
        Reorder the desktops of the selected monitor to match the given order.

    -d, --reset-desktops <name>...
        Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops. Incidentally reset the settings of the existing desktops.

    -g, --rectangle WxH+X+Y
        Set the rectangle of the selected monitor.

    -n, --rename <new_name>
        Rename the selected monitor.

    -s, --swap MONITOR_SEL
        Swap the selected monitor with the given monitor.

  Query

General Syntax

    query COMMANDS [OPTIONS]

Commands

    -N, --nodes
        List the IDs of the matching nodes.

    -D, --desktops
        List the names of the matching desktops.

    -M, --monitors
        List the names of the matching monitors.

    -T, --tree
        Print a JSON representation of the matching item.

Options

    [-m,--monitor [MONITOR_SEL]] | [-d,--desktop [DESKTOP_SEL]] | [-n, --node [NODE_SEL]]
        Constrain matches to the selected monitor, desktop or node. The descriptor can be omitted for -M, -D and -N.

  Wm

General Syntax

    wm COMMANDS

Commands

    -d, --dump-state
        Dump the current world state on standard output.

    -l, --load-state <file_path>
        Load a world state from the given file.

    -a, --add-monitor <name> WxH+X+Y
        Add a monitor for the given name and rectangle.

    -r, --remove-monitor <name>
        Remove the monitor with the given name.

    -o, --adopt-orphans
        Manage all the unmanaged windows remaining from a previous session.

    -h, --record-history on|off
        Enable or disable the recording of node focus history.

    -g, --get-status
        Print the current status information.

  Pointer

General Syntax

    pointer COMMANDS

Commands

    -g, --grab focus|move|resize_side|resize_corner
        Initiate the given pointer action.

    -t, --track <x> <y>
        Pass the pointer root coordinates for the current pointer action.

    -u, --ungrab
        Terminate the current pointer action.

  Rule

General Syntax

    rule COMMANDS

Commands

    -a, --add (<class_name>|*)[:(<instance_name>|*)] [-o|--one-shot] [monitor=MONITOR_SEL|desktop=DESKTOP_SEL|node=NODE_SEL] [state=STATE] [layer=LAYER] [split_dir=DIR] [split_ratio=RATIO] [(locked|sticky|private|center|follow|manage|focus|border)=(on|off)]
        Create a new rule.

    -r, --remove ^<n>|head|tail|(<class_name>|*)[:(<instance_name>|*)]...
        Remove the given rules.

    -l, --list
        List the rules.

  Config

General Syntax

    config [-m MONITOR_SEL|-d DESKTOP_SEL|-n NODE_SEL] <key> [<value>]
        Get or set the value of <key>.

  Subscribe

General Syntax

    subscribe (all|report|monitor|desktop|node|...)*
        Continuously print status information. See the EVENTS section for the detailed description of each event.

  Quit

General Syntax

    quit [<status>]
        Quit with an optional exit status.

EXIT CODES

If the server can’t handle a message, bspc will return with one of the following exit codes:

1
    Failure.

2
    Syntax error.

3
    Unknown command.

SETTINGS

Colors are in the form #RRGGBB, booleans are true, on, false or off.

All the boolean settings are false by default unless stated otherwise.

  Global Settings

normal_border_color
    Color of the border of an unfocused window.

active_border_color
    Color of the border of a focused window of an unfocused monitor.

focused_border_color
    Color of the border of a focused window of a focused monitor.

presel_feedback_color
    Color of the node --presel-{dir,ratio} message feedback area.

split_ratio
    Default split ratio.

status_prefix
    Prefix prepended to each of the status lines.

external_rules_command
    External command used to retrieve rule consequences. The command will receive the the ID of the window being processed as its first argument and the class and instance names as second and third arguments. The output of that command must have the following format: key1=value1 key2=value2 ... (the valid key/value pairs are given in the description of the rule command).

initial_polarity
    On which child should a new window be attached when adding a window on a single window tree in automatic mode. Accept the following values: first_child, second_child.

history_aware_focus
    Give priority to the focus history when focusing nodes.

focus_by_distance
    Base focusing on distances between windows.

borderless_monocle
    Remove borders of tiled windows for the monocle desktop layout.

gapless_monocle
    Remove gaps of tiled windows for the monocle desktop layout.

paddingless_monocle
    Remove padding space for the monocle desktop layout.

single_monocle
    Set the desktop layout to monocle if there’s only one tiled window in the tree.

focus_follows_pointer
    Focus the window under the pointer.

pointer_follows_focus
    When focusing a window, put the pointer at its center.

pointer_follows_monitor
    When focusing a monitor, put the pointer at its center.

ignore_ewmh_focus
    Ignore EWMH focus requests coming from applications.

center_pseudo_tiled
    Center pseudo tiled windows into their tiling rectangles. Defaults to true.

remove_disabled_monitors
    Consider disabled monitors as disconnected.

remove_unplugged_monitors
    Remove unplugged monitors.

merge_overlapping_monitors
    Merge overlapping monitors (the bigger remains).

  Monitor and Desktop Settings

top_padding, right_padding, bottom_padding, left_padding
    Padding space added at the sides of the monitor or desktop.

  Default, Desktop Default and Window Settings

border_width
    Window border width.

  Default and Desktop Settings

window_gap
    Size of the gap that separates windows.

EVENTS

report
    See the next section for the description of the format.

monitor_add <monitor_name> <monitor_id> <monitor_geometry>
    A monitor is added.

monitor_rename <old_name> <new_name>
    A monitor is renamed.

monitor_remove <monitor_name>
    A monitor is removed.

monitor_swap <src_monitor_name> <dst_monitor_name>
    A monitor is swapped.

monitor_focus <monitor_name>
    A monitor is focused.

monitor_geometry <monitor_name> <monitor_geometry>
    The geometry of a monitor changed.

desktop_add <monitor_name> <desktop_name>
    A desktop is added.

desktop_rename <monitor_name> <old_name> <new_name>
    A desktop is renamed.

desktop_remove <monitor_name> <desktop_name>
    A desktop is removed.

desktop_swap <src_monitor_name> <src_desktop_name> <dst_monitor_name> <dst_desktop_name>
    A desktop is swapped.

desktop_transfer <src_monitor_name> <src_desktop_name> <dst_monitor_name>
    A desktop is transferred.

desktop_focus <monitor_name> <desktop_name>
    A desktop is focused.

desktop_activate <monitor_name> <desktop_name>
    A desktop is activated.

desktop_layout <monitor_name> <desktop_name> tiled|monocle
    The layout of a desktop changed.

node_manage <monitor_name> <desktop_name> <node_id> <ip_id>
    A window is managed.

node_unmanage <monitor_name> <desktop_name> <node_id>
    A window is unmanaged.

node_swap <src_monitor_name> <src_desktop_name> <src_node_id> <dst_monitor_name> <dst_desktop_name> <dst_node_id>
    A node is swapped.

node_transfer <src_monitor_name> <src_desktop_name> <src_node_id> <dst_monitor_name> <dst_desktop_name> <dst_node_id>
    A node is transferred.

node_focus <monitor_name> <desktop_name> <node_id>
    A node is focused.

node_activate <monitor_name> <desktop_name> <node_id>
    A node is activated.

node_presel <monitor_name> <desktop_name> <node_id> (dir DIR|ratio RATIO|cancel)
    A node is preselected.

node_stack <node_id_1> below|above <node_id_2>
    A node is stacked below or above another node.

node_geometry <monitor_name> <desktop_name> <node_id> <node_geometry>
    The geometry of a window changed.

node_state <monitor_name> <desktop_name> <node_id> tiled|pseudo_tiled|floating|fullscreen on|off
    The state of a window changed.

node_flag <monitor_name> <desktop_name> <node_id> sticky|private|locked|urgent on|off
    One of the flags of a node changed.

node_layer <monitor_name> <desktop_name> <node_id> below|normal|above
    The layer of a window changed.

Please note that bspwm initializes monitors before it reads messages on its socket, therefore the initial monitor events can’t be received.

REPORT FORMAT

Each report event message is composed of items separated by colons.

Each item has the form <type><value> where <type> is the first character of the item.

M<monitor_name>
    Focused monitor.

m<monitor_name>
    Unfocused monitor.

O<desktop_name>
    Occupied focused desktop.

o<desktop_name>
    Occupied unfocused desktop.

F<desktop_name>
    Free focused desktop.

f<desktop_name>
    Free unfocused desktop.

U<desktop_name>
    Urgent focused desktop.

u<desktop_name>
    Urgent unfocused desktop.

L(T|M)
    Layout of the focused desktop of a monitor.

T(T|P|F|=|@)
    State of the focused node of a focused desktop.

G(S?P?L?)
    Active flags of the focused node of a focused desktop.

ENVIRONMENT VARIABLES

BSPWM_SOCKET
    The path of the socket used for the communication between bspc and bspwm. If it isn’t defined, then the following path is used: /tmp/bspwm<host_name>_<display_number>_<screen_number>-socket.

CONTRIBUTORS

    • Steven Allen <steven at stebalien.com>

    • Thomas Adam <thomas at xteddy.org>

    • Ivan Kanakarakis <ivan.kanak at gmail.com>

AUTHOR

Bastien Dejean <nihilhill at gmail.com>