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'
20 *bspc* 'COMMAND' ['OPTIONS'] ['ARGUMENTS']
25 *bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree.
27 It is controlled and configured via *bspc*.
34 Print the synopsis and exit.
37 Print the version and exit.
40 Use the given configuration file.
46 DIR := north | west | south | east
47 CYCLE_DIR := next | prev
53 Selectors are used to select a target node, desktop, or monitor. A selector
54 can either describe the target relatively or name it globally.
56 Selectors consist of an optional reference, a descriptor and any number of
57 non-conflicting modifiers as follows:
59 [REFERENCE#]DESCRIPTOR(.MODIFIER)*
61 The relative targets are computed in relation to the given reference (the
62 default reference value is *focused*).
64 An exclamation mark can be prepended to any modifier in order to reverse its
73 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]
75 STATE := tiled|pseudo_tiled|floating|fullscreen
77 FLAG := hidden|sticky|private|locked|urgent
79 LAYER := below|normal|above
81 PATH := @[DESKTOP_SEL:][[/]JUMP](/JUMP)*
83 JUMP := first|1|second|2|brother|parent|DIR
90 Selects the window in the given (spacial) direction relative to the reference node.
93 Selects the window in the given (cyclic) direction relative to the reference node.
96 Selects the node at the given path.
99 Selects the previously focused node relative to the reference node.
102 Selects the node older than the reference node in the history.
105 Selects the node newer than the reference node in the history.
108 Selects the currently focused node.
111 Selects the window under the pointer.
114 Selects the biggest window.
117 Selects the node with the given ID.
122 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).
125 Jumps to the first child.
128 Jumps to the second child.
131 Jumps to the brother node.
134 Jumps to the parent node.
137 Jumps to the node holding the edge in the given direction.
143 Only consider focused or unfocused nodes.
146 Only consider nodes in automatic or manual insertion mode.
149 Only consider nodes in or not in the reference desktop.
152 Only consider nodes in or not in the active desktop of their monitor.
155 Only consider leaves or internal nodes.
158 Only consider nodes that hold or don't hold a window.
160 [!](tiled|pseudo_tiled|floating|fullscreen)::
161 Only consider windows in or not in the given state.
164 Only consider windows that have or don't have the same class as the reference window.
167 Only consider nodes that are or aren't descendants of the reference node.
170 Only consider nodes that are or aren't ancestors of the reference node.
172 [!](hidden|sticky|private|locked|urgent)::
173 Only consider windows that have or don't have the given flag set.
175 [!](below|normal|above)::
176 Only consider windows in or not in the given layer.
184 DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|last|older|newer|[MONITOR_SEL:](focused|^<n>)|<desktop_id>|<desktop_name>)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
191 Selects the desktop in the given direction relative to the reference desktop.
194 Selects the previously focused desktop relative to the reference desktop.
197 Selects the desktop older than the reference desktop in the history.
200 Selects the desktop newer than the reference desktop in the history.
203 Selects the currently focused desktop.
206 Selects the nth desktop.
209 Selects the desktop with the given ID.
212 Selects the desktop with the given name.
218 Only consider occupied or free desktops.
221 Only consider focused or unfocused desktops.
224 Only consider urgent or non urgent desktops.
227 Only consider desktops inside or outside of the reference monitor.
235 MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|last|older|newer|focused|primary|^<n>|<monitor_id>|<monitor_name>)[.[!]occupied][.[!]focused]
242 Selects the monitor in the given (spacial) direction relative to the reference monitor.
245 Selects the monitor in the given (cyclic) direction relative to the reference monitor.
248 Selects the previously focused monitor relative to the reference monitor.
251 Selects the monitor older than the reference monitor in the history.
254 Selects the monitor newer than the reference monitor in the history.
257 Selects the currently focused monitor.
260 Selects the primary monitor.
263 Selects the nth monitor.
266 Selects the monitor with the given ID.
269 Selects the monitor with the given name.
276 Only consider monitors where the focused desktop is occupied or free.
279 Only consider focused or unfocused monitors.
286 Its size and position are determined by the splitting type and ratio of each node of its path in the window tree.
289 Has an unrestricted size while being centered in its tiling space.
292 Can be moved/resized freely. Although it doesn't occupy any tiling space, it is still part of the window tree.
295 Fills its monitor rectangle and has no borders. It is send in the ABOVE layer by default.
302 Is hidden and doesn't occupy any tiling space.
305 Stays in the focused desktop of its monitor.
308 Tries to keep the same tiling position/size.
311 Ignores the *node --close* message.
314 Has its urgency hint set. This flag is set externally.
320 There's three stacking layers: BELOW, NORMAL and ABOVE.
322 In each layer, the window are orderered as follow: tiled & pseudo-tiled < fullscreen < floating.
334 node ['NODE_SEL'] 'COMMANDS'
336 If 'NODE_SEL' is omitted, *focused* is assumed.
340 *-f*, *--focus* ['NODE_SEL']::
341 Focus the selected or given node.
343 *-a*, *--activate* ['NODE_SEL']::
344 Activate the selected or given node.
346 *-d*, *--to-desktop* 'DESKTOP_SEL'::
347 Send the selected node to the given desktop.
349 *-m*, *--to-monitor* 'MONITOR_SEL'::
350 Send the selected node to the given monitor.
352 *-n*, *--to-node* 'NODE_SEL'::
353 Transplant the selected node to the given node.
355 *-s*, *--swap* 'NODE_SEL'::
356 Swap the selected node with the given node.
358 *-p*, *--presel-dir* \[~]'DIR'|cancel::
359 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*.
361 *-o*, *--presel-ratio* 'RATIO'::
362 Set the splitting ratio of the preselection area.
364 *-v*, *--move* 'dx' 'dy'::
365 Move the selected window by 'dx' pixels horizontally and 'dy' pixels vertically.
367 *-z*, *--resize* top|left|bottom|right|top_left|top_right|bottom_right|bottom_left 'dx' 'dy'::
368 Resize the selected window by moving the given handle by 'dx' pixels horizontally and 'dy' pixels vertically.
370 *-r*, *--ratio* 'RATIO'|(+|-)'PIXELS'::
371 Set the splitting ratio of the selected node (0 < 'RATIO' < 1).
373 *-R*, *--rotate* '90|270|180'::
374 Rotate the tree rooted at the selected node.
376 *-F*, *--flip* 'horizontal|vertical'::
377 Flip the the tree rooted at selected node.
380 Reset the split ratios of the tree rooted at the selected node to their default value.
383 Adjust the split ratios of the tree rooted at the selected node so that all windows occupy the same area.
385 *-C*, *--circulate* forward|backward::
386 Circulate the windows of the tree rooted at the selected node.
388 *-t*, *--state* [~](tiled|pseudo_tiled|floating|fullscreen)::
389 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.
391 *-g*, *--flag* hidden|sticky|private|locked[=on|off]::
392 Set or toggle the given flag for the selected node.
394 *-l*, *--layer* below|normal|above::
395 Set the stacking layer of the selected window.
397 *-i*, *--insert-receptacle*::
398 Insert a receptacle node at the selected node.
401 Close the windows rooted at the selected node.
404 Kill the windows rooted at the selected node.
412 desktop ['DESKTOP_SEL'] 'COMMANDS'
414 If 'DESKTOP_SEL' is omitted, *focused* is assumed.
418 *-f*, *--focus* ['DESKTOP_SEL']::
419 Focus the selected or given desktop.
421 *-a*, *--activate* ['DESKTOP_SEL']::
422 Activate the selected or given desktop.
424 *-m*, *--to-monitor* 'MONITOR_SEL'::
425 Send the selected desktop to the given monitor.
427 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
428 Set or cycle the layout of the selected desktop.
430 *-n*, *--rename* <new_name>::
431 Rename the selected desktop.
433 *-s*, *--swap* 'DESKTOP_SEL'::
434 Swap the selected desktop with the given desktop.
436 *-b*, *--bubble* 'CYCLE_DIR'::
437 Bubble the selected desktop in the given direction.
440 Remove the selected desktop.
448 monitor ['MONITOR_SEL'] 'COMMANDS'
450 If 'MONITOR_SEL' is omitted, *focused* is assumed.
454 *-f*, *--focus* ['MONITOR_SEL']::
455 Focus the selected or given monitor.
457 *-s*, *--swap* 'MONITOR_SEL'::
458 Swap the selected monitor with the given monitor.
460 *-a*, *--add-desktops* <name>...::
461 Create desktops with the given names in the selected monitor.
463 *-o*, *--reorder-desktops* <name>...::
464 Reorder the desktops of the selected monitor to match the given order.
466 *-d*, *--reset-desktops* <name>...::
467 Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops.
469 *-g*, *--rectangle* WxH+X+Y::
470 Set the rectangle of the selected monitor.
472 *-n*, *--rename* <new_name>::
473 Rename the selected monitor.
476 Remove the selected monitor.
484 query 'COMMANDS' ['OPTIONS']
489 The optional selectors are references.
491 *-N*, *--nodes* ['NODE_SEL']::
492 List the IDs of the matching nodes.
494 *-D*, *--desktops* ['DESKTOP_SEL']::
495 List the IDs (or names) of the matching desktops.
497 *-M*, *--monitors* ['MONITOR_SEL']::
498 List the IDs (or names) of the matching monitors.
501 Print a JSON representation of the matching item.
506 *-m*,*--monitor* ['MONITOR_SEL']::
507 *-d*,*--desktop* ['DESKTOP_SEL']::
508 *-n*, *--node* ['NODE_SEL']::
509 Constrain matches to the selected monitor, desktop or node. The descriptor can be omitted for '-M', '-D' and '-N'.
512 Print names instead of IDs.
525 *-d*, *--dump-state*::
526 Dump the current world state on standard output.
528 *-l*, *--load-state* <file_path>::
529 Load a world state from the given file.
531 *-a*, *--add-monitor* <name> WxH+X+Y::
532 Add a monitor for the given name and rectangle.
534 *-o*, *--adopt-orphans*::
535 Manage all the unmanaged windows remaining from a previous session.
537 *-h*, *--record-history* on|off::
538 Enable or disable the recording of node focus history.
540 *-g*, *--get-status*::
541 Print the current status information.
554 *-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)]::
557 *-r*, *--remove* ^<n>|head|tail|(<class_name>|\*)[:(<instance_name>|*)]...::
558 Remove the given rules.
569 config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-n 'NODE_SEL'] <setting> [<value>]::
570 Get or set the value of <setting>.
577 subscribe (all|report|monitor|desktop|node|...)*::
578 Continuously print status information. See the *EVENTS* section for the detailed description of each event.
587 Quit with an optional exit status.
592 If the server can't handle a message, *bspc* will return with a non-zero exit code.
596 Colors are in the form '#RRGGBB', booleans are 'true', 'on', 'false' or 'off'.
598 All the boolean settings are 'false' by default unless stated otherwise.
603 'normal_border_color'::
604 Color of the border of an unfocused window.
606 'active_border_color'::
607 Color of the border of a focused window of an unfocused monitor.
609 'focused_border_color'::
610 Color of the border of a focused window of a focused monitor.
612 'presel_feedback_color'::
613 Color of the *node --presel-{dir,ratio}* message feedback area.
619 Prefix prepended to each of the status lines.
621 'external_rules_command'::
622 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).
625 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*.
627 'borderless_monocle'::
628 Remove borders of tiled windows for the *monocle* desktop layout.
631 Remove gaps of tiled windows for the *monocle* desktop layout.
633 'paddingless_monocle'::
634 Remove padding space for the *monocle* desktop layout.
637 Set the desktop layout to *monocle* if there's only one tiled window in the tree.
639 'pointer_motion_interval'::
640 The minimum interval, in milliseconds, between two motion notify events.
643 Keyboard modifier used for moving or resizing windows. Accept the following values: *shift*, *control*, *lock*, *mod1*, *mod2*, *mod3*, *mod4*, *mod5*.
648 Action performed when pressing 'pointer_modifier' + 'button<n>'. Accept the following values: *move*, *resize_side*, *resize_corner*, *focus*, *none*.
651 Focus a window (or a monitor) by clicking it.
653 'swallow_first_click'::
654 Don't replay the click that makes a window focused when 'click_to_focus' is set.
656 'focus_follows_pointer'::
657 Focus the window under the pointer.
659 'pointer_follows_focus'::
660 When focusing a window, put the pointer at its center.
662 'pointer_follows_monitor'::
663 When focusing a monitor, put the pointer at its center.
665 'ignore_ewmh_focus'::
666 Ignore EWMH focus requests coming from applications.
668 'center_pseudo_tiled'::
669 Center pseudo tiled windows into their tiling rectangles. Defaults to 'true'.
672 Apply ICCCM window size hints.
674 'remove_disabled_monitors'::
675 Consider disabled monitors as disconnected.
677 'remove_unplugged_monitors'::
678 Remove unplugged monitors.
680 'merge_overlapping_monitors'::
681 Merge overlapping monitors (the bigger remains).
683 Monitor and Desktop Settings
684 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
690 Padding space added at the sides of the monitor or desktop.
696 Size of the gap that separates windows.
708 Focus the window under the pointer if 'click_to_focus' is set.
710 'pointer_modifier' + 'button1'::
711 Move the window under the pointer.
713 'pointer_modifier' + 'button2'::
714 Resize the window under the pointer by dragging the nearest side.
716 'pointer_modifier' + 'button3'::
717 Resize the window under the pointer by dragging the nearest corner.
719 The behavior of 'pointer_modifier' + 'button<n>' can be modified through the 'pointer_action<n>' setting.
725 See the next section for the description of the format.
727 'monitor_add <monitor_id> <monitor_name> <monitor_geometry>'::
730 'monitor_rename <monitor_id> <old_name> <new_name>'::
731 A monitor is renamed.
733 'monitor_remove <monitor_id>'::
734 A monitor is removed.
736 'monitor_swap <src_monitor_id> <dst_monitor_id>'::
737 A monitor is swapped.
739 'monitor_focus <monitor_id>'::
740 A monitor is focused.
742 'monitor_geometry <monitor_id> <monitor_geometry>'::
743 The geometry of a monitor changed.
745 'desktop_add <monitor_id> <desktop_id> <desktop_name>'::
748 'desktop_rename <monitor_id> <desktop_id> <old_name> <new_name>'::
749 A desktop is renamed.
751 'desktop_remove <monitor_id> <desktop_id>'::
752 A desktop is removed.
754 'desktop_swap <src_monitor_id> <src_desktop_id> <dst_monitor_id> <dst_desktop_id>'::
755 A desktop is swapped.
757 'desktop_transfer <src_monitor_id> <src_desktop_id> <dst_monitor_id>'::
758 A desktop is transferred.
760 'desktop_focus <monitor_id> <desktop_id>'::
761 A desktop is focused.
763 'desktop_activate <monitor_id> <desktop_id>'::
764 A desktop is activated.
766 'desktop_layout <monitor_id> <desktop_id> tiled|monocle'::
767 The layout of a desktop changed.
769 'node_manage <monitor_id> <desktop_id> <node_id> <ip_id>'::
772 'node_unmanage <monitor_id> <desktop_id> <node_id>'::
773 A window is unmanaged.
775 'node_swap <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
778 'node_transfer <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
779 A node is transferred.
781 'node_focus <monitor_id> <desktop_id> <node_id>'::
784 'node_activate <monitor_id> <desktop_id> <node_id>'::
787 'node_presel <monitor_id> <desktop_id> <node_id> (dir DIR|ratio RATIO|cancel)'::
788 A node is preselected.
790 'node_stack <node_id_1> below|above <node_id_2>'::
791 A node is stacked below or above another node.
793 'node_geometry <monitor_id> <desktop_id> <node_id> <node_geometry>'::
794 The geometry of a window changed.
796 'node_state <monitor_id> <desktop_id> <node_id> tiled|pseudo_tiled|floating|fullscreen on|off'::
797 The state of a window changed.
799 'node_flag <monitor_id> <desktop_id> <node_id> hidden|sticky|private|locked|urgent on|off'::
800 One of the flags of a node changed.
802 'node_layer <monitor_id> <desktop_id> <node_id> below|normal|above'::
803 The layer of a window changed.
805 'pointer_action <monitor_id> <desktop_id> <node_id> move|resize_corner|resize_side begin|end'::
806 A pointer action occured.
808 Please note that *bspwm* initializes monitors before it reads messages on its socket, therefore the initial monitor events can't be received.
813 Each report event message is composed of items separated by colons.
815 Each item has the form '<type><value>' where '<type>' is the first character of the item.
824 Occupied focused desktop.
827 Occupied unfocused desktop.
830 Free focused desktop.
833 Free unfocused desktop.
836 Urgent focused desktop.
839 Urgent unfocused desktop.
842 Layout of the focused desktop of a monitor.
845 State of the focused node of a focused desktop.
848 Active flags of the focused node of a focused desktop.
850 Environment Variables
851 ---------------------
854 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'.
859 * Steven Allen <steven at stebalien.com>
860 * Thomas Adam <thomas at xteddy.org>
861 * Ivan Kanakarakis <ivan.kanak at gmail.com>
866 Bastien Dejean <nihilhill at gmail.com>