BSPWM(1)

NAME
bspwm - Binary space partitioning window manager

SYNOPSIS

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

bspc COMMAND [ARGUMENTS]

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.

CONFIGURATION

bspwm has only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.

The default configuration file is $XDG_CONFIG_HOME/bspwm/bspwmrc.

Keyboard and pointer bindings are defined with sxhkd.

Example configuration files can be found in the examples directory.

SPLITTING MODES

New windows are inserted in the tree as close as possible to the focused window.

There are only two splitting modes: automatic and manual.

The default mode is automatic. The manual mode is entered by sending a preselection message.

Example: insertion of a new node (number 4) into the given tree in automatic mode:

                  b                                   c
                 / \                                 / \
                3   a              -->              4   b
                ^  / \                              ^  / \
                  2   1                               3   a
                                                         / \
                                                        2   1
     +-------------------------+         +-------------------------+
     |            |            |         |            |            |
     |            |     2      |         |            |     3      |
     |            |            |         |            |            |
     |     3      |------------|   -->   |     4      |------------|
     |     ^      |            |         |     ^      |     |      |
     |            |     1      |         |            |  1  |  2   |
     |            |            |         |            |     |      |
     +-------------------------+         +-------------------------+

Same action, but the mode is manual, and a window --presel up message was sent beforehand:

                 b                                   b
                / \                                 / \
               3   a              -->              c   a
               ^  / \                             / \ / \
                 2   1                           4  3 2  1
                                                 ^
    +-------------------------+         +-------------------------+
    |            |            |         |            |            |
    |            |     2      |         |     4      |     2      |
    |            |            |         |     ^      |            |
    |     3      |------------|   -->   |------------|------------|
    |     ^      |            |         |            |            |
    |            |     1      |         |     3      |     1      |
    |            |            |         |            |            |
    +-------------------------+         +-------------------------+

CONTAINERS

Each monitor contains at least one desktop.

Each desktop contains at most one tree.

COMMON DEFINITIONS

    DIR         := left | right | up | down
    CYCLE_DIR   := next | prev

SELECTORS

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

Descriptive (relative) selectors consist of a primary selector and any number of non-conflicting modifiers as follows:

    PRIMARY_SELECTOR[.MODIFIER]*

For obvious reasons, neither desktop nor monitor names may be valid descriptive selectors.

  Window

Select a window.

    WINDOW_SEL := <window_id>
                | (DIR|CYCLE_DIR|biggest|last|focused|older|newer)[.floating|.tiled][.like|.unlike][.manual|.automatic][.urgent][.local][.unfocused]

Primary Selectors

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

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

    biggest
        Selects the biggest window on the current desktop.

    last
        Selects the previously focused window.

    focused
        Selects the currently focused window.

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

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

Modifiers

    floating
        Only consider floating windows.

    tiled
        Only consider tiled windows.

    like
        Only consider windows that have the same class as the current window.

    unlike
        Only consider windows that have a different class than the current window.

    manual
        Only consider windows in manual splitting mode.

    automatic
        Only consider windows in automatic splitting mode.

    local
        Only consider windows of the current desktop.

    urgent
        Only consider urgent windows.

    unfocused
        Only consider windows other than the focused window.

  Desktop

Select a desktop.

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

Primary Selectors

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

    free
        Only consider free desktops.

    urgent
        Only consider urgent desktops.

    local
        Only consider desktops of the current monitor.

  Monitor

Select a monitor.

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

Primary Selectors

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

    free
        Only consider monitors where the focused desktop is free.

WINDOW STATES

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

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

fullscreen
    Fills its monitor rectangle, is above all the other windows and has no borders.

locked
    Ignores the close message.

sticky
    Stays in the focused desktop of its monitor.

private
    Tries to keep the same tiling position/size.

COMMANDS

  Window

General Syntax

    window [WINDOW_SEL] OPTIONS

Options

    -f, --focus [WINDOW_SEL]
        Focus the selected or given window.

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

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

    -w, --to-window WINDOW_SEL
        Transplant the selected window to the given window.

    -s, --swap WINDOW_SEL
        Swap the selected window with the given window.

    -p, --presel DIR|cancel
        Preselect the splitting area of the selected window (or cancel the preselection).

    -r, --ratio RATIO
        Set the splitting ratio of the selected window (0 < RATIO < 1).

    -e, --edge DIR RATIO|±PIXELS
        Set or change the splitting ratio of the edge located in the given direction in relation to the selected window.

    -R, --rotate DIR 90|270|180
        Rotate the tree holding the edge located in the given direction in relation to the selected window.

    -t, --toggle floating|fullscreen|pseudo_tiled|locked|sticky|private[=on|off]
        Set or toggle the given state for the selected window.

    -c, --close
        Close the selected window.

    -k, --kill
        Kill the selected window.

  Desktop

General Syntax

    desktop [DESKTOP_SEL] OPTIONS

Options

    -f, --focus [DESKTOP_SEL]
        Focus 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.

    -r, --remove
        Remove the selected desktop.

    -c, --cancel-presel
        Cancel the preselection of all the windows of the selected desktop.

    -F, --flip horizontal|vertical
        Flip the tree of the selected desktop.

    -R, --rotate 90|270|180
        Rotate the tree of the selected desktop.

    -E, --equalize
        Reset the split ratios of the tree of the selected desktop.

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

    -C, --circulate forward|backward
        Circulate the leaves of the tree of the selected desktop.

    -t, --toggle floating[=on|off]
        Set or toggle the given state for the selected desktop.

  Monitor

General Syntax

    monitor [MONITOR_SEL] OPTIONS

Options

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

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

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

  Query

General Syntax

    query OPTIONS

Options

    -W, --windows
        List matching windows.

    -D, --desktops
        List matching desktops.

    -M, --monitors
        List matching monitors.

    -T, --tree
        Print tree rooted at query.

    -H, --history
        Print the history as it relates to the query.

    -S, --stack
        Print the window stacking order.

    [-m,--monitor [MONITOR_SEL]] | [-d,--desktop [DESKTOP_SEL]] | [-w, --window [WINDOW_SEL]]
        Constrain matches to the selected monitor, desktop or window.

  Restore

General Syntax

    restore OPTIONS

Options

    -T, --tree <file_path>
        Load the desktop trees from the given file.

    -H, --history <file_path>
        Load the focus history from the given file.

    -S, --stack <file_path>
        Load the window stacking order from the given file.

  Control

General Syntax

    control OPTIONS

Options

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

    --toggle-visibility
        Toggle the visibility of all the windows.

    --record-history on|off
        Enable or disable the recording of window focus history.

    --subscribe
        Continuously print status information.

    --get-status
        Print the current status information.

  Pointer

General Syntax

    pointer OPTIONS

Options

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

Options

    -a, --add <class_name>|<instance_name>|* [-o|--one-shot] [monitor=MONITOR_SEL|desktop=DESKTOP_SEL|window=WINDOW_SEL] [(floating|fullscreen|pseudo_tiled|locked|sticky|private|center|follow|manage|focus|border)=(on|off)] [split_dir=DIR] [split_ratio=RATIO]
        Create a new rule.

    -r, --remove ^<n>|head|tail|<class_name>|<instance_name>|*...
        Remove the given rules.

    -l, --list [<class_name>|<instance_name>|*]
        List the rules.

  Config

General Syntax

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

  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 either #RRGGBB or X color names, booleans are true, on, false or off.

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

  Global Settings

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

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

normal_border_color
    Color of the border of an unfocused window.

presel_border_color
    Color of the presel message feedback.

focused_locked_border_color
    Color of the border of a focused locked window of a focused monitor.

active_locked_border_color
    Color of the border of a focused locked window of an unfocused monitor.

normal_locked_border_color
    Color of the border of an unfocused locked window.

focused_sticky_border_color
    Color of the border of a focused sticky window of a focused monitor.

active_sticky_border_color
    Color of the border of a focused sticky window of an unfocused monitor.

normal_sticky_border_color
    Color of the border of an unfocused sticky window.

focused_private_border_color
    Color of the border of a focused private window of a focused monitor.

active_private_border_color
    Color of the border of a focused private window of an unfocused monitor.

normal_private_border_color
    Color of the border of an unfocused private window.

urgent_border_color
    Color of the border of an urgent window.

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 for tiled windows in monocle mode.

gapless_monocle
    Remove gaps for tiled windows in monocle mode.

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.

auto_alternate
    Interpret two consecutive identical use messages as an alternate message.

auto_cancel
    Interpret two consecutive identical presel messages as a cancel message.

apply_floating_atom
    Set the value of the _BSPWM_FLOATING_WINDOW atom of each window according to its floating state.

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.

STATUS FORMAT

Status information 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.

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.

PANELS

    • Any EWMH compliant panel (e.g.: tint2, bmpanel2, etc.).

    • A custom panel (have a look at the files in examples/panel).

KEY FEATURES

    • Configured and controlled through messages.

    • Multiple monitors support.

    • EWMH support.

    • Hybrid tiling.

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>

MAILING LIST

bspwm at librelist.com