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
67 The following characters cannot be used in monitor or desktop names: *#*, *:*, *.*.
69 The special selector *%<name>* can be used to select a monitor or a desktop with an invalid name.
77 NODE_SEL := [NODE_SEL#](DIR|CYCLE_DIR|PATH|any|first_ancestor|last|newest|
78 older|newer|focused|pointed|biggest|smallest|
79 <node_id>)[.[!]focused][.[!]active][.[!]automatic][.[!]local]
80 [.[!]leaf][.[!]window][.[!]STATE][.[!]FLAG][.[!]LAYER]
81 [.[!]same_class][.[!]descendant_of][.[!]ancestor_of]
83 STATE := tiled|pseudo_tiled|floating|fullscreen
85 FLAG := hidden|sticky|private|locked|marked|urgent
87 LAYER := below|normal|above
89 PATH := @[DESKTOP_SEL:][[/]JUMP](/JUMP)*
91 JUMP := first|1|second|2|brother|parent|DIR
98 Selects the window in the given (spacial) direction relative to the reference node.
101 Selects the window in the given (cyclic) direction relative to the reference node.
104 Selects the node at the given path.
107 Selects the first node that matches the given selectors.
110 Selects the first ancestor of the reference node that matches the given selectors.
113 Selects the previously focused node relative to the reference node.
116 Selects the newest node in the history of the focused node.
119 Selects the node older than the reference node in the history.
122 Selects the node newer than the reference node in the history.
125 Selects the currently focused node.
128 Selects the window under the pointer.
131 Selects the biggest window.
134 Selects the smallest window.
137 Selects the node with the given ID.
142 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).
145 Jumps to the first child.
148 Jumps to the second child.
151 Jumps to the brother node.
154 Jumps to the parent node.
157 Jumps to the node holding the edge in the given direction.
163 Only consider the focused node.
166 Only consider nodes that are the focused node of their desktop.
169 Only consider nodes in automatic insertion mode. See also *--presel-dir* under *Node* in the *DOMAINS* section below.
172 Only consider nodes in the reference desktop.
175 Only consider leaf nodes.
178 Only consider nodes whose split type is horizontal.
181 Only consider nodes whose split type is vertical.
184 Only consider nodes that hold a window.
186 [!](tiled|pseudo_tiled|floating|fullscreen)::
187 Only consider windows in the given state.
190 Only consider windows that have the same class as the reference window.
193 Only consider nodes that are descendants of the reference node.
196 Only consider nodes that are ancestors of the reference node.
198 [!](hidden|sticky|private|locked|marked|urgent)::
199 Only consider windows that have the given flag set.
201 [!](below|normal|above)::
202 Only consider windows in the given layer.
210 DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|any|last|newest|older|newer|
211 [MONITOR_SEL:](focused|^<n>)|
212 <desktop_id>|<desktop_name>)[.[!]focused][.[!]active]
213 [.[!]occupied][.[!]urgent][.[!]local]
220 Selects the desktop in the given direction relative to the reference desktop.
223 Selects the first desktop that matches the given selectors.
226 Selects the previously focused desktop relative to the reference desktop.
229 Selects the newest desktop in the history of the focused desktops.
232 Selects the desktop older than the reference desktop in the history.
235 Selects the desktop newer than the reference desktop in the history.
238 Selects the currently focused desktop.
241 Selects the nth desktop. If *MONITOR_SEL* is given, selects the nth desktop on the selected monitor.
244 Selects the desktop with the given ID.
247 Selects the desktop with the given name.
253 Only consider the focused desktop.
256 Only consider desktops that are the focused desktop of their monitor.
259 Only consider occupied desktops.
262 Only consider urgent desktops.
265 Only consider desktops inside the reference monitor.
273 MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|any|last|newest|older|newer|
274 focused|pointed|primary|^<n>|
275 <monitor_id>|<monitor_name>)[.[!]focused][.[!]occupied]
282 Selects the monitor in the given (spacial) direction relative to the reference monitor.
285 Selects the monitor in the given (cyclic) direction relative to the reference monitor.
288 Selects the first monitor that matches the given selectors.
291 Selects the previously focused monitor relative to the reference monitor.
294 Selects the newest monitor in the history of the focused monitors.
297 Selects the monitor older than the reference monitor in the history.
300 Selects the monitor newer than the reference monitor in the history.
303 Selects the currently focused monitor.
306 Selects the monitor under the pointer.
309 Selects the primary monitor.
312 Selects the nth monitor.
315 Selects the monitor with the given ID.
318 Selects the monitor with the given name.
325 Only consider the focused monitor.
328 Only consider monitors where the focused desktop is occupied.
336 Its size and position are determined by the window tree.
339 A tiled window that automatically shrinks but doesn't stretch beyond its floating size.
342 Can be moved/resized freely. Although it doesn't use any tiling space, it is still part of the window tree.
345 Fills its monitor rectangle and has no borders.
352 Is hidden and doesn't occupy any tiling space.
355 Stays in the focused desktop of its monitor.
358 Tries to keep the same tiling position/size.
361 Ignores the *node --close* message.
364 Is marked (useful for deferred actions). A marked node becomes unmarked after being sent on a preselected node.
367 Has its urgency hint set. This flag is set externally.
373 There's three stacking layers: BELOW, NORMAL and ABOVE.
375 In each layer, the window are orderered as follow: tiled & pseudo-tiled < floating < fullscreen.
380 A leaf node that doesn't hold any window is called a receptacle. When a node is inserted on a receptacle in automatic mode, it will replace the receptacle. A receptacle can be inserted on a node, preselected and killed. Receptacles can therefore be used to build a tree whose leaves are receptacles. Using the appropriate rules, one can then send windows on the leaves of this tree. This feature is used in 'examples/receptacles' to store and recreate layouts.
392 node ['NODE_SEL'] 'COMMANDS'
394 If 'NODE_SEL' is omitted, *focused* is assumed.
398 *-f*, *--focus* ['NODE_SEL']::
399 Focus the selected or given node.
401 *-a*, *--activate* ['NODE_SEL']::
402 Activate the selected or given node.
404 *-d*, *--to-desktop* 'DESKTOP_SEL' [*--follow*]::
405 Send the selected node to the given desktop. If *--follow* is passed, the focused node will stay focused.
407 *-m*, *--to-monitor* 'MONITOR_SEL' [*--follow*]::
408 Send the selected node to the given monitor. If *--follow* is passed, the focused node will stay focused.
410 *-n*, *--to-node* 'NODE_SEL' [*--follow*]::
411 Send the selected node on the given node. If *--follow* is passed, the focused node will stay focused.
413 *-s*, *--swap* 'NODE_SEL' [*--follow*]::
414 Swap the selected node with the given node. If *--follow* is passed, the focused node will stay focused.
416 *-p*, *--presel-dir* \[~]'DIR'|cancel::
417 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*. A node with a preselected area is said to be in "manual insertion mode".
419 *-o*, *--presel-ratio* 'RATIO'::
420 Set the splitting ratio of the preselection area.
422 *-v*, *--move* 'dx' 'dy'::
423 Move the selected window by 'dx' pixels horizontally and 'dy' pixels vertically.
425 *-z*, *--resize* top|left|bottom|right|top_left|top_right|bottom_right|bottom_left 'dx' 'dy'::
426 Resize the selected window by moving the given handle by 'dx' pixels horizontally and 'dy' pixels vertically.
428 *-r*, *--ratio* 'RATIO'|(+|-)('PIXELS'|'FRACTION')::
429 Set the splitting ratio of the selected node (0 < 'RATIO' < 1).
431 *-R*, *--rotate* '90|270|180'::
432 Rotate the tree rooted at the selected node.
434 *-F*, *--flip* 'horizontal|vertical'::
435 Flip the the tree rooted at selected node.
438 Reset the split ratios of the tree rooted at the selected node to their default value.
441 Adjust the split ratios of the tree rooted at the selected node so that all windows occupy the same area.
443 *-C*, *--circulate* forward|backward::
444 Circulate the windows of the tree rooted at the selected node.
446 *-t*, *--state* [~](tiled|pseudo_tiled|floating|fullscreen)::
447 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.
449 *-g*, *--flag* hidden|sticky|private|locked|marked[=on|off]::
450 Set or toggle the given flag for the selected node.
452 *-l*, *--layer* below|normal|above::
453 Set the stacking layer of the selected window.
455 *-i*, *--insert-receptacle*::
456 Insert a receptacle node at the selected node.
459 Close the windows rooted at the selected node.
462 Kill the windows rooted at the selected node.
470 desktop ['DESKTOP_SEL'] 'COMMANDS'
472 If 'DESKTOP_SEL' is omitted, *focused* is assumed.
476 *-f*, *--focus* ['DESKTOP_SEL']::
477 Focus the selected or given desktop.
479 *-a*, *--activate* ['DESKTOP_SEL']::
480 Activate the selected or given desktop.
482 *-m*, *--to-monitor* 'MONITOR_SEL' [*--follow*]::
483 Send the selected desktop to the given monitor. If *--follow* is passed, the focused desktop will stay focused.
485 *-s*, *--swap* 'DESKTOP_SEL' [*--follow*]::
486 Swap the selected desktop with the given desktop. If *--follow* is passed, the focused desktop will stay focused.
488 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
489 Set or cycle the layout of the selected desktop.
491 *-n*, *--rename* <new_name>::
492 Rename the selected desktop.
494 *-b*, *--bubble* 'CYCLE_DIR'::
495 Bubble the selected desktop in the given direction.
498 Remove the selected desktop.
506 monitor ['MONITOR_SEL'] 'COMMANDS'
508 If 'MONITOR_SEL' is omitted, *focused* is assumed.
512 *-f*, *--focus* ['MONITOR_SEL']::
513 Focus the selected or given monitor.
515 *-s*, *--swap* 'MONITOR_SEL'::
516 Swap the selected monitor with the given monitor.
518 *-a*, *--add-desktops* <name>...::
519 Create desktops with the given names in the selected monitor.
521 *-o*, *--reorder-desktops* <name>...::
522 Reorder the desktops of the selected monitor to match the given order.
524 *-d*, *--reset-desktops* <name>...::
525 Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops.
527 *-g*, *--rectangle* WxH+X+Y::
528 Set the rectangle of the selected monitor.
530 *-n*, *--rename* <new_name>::
531 Rename the selected monitor.
534 Remove the selected monitor.
542 query 'COMMANDS' ['OPTIONS']
547 The optional selectors are references.
549 *-N*, *--nodes* ['NODE_SEL']::
550 List the IDs of the matching nodes.
552 *-D*, *--desktops* ['DESKTOP_SEL']::
553 List the IDs (or names) of the matching desktops.
555 *-M*, *--monitors* ['MONITOR_SEL']::
556 List the IDs (or names) of the matching monitors.
559 Print a JSON representation of the matching item.
564 *-m*,*--monitor* ['MONITOR_SEL']::
565 *-d*,*--desktop* ['DESKTOP_SEL']::
566 *-n*, *--node* ['NODE_SEL']::
567 Constrain matches to the selected monitor, desktop or node. The descriptor can be omitted for '-M', '-D' and '-N'.
570 Print names instead of IDs. Can only be used with '-M' and '-D'.
583 *-d*, *--dump-state*::
584 Dump the current world state on standard output.
586 *-l*, *--load-state* <file_path>::
587 Load a world state from the given file. The path must be absolute.
589 *-a*, *--add-monitor* <name> WxH+X+Y::
590 Add a monitor for the given name and rectangle.
592 *-O*, *--reorder-monitors* <name>...::
593 Reorder the list of monitors to match the given order.
595 *-o*, *--adopt-orphans*::
596 Manage all the unmanaged windows remaining from a previous session.
598 *-h*, *--record-history* on|off::
599 Enable or disable the recording of node focus history.
601 *-g*, *--get-status*::
602 Print the current status information.
605 Restart the window manager
618 *-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|marked|center|follow|manage|focus|border)=(on|off)] [rectangle=WxH+X+Y]::
621 *-r*, *--remove* ^<n>|head|tail|(<class_name>|\*)[:(<instance_name>|*)]...::
622 Remove the given rules.
633 config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-n 'NODE_SEL'] <setting> [<value>]::
634 Get or set the value of <setting>.
641 subscribe ['OPTIONS'] (all|report|monitor|desktop|node|...)*::
642 Continuously print events. See the *EVENTS* section for the description of each event.
648 Print a path to a FIFO from which events can be read and return.
650 *-c*, *--count* 'COUNT'::
651 Stop the corresponding *bspc* process after having received 'COUNT' events.
660 Quit with an optional exit status.
665 If the server can't handle a message, *bspc* will return with a non-zero exit code.
669 Colors are in the form '#RRGGBB', booleans are 'true', 'on', 'false' or 'off'.
671 All the boolean settings are 'false' by default unless stated otherwise.
676 'normal_border_color'::
677 Color of the border of an unfocused window.
679 'active_border_color'::
680 Color of the border of a focused window of an unfocused monitor.
682 'focused_border_color'::
683 Color of the border of a focused window of a focused monitor.
685 'presel_feedback_color'::
686 Color of the *node --presel-{dir,ratio}* message feedback area.
692 Prefix prepended to each of the status lines.
694 'external_rules_command'::
695 Absolute path to the command used to retrieve rule consequences. The command will receive the following arguments: window ID, class name, instance name, and intermediate consequences. 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).
698 The insertion scheme used when the insertion point is in automatic mode. Accept the following values: *longest_side*, *alternate*, *spiral*.
701 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*.
703 'directional_focus_tightness'::
704 The tightness of the algorithm used to decide whether a window is on the 'DIR' side of another window. Accept the following values: *high*, *low*.
706 'removal_adjustment'::
707 Adjust the brother when unlinking a node from the tree in accordance with the automatic insertion scheme.
710 Draw the preselection feedback area. Defaults to 'true'.
712 'borderless_monocle'::
713 Remove borders of tiled windows for the *monocle* desktop layout.
716 Remove gaps of tiled windows for the *monocle* desktop layout.
718 'top_monocle_padding'::
719 'right_monocle_padding'::
720 'bottom_monocle_padding'::
721 'left_monocle_padding'::
722 Padding space added at the sides of the screen for the *monocle* desktop layout.
725 Set the desktop layout to *monocle* if there's only one tiled window in the tree.
727 'pointer_motion_interval'::
728 The minimum interval, in milliseconds, between two motion notify events.
731 Keyboard modifier used for moving or resizing windows. Accept the following values: *shift*, *control*, *lock*, *mod1*, *mod2*, *mod3*, *mod4*, *mod5*.
736 Action performed when pressing 'pointer_modifier' + 'button<n>'. Accept the following values: *move*, *resize_side*, *resize_corner*, *focus*, *none*.
739 Button used for focusing a window (or a monitor). The possible values are: *button1*, *button2*, *button3*, *any*, *none*. Defaults to *button1*.
741 'swallow_first_click'::
742 Don't replay the click that makes a window focused if 'click_to_focus' isn't *none*.
744 'focus_follows_pointer'::
745 Focus the window under the pointer.
747 'pointer_follows_focus'::
748 When focusing a window, put the pointer at its center.
750 'pointer_follows_monitor'::
751 When focusing a monitor, put the pointer at its center.
753 'mapping_events_count'::
754 Handle the next *mapping_events_count* mapping notify events. A negative value implies that every event needs to be handled.
756 'ignore_ewmh_focus'::
757 Ignore EWMH focus requests coming from applications.
759 'ignore_ewmh_fullscreen'::
760 Block the fullscreen state transitions that originate from an EWMH request. The possible values are: *none*, *all*, or a comma separated list of the following values: *enter*, *exit*.
762 'ignore_ewmh_struts'::
763 BIgnore strut hinting from clients requesting to reserve space (i.e. task bars).
765 'center_pseudo_tiled'::
766 Center pseudo tiled windows into their tiling rectangles. Defaults to 'true'.
769 Apply ICCCM window size hints.
771 'remove_disabled_monitors'::
772 Consider disabled monitors as disconnected.
774 'remove_unplugged_monitors'::
775 Remove unplugged monitors.
777 'merge_overlapping_monitors'::
778 Merge overlapping monitors (the bigger remains).
780 Monitor and Desktop Settings
781 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
787 Padding space added at the sides of the monitor or desktop.
793 Size of the gap that separates windows.
805 Focus the window (or the monitor) under the pointer if the value isn't *none*.
807 'pointer_modifier' + 'button1'::
808 Move the window under the pointer.
810 'pointer_modifier' + 'button2'::
811 Resize the window under the pointer by dragging the nearest side.
813 'pointer_modifier' + 'button3'::
814 Resize the window under the pointer by dragging the nearest corner.
816 The behavior of 'pointer_modifier' + 'button<n>' can be modified through the 'pointer_action<n>' setting.
822 See the next section for the description of the format.
824 'monitor_add <monitor_id> <monitor_name> <monitor_geometry>'::
827 'monitor_rename <monitor_id> <old_name> <new_name>'::
828 A monitor is renamed.
830 'monitor_remove <monitor_id>'::
831 A monitor is removed.
833 'monitor_swap <src_monitor_id> <dst_monitor_id>'::
834 A monitor is swapped.
836 'monitor_focus <monitor_id>'::
837 A monitor is focused.
839 'monitor_geometry <monitor_id> <monitor_geometry>'::
840 The geometry of a monitor changed.
842 'desktop_add <monitor_id> <desktop_id> <desktop_name>'::
845 'desktop_rename <monitor_id> <desktop_id> <old_name> <new_name>'::
846 A desktop is renamed.
848 'desktop_remove <monitor_id> <desktop_id>'::
849 A desktop is removed.
851 'desktop_swap <src_monitor_id> <src_desktop_id> <dst_monitor_id> <dst_desktop_id>'::
852 A desktop is swapped.
854 'desktop_transfer <src_monitor_id> <src_desktop_id> <dst_monitor_id>'::
855 A desktop is transferred.
857 'desktop_focus <monitor_id> <desktop_id>'::
858 A desktop is focused.
860 'desktop_activate <monitor_id> <desktop_id>'::
861 A desktop is activated.
863 'desktop_layout <monitor_id> <desktop_id> tiled|monocle'::
864 The layout of a desktop changed.
866 'node_add <monitor_id> <desktop_id> <ip_id> <node_id>'::
869 'node_remove <monitor_id> <desktop_id> <node_id>'::
872 'node_swap <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
875 'node_transfer <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
876 A node is transferred.
878 'node_focus <monitor_id> <desktop_id> <node_id>'::
881 'node_activate <monitor_id> <desktop_id> <node_id>'::
884 'node_presel <monitor_id> <desktop_id> <node_id> (dir DIR|ratio RATIO|cancel)'::
885 A node is preselected.
887 'node_stack <node_id_1> below|above <node_id_2>'::
888 A node is stacked below or above another node.
890 'node_geometry <monitor_id> <desktop_id> <node_id> <node_geometry>'::
891 The geometry of a window changed.
893 'node_state <monitor_id> <desktop_id> <node_id> tiled|pseudo_tiled|floating|fullscreen on|off'::
894 The state of a window changed.
896 'node_flag <monitor_id> <desktop_id> <node_id> hidden|sticky|private|locked|marked|urgent on|off'::
897 One of the flags of a node changed.
899 'node_layer <monitor_id> <desktop_id> <node_id> below|normal|above'::
900 The layer of a window changed.
902 'pointer_action <monitor_id> <desktop_id> <node_id> move|resize_corner|resize_side begin|end'::
903 A pointer action occurred.
905 Please note that *bspwm* initializes monitors before it reads messages on its socket, therefore the initial monitor events can't be received.
910 Each report event message is composed of items separated by colons.
912 Each item has the form '<type><value>' where '<type>' is the first character of the item.
921 Occupied focused desktop.
924 Occupied unfocused desktop.
927 Free focused desktop.
930 Free unfocused desktop.
933 Urgent focused desktop.
936 Urgent unfocused desktop.
939 Layout of the focused desktop of a monitor.
942 State of the focused node of a focused desktop.
945 Active flags of the focused node of a focused desktop.
947 Environment Variables
948 ---------------------
951 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'.
956 * Steven Allen <steven at stebalien.com>
957 * Thomas Adam <thomas at xteddy.org>
958 * Ivan Kanakarakis <ivan.kanak at gmail.com>
963 Bastien Dejean <nihilhill at gmail.com>