bspwm man page

bspwm — Binary space partitioning window manager

Synopsis

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

bspc DOMAIN [SELECTOR] COMMANDS

bspc COMMAND [Options] [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.

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 an optional reference, a descriptor and any number of non-conflicting modifiers as follows:

[REFERENCE#]DESCRIPTOR(.MODIFIER)*

The relative targets are computed in relation to the given reference (the default reference value is focused).

An exclamation mark can be prepended to any modifier in order to reverse its meaning.

Node

Select a node.

NODE_SEL := [NODE_SEL#](DIR|CYCLE_DIR|PATH|last|older|newer|focused|pointed|biggest|<node_id>)[.[!]focused][.[!]automatic][.[!]local][.[!]active][.[!]leaf][.[!]window][.[!]STATE][.[!]FLAG][.[!]LAYER][.[!]same_class][.[!]descendant_of][.[!]ancestor_of]

STATE := tiled|pseudo_tiled|floating|fullscreen

FLAG := hidden|sticky|private|locked|urgent

LAYER := below|normal|above

PATH := @[DESKTOP_SEL:][[/]JUMP](/JUMP)*

JUMP := first|1|second|2|brother|parent|DIR

Descriptors

DIR

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

CYCLE_DIR

Selects the window in the given (cyclic) direction relative to the reference node.

PATH

Selects the node at the given path.

last

Selects the previously focused node relative to the reference node.

older

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

newer

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

focused

Selects the currently focused node.

pointed

Selects the window under the pointer.

biggest

Selects the biggest window.

<node_id>

Selects the node with the given ID.

Path Jumps

The initial node is the focused node (or the root if the path starts with /) of the reference 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 reference desktop.

[!]active

Only consider nodes in or not in the active desktop of their monitor.

[!]leaf

Only consider leaves or internal nodes.

[!]window

Only consider nodes that hold or don’t hold a window.

[!](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 reference window.

[!]descendant_of

Only consider nodes that are or aren’t descendants of the reference node.

[!]ancestor_of

Only consider nodes that are or aren’t ancestors of the reference node.

[!](hidden|sticky|private|locked|urgent)

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_SEL#](CYCLE_DIR|last|older|newer|[MONITOR_SEL:](focused|^<n>)|<desktop_id>|<desktop_name>)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]

Descriptors

CYCLE_DIR

Selects the desktop in the given direction relative to the reference desktop.

last

Selects the previously focused desktop relative to the reference desktop.

older

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

newer

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

focused

Selects the currently focused desktop.

^<n>

Selects the nth desktop.

<desktop_id>

Selects the desktop with the given ID.

<desktop_name>

Selects the desktop with the given name.

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

Monitor

Select a monitor.

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

Descriptors

DIR

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

CYCLE_DIR

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

last

Selects the previously focused monitor relative to the reference monitor.

older

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

newer

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

focused

Selects the currently focused monitor.

primary

Selects the primary monitor.

^<n>

Selects the nth monitor.

<monitor_id>

Selects the monitor with the given ID.

<monitor_name>

Selects the monitor with the given name.

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

hidden

Is hidden and doesn’t occupy any tiling space.

sticky

Stays in the focused desktop of its monitor.

private

Tries to keep the same tiling position/size.

locked

Ignores the node --close message.

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

If NODE_SEL is omitted, focused is assumed.

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.

-v, --move dx dy

Move the selected window by dx pixels horizontally and dy pixels vertically.

-z, --resize top|left|bottom|right|top_left|top_right|bottom_right|bottom_left dx dy

Resize the selected window by moving the given handle by dx pixels horizontally and dy pixels vertically.

-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 hidden|sticky|private|locked[=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.

-i, --insert-receptacle

Insert a receptacle node at the selected node.

-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

If DESKTOP_SEL is omitted, focused is assumed.

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

If MONITOR_SEL is omitted, focused is assumed.

Commands

-f, --focus [MONITOR_SEL]

Focus the selected or given monitor.

-s, --swap MONITOR_SEL

Swap the selected monitor with the given monitor.

-a, --add-desktops <name>...

Create desktops with the given names in the selected monitor.

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

-g, --rectangle WxH+X+Y

Set the rectangle of the selected monitor.

-n, --rename <new_name>

Rename the selected monitor.

-r, --remove

Remove the selected monitor.

Query

General Syntax

query COMMANDS [Options]

Commands

The optional selectors are references.

-N, --nodes [NODE_SEL]

List the IDs of the matching nodes.

-D, --desktops [DESKTOP_SEL]

List the IDs of the matching desktops.

-M, --monitors [MONITOR_SEL]

List the IDs 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.

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

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] [(hidden|sticky|private|locked|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 a non-zero exit code.

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 following arguments: window ID, class and instance names, monitor, desktop and node selectors. 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.

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.

pointer_motion_interval

The minimum interval, in milliseconds, between two motion notify events.

pointer_modifier

Keyboard modifier used for moving or resizing windows. Accept the following values: shift, control, lock, mod1, mod2, mod3, mod4, mod5.

pointer_action1, pointer_action2, pointer_action3

Action performed when pressing pointer_modifier + button<n>. Accept the following values: move, resize_side, resize_corner, focus, none.

click_to_focus

Focus a window (or a monitor) by clicking it.

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.

honor_size_hints

Apply ICCCM window size hints.

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.

Desktop Settings

window_gap

Size of the gap that separates windows.

Node Settings

border_width

Window border width.

Pointer Bindings

button1

Focus the window under the pointer if click_to_focus is set.

pointer_modifier + button1

Move the window under the pointer.

pointer_modifier + button2

Resize the window under the pointer by dragging the nearest side.

pointer_modifier + button3

Resize the window under the pointer by dragging the nearest corner.

The behavior of pointer_modifier + button<n> can be modified through the pointer_action<n> setting.

Events

report

See the next section for the description of the format.

monitor_add <monitor_id> <monitor_name> <monitor_geometry>

A monitor is added.

monitor_rename <monitor_id> <old_name> <new_name>

A monitor is renamed.

monitor_remove <monitor_id>

A monitor is removed.

monitor_swap <src_monitor_id> <dst_monitor_id>

A monitor is swapped.

monitor_focus <monitor_id>

A monitor is focused.

monitor_geometry <monitor_id> <monitor_geometry>

The geometry of a monitor changed.

desktop_add <monitor_id> <desktop_id> <desktop_name>

A desktop is added.

desktop_rename <monitor_id> <desktop_id> <old_name> <new_name>

A desktop is renamed.

desktop_remove <monitor_id> <desktop_id>

A desktop is removed.

desktop_swap <src_monitor_id> <src_desktop_id> <dst_monitor_id> <dst_desktop_id>

A desktop is swapped.

desktop_transfer <src_monitor_id> <src_desktop_id> <dst_monitor_id>

A desktop is transferred.

desktop_focus <monitor_id> <desktop_id>

A desktop is focused.

desktop_activate <monitor_id> <desktop_id>

A desktop is activated.

desktop_layout <monitor_id> <desktop_id> tiled|monocle

The layout of a desktop changed.

node_manage <monitor_id> <desktop_id> <node_id> <ip_id>

A window is managed.

node_unmanage <monitor_id> <desktop_id> <node_id>

A window is unmanaged.

node_swap <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>

A node is swapped.

node_transfer <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>

A node is transferred.

node_focus <monitor_id> <desktop_id> <node_id>

A node is focused.

node_activate <monitor_id> <desktop_id> <node_id>

A node is activated.

node_presel <monitor_id> <desktop_id> <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_id> <desktop_id> <node_id> <node_geometry>

The geometry of a window changed.

node_state <monitor_id> <desktop_id> <node_id> tiled|pseudo_tiled|floating|fullscreen on|off

The state of a window changed.

node_flag <monitor_id> <desktop_id> <node_id> hidden|sticky|private|locked|urgent on|off

One of the flags of a node changed.

node_layer <monitor_id> <desktop_id> <node_id> below|normal|above

The layer of a window changed.

pointer_action <monitor_id> <desktop_id> <node_id> move|resize_corner|resize_side begin|end

A pointer action occured.

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

Author

Bastien Dejean <nihilhill at gmail.com>

Info

10/30/2016 Bspwm 0.9.2 Bspwm Manual