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
<node_id>
PATH
DIR
CYCLE_DIR
biggest
last
focused
older
newer
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
2|second
brother
parent
DIR
[!]focused
[!]automatic
[!]local
[!]leaf
[!](tiled|pseudo_tiled|floating|fullscreen)
[!]same_class
[!](private|urgent|sticky|locked)
[!](below|normal|above)
Descriptors
Desktop
Select a desktop.
-
DESKTOP_SEL := (<desktop_name>|[MONITOR_SEL:](focused|^<n>)CYCLE_DIR|last|older|newer)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
<desktop_name>
^<n>
CYCLE_DIR
last
focused
older
newer
[!]occupied
[!]focused
[!]urgent
[!]local
Descriptors
Monitor
Select a monitor.
-
MONITOR_SEL := (<monitor_name>|^<n>|DIR|CYCLE_DIR|last|primary|focused|older|newer)[.[!]occupied][.[!]focused]
<monitor_name>
^<n>
DIR
CYCLE_DIR
primary
last
focused
older
newer
[!]occupied
[!]focused
Descriptors
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
node [NODE_SEL] COMMANDS
-f, --focus [NODE_SEL]
-a, --activate [NODE_SEL]
-d, --to-desktop DESKTOP_SEL
-m, --to-monitor MONITOR_SEL
-n, --to-node NODE_SEL
-s, --swap NODE_SEL
-p, --presel-dir [~]DIR|cancel
-o, --presel-ratio RATIO
-r, --ratio RATIO|(+|-)PIXELS
-R, --rotate 90|270|180
-F, --flip horizontal|vertical
-E, --equalize
-B, --balance
-C, --circulate forward|backward
-t, --state [~](tiled|pseudo_tiled|floating|fullscreen)
-g, --flag locked|sticky|private[=on|off]
-l, --layer below|normal|above
-c, --close
-k, --kill
General Syntax
Desktop
desktop [DESKTOP_SEL] COMMANDS
-f, --focus [DESKTOP_SEL]
-a, --activate [DESKTOP_SEL]
-m, --to-monitor MONITOR_SEL
-l, --layout CYCLE_DIR|monocle|tiled
-n, --rename <new_name>
-s, --swap DESKTOP_SEL
-b, --bubble CYCLE_DIR
-r, --remove
General Syntax
Monitor
monitor [MONITOR_SEL] COMMANDS
-f, --focus [MONITOR_SEL]
-a, --add-desktops <name>...
-r, --remove-desktops <name>...
-o, --reorder-desktops <name>...
-d, --reset-desktops <name>...
-g, --rectangle WxH+X+Y
-n, --rename <new_name>
-s, --swap MONITOR_SEL
General Syntax
Query
query COMMANDS [OPTIONS]
-N, --nodes
-D, --desktops
-M, --monitors
-T, --tree
[-m,--monitor [MONITOR_SEL]] | [-d,--desktop [DESKTOP_SEL]] | [-n, --node [NODE_SEL]]
General Syntax
Wm
wm COMMANDS
-d, --dump-state
-l, --load-state <file_path>
-a, --add-monitor <name> WxH+X+Y
-r, --remove-monitor <name>
-o, --adopt-orphans
-h, --record-history on|off
-g, --get-status
General Syntax
Pointer
pointer COMMANDS
-g, --grab focus|move|resize_side|resize_corner
-t, --track <x> <y>
-u, --ungrab
General Syntax
Rule
rule 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)]
-r, --remove ^<n>|head|tail|(<class_name>|*)[:(<instance_name>|*)]...
-l, --list
General Syntax
Config
config [-m MONITOR_SEL|-d DESKTOP_SEL|-n NODE_SEL] <key> [<value>]
General Syntax
Subscribe
subscribe (all|report|monitor|desktop|node|...)*
General Syntax
Quit
quit [<status>]
General Syntax
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>