2 :man version: {revnumber}
3 :man manual: Bspwm Manual
11 bspwm - Binary space partitioning window manager
16 *bspwm* [*-h*|*-v*|*-c* 'CONFIG_PATH']
18 *bspc* 'DOMAIN' ['SELECTOR'] 'COMMANDS'
23 *bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree.
25 It is controlled and configured via *bspc*.
32 Print the synopsis and exit.
35 Print the version and exit.
38 Use the given configuration file.
44 DIR := north | west | south | east
45 CYCLE_DIR := next | prev
51 Selectors are used to select a target node, desktop, or monitor. A selector
52 can either describe the target relatively or name it globally.
54 Selectors consist of a descriptor and any number of non-conflicting modifiers
57 DESCRIPTOR(.MODIFIER)*
59 An exclamation mark can be prepended to certain modifiers in order to reverse their meaning.
67 NODE_SEL := (<node_id>|PATH|DIR|CYCLE_DIR|last|older|newer|biggest|focused)[.[!]focused][.[!]automatic][.[!]local][.[!]leaf][.[!]STATE][.[!]FLAG][.[!]LAYER][.[!]same_class]
69 STATE := tiled|pseudo_tiled|floating|fullscreen
71 FLAG := urgent|sticky|private|locked
73 LAYER := below|normal|above
75 PATH := @[DESK_SEL:][[/]JUMP](/JUMP)*
77 JUMP := first|1|second|2|brother|parent|DIR
84 Selects the node with the given ID.
87 Selects the node at the given path.
90 Selects the window in the given (spacial) direction relative to the active node.
93 Selects the window in the given (cyclic) direction.
96 Selects the biggest window on the current desktop.
99 Selects the previously focused node.
102 Selects the currently focused node.
105 Selects the node older than the focused node in the history.
108 Selects the node newer than the focused node in the history.
113 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 'DESK_SEL' prefix).
116 Jumps to the first child.
119 Jumps to the second child.
122 Jumps to the brother node.
125 Jumps to the parent node.
128 Jumps to the node holding the edge in the given direction.
134 Only consider focused or unfocused nodes.
137 Only consider nodes in automatic or manual insertion mode.
140 Only consider nodes in or not in the current desktop.
143 Only consider leaves or internal nodes.
145 [!](tiled|pseudo_tiled|floating|fullscreen)::
146 Only consider windows in or not in the given state.
149 Only consider windows that have or don't have the same class as the current window.
151 [!](private|urgent|sticky|locked)::
152 Only consider windows that have or don't have the given flag set.
154 [!](below|normal|above)::
155 Only consider windows in or not in the given layer.
163 DESKTOP_SEL := (<desktop_name>|[MONITOR_SEL:](focused|^<n>)CYCLE_DIR|last|older|newer)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
170 Selects the desktop with the given name.
173 Selects the nth desktop.
176 Selects the desktop in the given direction relative to the active desktop.
179 Selects the previously focused desktop.
182 Selects the currently focused desktop.
185 Selects the desktop older than the focused desktop in the history.
188 Selects the desktop newer than the focused desktop in the history.
194 Only consider occupied or free desktops.
197 Only consider focused or unfocused desktops.
200 Only consider urgent or non urgent desktops.
203 Only consider inside or outside of the current monitor.
211 MONITOR_SEL := (<monitor_name>|^<n>|DIR|CYCLE_DIR|last|primary|focused|older|newer)[.[!]occupied][.[!]focused]
218 Selects the monitor with the given name.
221 Selects the nth monitor.
224 Selects the monitor in the given (spacial) direction relative to the active monitor.
227 Selects the monitor in the given (cyclic) direction relative to the active monitor.
230 Selects the primary monitor.
233 Selects the previously focused monitor.
236 Selects the currently focused monitor.
239 Selects the monitor older than the focused monitor in the history.
242 Selects the monitor newer than the focused monitor in the history.
248 Only consider monitors where the focused desktop is occupied or free.
251 Only consider focused or unfocused monitors.
258 Its size and position are determined by the splitting type and ratio of each node of its path in the window tree.
261 Has an unrestricted size while being centered in its tiling space.
264 Can be moved/resized freely. Although it doesn't occupy any tiling space, it is still part of the window tree.
267 Fills its monitor rectangle and has no borders. It is send in the ABOVE layer by default.
274 Ignores the *node --close* message.
277 Stays in the focused desktop of its monitor.
280 Tries to keep the same tiling position/size.
283 Has its urgency hint set. This flag is set externally.
289 There's three stacking layers: BELOW, NORMAL and ABOVE.
291 In each layer, the window are orderered as follow: tiled & pseudo-tiled < fullscreen < floating.
303 node ['NODE_SEL'] 'COMMANDS'
307 *-f*, *--focus* ['NODE_SEL']::
308 Focus the selected or given node.
310 *-a*, *--activate* ['NODE_SEL']::
311 Activate the selected or given node.
313 *-d*, *--to-desktop* 'DESKTOP_SEL'::
314 Send the selected node to the given desktop.
316 *-m*, *--to-monitor* 'MONITOR_SEL'::
317 Send the selected node to the given monitor.
319 *-n*, *--to-node* 'NODE_SEL'::
320 Transplant the selected node to the given node.
322 *-s*, *--swap* 'NODE_SEL'::
323 Swap the selected node with the given node.
325 *-p*, *--presel-dir* [~]'DIR'|cancel::
326 Preselect the splitting area of the selected node (or cancel the preselection).
328 *-o*, *--presel-ratio* 'RATIO'::
329 Set the splitting ratio of the preselection area.
331 *-r*, *--ratio* 'RATIO'|±'PIXELS'::
332 Set the splitting ratio of the selected node (0 < 'RATIO' < 1).
334 *-R*, *--rotate* '90|270|180'::
335 Rotate the tree rooted at the selected node.
337 *-F*, *--flip* 'horizontal|vertical'::
338 Flip the the tree rooted at selected node.
341 Reset the split ratios of the tree rooted at the selected node to their default value.
344 Adjust the split ratios of the tree rooted at the selected node so that all windows occupy the same area.
346 *-C*, *--circulate* forward|backward::
347 Circulate the windows of the tree rooted at the selected node.
349 *-t*, *--state* [~](tiled|pseudo_tiled|floating|fullscreen)::
350 Set the state of the selected window.
352 *-g*, *--flag* locked|sticky|private[=on|off]::
353 Set or toggle the given flag for the selected node.
355 *-l*, *--layer* below|normal|above::
356 Set the stacking layer of the selected window.
359 Close the windows rooted at the selected node.
362 Kill the windows rooted at the selected node.
370 desktop ['DESKTOP_SEL'] 'COMMANDS'
374 *-f*, *--focus* ['DESKTOP_SEL']::
375 Focus the selected or given desktop.
377 *-a*, *--activate* ['DESKTOP_SEL']::
378 Activate the selected or given desktop.
380 *-m*, *--to-monitor* 'MONITOR_SEL'::
381 Send the selected desktop to the given monitor.
383 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
384 Set or cycle the layout of the selected desktop.
386 *-n*, *--rename* <new_name>::
387 Rename the selected desktop.
389 *-s*, *--swap* 'DESKTOP_SEL'::
390 Swap the selected desktop with the given desktop.
392 *-b*, *--bubble* 'CYCLE_DIR'::
393 Bubble the selected desktop in the given direction.
396 Remove the selected desktop.
404 monitor ['MONITOR_SEL'] 'COMMANDS'
408 *-f*, *--focus* ['MONITOR_SEL']::
409 Focus the selected or given monitor.
411 *-a*, *--add-desktops* <name>...::
412 Create desktops with the given names in the selected monitor.
414 *-r*, *--remove-desktops* <name>...::
415 Remove desktops with the given names.
417 *-o*, *--reorder-desktops* <name>...::
418 Reorder the desktops of the selected monitor to match the given order.
420 *-d*, *--reset-desktops* <name>...::
421 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.
423 *-g*, *--rectangle* WxH+X+Y::
424 Set the rectangle of the selected monitor.
426 *-n*, *--rename* <new_name>::
427 Rename the selected monitor.
429 *-s*, *--swap* 'MONITOR_SEL'::
430 Swap the selected monitor with the given monitor.
438 query 'COMMANDS' ['OPTIONS']
444 List the IDs of the matching nodes.
447 List the names of the matching desktops.
450 List the names of the matching monitors.
453 Print a JSON representation of the matching item.
458 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-n*, *--node* ['NODE_SEL']]::
459 Constrain matches to the selected monitor, desktop or node. The descriptor can be omitted for '-M', '-D' and '-N'.
472 *-d*, *--dump-state*::
473 Dump the current world state on standard output.
475 *-l*, *--load-state* <file_path>::
476 Load a world state from the given file.
478 *-a*, *--add-monitor* <name> WxH+X+Y::
479 Add a monitor for the given name and rectangle.
481 *-r*, *--remove-monitor* <name>::
482 Remove the monitor with the given name.
484 *-o*, *--adopt-orphans*::
485 Manage all the unmanaged windows remaining from a previous session.
487 *-h*, *--record-history* on|off::
488 Enable or disable the recording of node focus history.
490 *-g*, *--get-status*::
491 Print the current status information.
504 *-g*, *--grab* focus|move|resize_side|resize_corner::
505 Initiate the given pointer action.
507 *-t*, *--track* <x> <y>::
508 Pass the pointer root coordinates for the current pointer action.
511 Terminate the current pointer action.
524 *-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)]::
527 *-r*, *--remove* ^<n>|head|tail|(<class_name>|*)[:(<instance_name>|*)]...::
528 Remove the given rules.
539 config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-n 'NODE_SEL'] <key> [<value>]::
540 Get or set the value of <key>.
547 subscribe (all|report|monitor|desktop|window|...)*::
548 Continuously print status information. See the *EVENTS* section for the detailed description of each event.
557 Quit with an optional exit status.
562 If the server can't handle a message, *bspc* will return with one of the following exit codes:
574 Colors are in the form '#RRGGBB', booleans are 'true', 'on', 'false' or 'off'.
576 All the boolean settings are 'false' by default unless stated otherwise.
581 'normal_border_color'::
582 Color of the border of an unfocused window.
584 'active_border_color'::
585 Color of the border of a focused window of an unfocused monitor.
587 'focused_border_color'::
588 Color of the border of a focused window of a focused monitor.
590 'presel_feedback_color'::
591 Color of the *node --presel-{dir,ratio}* message feedback area.
597 Prefix prepended to each of the status lines.
599 'external_rules_command'::
600 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).
603 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*.
605 'history_aware_focus'::
606 Give priority to the focus history when focusing nodes.
608 'focus_by_distance'::
609 Base focusing on distances between windows.
611 'borderless_monocle'::
612 Remove borders of tiled windows for the *monocle* desktop layout.
615 Remove gaps of tiled windows for the *monocle* desktop layout.
618 Set the desktop layout to *monocle* if there's only one tiled window in the tree.
620 'focus_follows_pointer'::
621 Focus the window under the pointer.
623 'pointer_follows_focus'::
624 When focusing a window, put the pointer at its center.
626 'pointer_follows_monitor'::
627 When focusing a monitor, put the pointer at its center.
629 'ignore_ewmh_focus'::
630 Ignore EWMH focus requests coming from applications.
632 'center_pseudo_tiled'::
633 Center pseudo tiled windows into their tiling rectangles. Defaults to 'true'.
635 'remove_disabled_monitors'::
636 Consider disabled monitors as disconnected.
638 'remove_unplugged_monitors'::
639 Remove unplugged monitors.
641 'merge_overlapping_monitors'::
642 Merge overlapping monitors (the bigger remains).
644 Monitor and Desktop Settings
645 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
651 Padding space added at the sides of the monitor or desktop.
653 Default, Desktop Default and Window Settings
654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
659 Default and Desktop Settings
660 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
663 Size of the gap that separates windows.
670 See the next section for the description of the format.
672 'monitor_add <monitor_name> <monitor_id> <monitor_geometry>'::
675 'monitor_rename <old_name> <new_name>'::
676 A monitor is renamed.
678 'monitor_remove <monitor_name>'::
679 A monitor is removed.
681 'monitor_focus <monitor_name>'::
682 A monitor is focused.
684 'monitor_geometry <monitor_name> <monitor_geometry>'::
685 The geometry of a monitor changed.
687 'desktop_add <monitor_name> <desktop_name>'::
690 'desktop_rename <monitor_name> <old_name> <new_name>'::
691 A desktop is renamed.
693 'desktop_remove <monitor_name> <desktop_name>'::
694 A desktop is removed.
696 'desktop_swap <src_monitor_name> <src_desktop_name> <dst_monitor_name> <dst_desktop_name>'::
697 A desktop is swapped.
699 'desktop_transfer <src_monitor_name> <src_desktop_name> <dst_monitor_name>'::
700 A desktop is transferred.
702 'desktop_focus <monitor_name> <desktop_name>'::
703 A desktop is focused.
705 'desktop_activate <monitor_name> <desktop_name>'::
706 A desktop is activated.
708 'desktop_layout <monitor_name> <desktop_name> tiled|monocle'::
709 The layout of a desktop changed.
711 'node_manage <monitor_name> <desktop_name> <node_id> <ip_id>'::
714 'node_unmanage <monitor_name> <desktop_name> <node_id>'::
715 A window is unmanaged.
717 'node_swap <src_monitor_name> <src_desktop_name> <src_node_id> <dst_monitor_name> <dst_desktop_name> <dst_node_id>'::
720 'node_transfer <src_monitor_name> <src_desktop_name> <src_node_id> <dst_monitor_name> <dst_desktop_name> <dst_node_id>'::
721 A node is transferred.
723 'node_focus <monitor_name> <desktop_name> <node_id>'::
726 'node_activate <monitor_name> <desktop_name> <node_id>'::
729 'node_presel <monitor_name> <desktop_name> <node_id> (dir DIR|ratio RATIO|cancel)'::
730 A node is preselected.
732 'node_stack <node_id_1> below|above <node_id_2>'::
733 A node is stacked below or above another node.
735 'node_geometry <monitor_name> <desktop_name> <node_id> <node_geometry>'::
736 The geometry of a window changed.
738 'node_state <monitor_name> <desktop_name> <node_id> tiled|pseudo_tiled|floating|fullscreen on|off'::
739 The state of a window changed.
741 'node_flag <monitor_name> <desktop_name> <node_id> sticky|private|locked|urgent on|off'::
742 One of the flags of a node changed.
744 'node_layer <monitor_name> <desktop_name> <node_id> below|normal|above'::
745 The layer of a window changed.
747 Please note that *bspwm* initializes monitors before it reads messages on its socket, therefore the initial monitor events can't be received.
752 Each report event message is composed of items separated by colons.
754 Each item has the form '<type><value>' where '<type>' is the first character of the item.
763 Occupied focused desktop.
766 Occupied unfocused desktop.
769 Free focused desktop.
772 Free unfocused desktop.
775 Urgent focused desktop.
778 Urgent unfocused desktop.
781 Layout of the focused desktop of a monitor.
784 State of the focused node of a focused desktop.
787 Active flags of the focused node of a focused desktop.
789 Environment Variables
790 ---------------------
793 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'.
798 * Steven Allen <steven at stebalien.com>
799 * Thomas Adam <thomas at xteddy.org>
800 * Ivan Kanakarakis <ivan.kanak at gmail.com>
805 Bastien Dejean <nihilhill at gmail.com>