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|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 previously focused node relative to the reference node.
113 Selects the newest node in the history of the focused node.
116 Selects the node older than the reference node in the history.
119 Selects the node newer than the reference node in the history.
122 Selects the currently focused node.
125 Selects the window under the pointer.
128 Selects the biggest window.
131 Selects the smallest window.
134 Selects the node with the given ID.
139 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).
142 Jumps to the first child.
145 Jumps to the second child.
148 Jumps to the brother node.
151 Jumps to the parent node.
154 Jumps to the node holding the edge in the given direction.
162 Only consider the focused node.
165 Only consider nodes that are the focused node of their desktop.
168 Only consider nodes in automatic insertion mode. See also *--presel-dir* under *Node* in the *DOMAINS* section below.
171 Only consider nodes in the reference desktop.
174 Only consider leaf nodes.
177 Only consider nodes that hold a window.
179 [!](tiled|pseudo_tiled|floating|fullscreen)::
180 Only consider windows in the given state.
183 Only consider windows that have the same class as the reference window.
186 Only consider nodes that are descendants of the reference node.
189 Only consider nodes that are ancestors of the reference node.
191 [!](hidden|sticky|private|locked|marked|urgent)::
192 Only consider windows that have the given flag set.
194 [!](below|normal|above)::
195 Only consider windows in the given layer.
203 DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|any|last|newest|older|newer|
204 [MONITOR_SEL:](focused|^<n>)|
205 <desktop_id>|<desktop_name>)[.[!]focused][.[!]active]
206 [.[!]occupied][.[!]urgent][.[!]local]
213 Selects the desktop in the given direction relative to the reference desktop.
216 Selects the first desktop that matches the given selectors.
219 Selects the previously focused desktop relative to the reference desktop.
222 Selects the newest desktop in the history of the focused desktops.
225 Selects the desktop older than the reference desktop in the history.
228 Selects the desktop newer than the reference desktop in the history.
231 Selects the currently focused desktop.
234 Selects the nth desktop. If *MONITOR_SEL* is given, selects the nth desktop on the selected monitor.
237 Selects the desktop with the given ID.
240 Selects the desktop with the given name.
246 Only consider the focused desktop.
249 Only consider desktops that are the focused desktop of their monitor.
252 Only consider occupied desktops.
255 Only consider urgent desktops.
258 Only consider desktops inside the reference monitor.
266 MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|any|last|newest|older|newer|
267 focused|pointed|primary|^<n>|
268 <monitor_id>|<monitor_name>)[.[!]focused][.[!]occupied]
275 Selects the monitor in the given (spacial) direction relative to the reference monitor.
278 Selects the monitor in the given (cyclic) direction relative to the reference monitor.
281 Selects the first monitor that matches the given selectors.
284 Selects the previously focused monitor relative to the reference monitor.
287 Selects the newest monitor in the history of the focused monitors.
290 Selects the monitor older than the reference monitor in the history.
293 Selects the monitor newer than the reference monitor in the history.
296 Selects the currently focused monitor.
299 Selects the monitor under the pointer.
302 Selects the primary monitor.
305 Selects the nth monitor.
308 Selects the monitor with the given ID.
311 Selects the monitor with the given name.
318 Only consider the focused monitor.
321 Only consider monitors where the focused desktop is occupied.
329 Its size and position are determined by the splitting type and ratio of each node of its path in the window tree.
332 Has an unrestricted size while being centered in its tiling space.
335 Can be moved/resized freely. Although it doesn't occupy any tiling space, it is still part of the window tree.
338 Fills its monitor rectangle and has no borders. It is send in the ABOVE layer by default.
345 Is hidden and doesn't occupy any tiling space.
348 Stays in the focused desktop of its monitor.
351 Tries to keep the same tiling position/size.
354 Ignores the *node --close* message.
357 Is marked (useful for deferred actions). A marked node becomes unmarked after being sent on a preselected node.
360 Has its urgency hint set. This flag is set externally.
366 There's three stacking layers: BELOW, NORMAL and ABOVE.
368 In each layer, the window are orderered as follow: tiled & pseudo-tiled < floating < fullscreen.
373 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.
385 node ['NODE_SEL'] 'COMMANDS'
387 If 'NODE_SEL' is omitted, *focused* is assumed.
391 *-f*, *--focus* ['NODE_SEL']::
392 Focus the selected or given node.
394 *-a*, *--activate* ['NODE_SEL']::
395 Activate the selected or given node.
397 *-d*, *--to-desktop* 'DESKTOP_SEL' [*--follow*]::
398 Send the selected node to the given desktop. If *--follow* is passed, the focused node will stay focused.
400 *-m*, *--to-monitor* 'MONITOR_SEL' [*--follow*]::
401 Send the selected node to the given monitor. If *--follow* is passed, the focused node will stay focused.
403 *-n*, *--to-node* 'NODE_SEL' [*--follow*]::
404 Send the selected node on the given node. If *--follow* is passed, the focused node will stay focused.
406 *-s*, *--swap* 'NODE_SEL' [*--follow*]::
407 Swap the selected node with the given node. If *--follow* is passed, the focused node will stay focused.
409 *-p*, *--presel-dir* \[~]'DIR'|cancel::
410 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".
412 *-o*, *--presel-ratio* 'RATIO'::
413 Set the splitting ratio of the preselection area.
415 *-v*, *--move* 'dx' 'dy'::
416 Move the selected window by 'dx' pixels horizontally and 'dy' pixels vertically.
418 *-z*, *--resize* top|left|bottom|right|top_left|top_right|bottom_right|bottom_left 'dx' 'dy'::
419 Resize the selected window by moving the given handle by 'dx' pixels horizontally and 'dy' pixels vertically.
421 *-r*, *--ratio* 'RATIO'|(+|-)('PIXELS'|'FRACTION')::
422 Set the splitting ratio of the selected node (0 < 'RATIO' < 1).
424 *-R*, *--rotate* '90|270|180'::
425 Rotate the tree rooted at the selected node.
427 *-F*, *--flip* 'horizontal|vertical'::
428 Flip the the tree rooted at selected node.
431 Reset the split ratios of the tree rooted at the selected node to their default value.
434 Adjust the split ratios of the tree rooted at the selected node so that all windows occupy the same area.
436 *-C*, *--circulate* forward|backward::
437 Circulate the windows of the tree rooted at the selected node.
439 *-t*, *--state* [~](tiled|pseudo_tiled|floating|fullscreen)::
440 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.
442 *-g*, *--flag* hidden|sticky|private|locked|marked[=on|off]::
443 Set or toggle the given flag for the selected node.
445 *-l*, *--layer* below|normal|above::
446 Set the stacking layer of the selected window.
448 *-i*, *--insert-receptacle*::
449 Insert a receptacle node at the selected node.
452 Close the windows rooted at the selected node.
455 Kill the windows rooted at the selected node.
463 desktop ['DESKTOP_SEL'] 'COMMANDS'
465 If 'DESKTOP_SEL' is omitted, *focused* is assumed.
469 *-f*, *--focus* ['DESKTOP_SEL']::
470 Focus the selected or given desktop.
472 *-a*, *--activate* ['DESKTOP_SEL']::
473 Activate the selected or given desktop.
475 *-m*, *--to-monitor* 'MONITOR_SEL' [*--follow*]::
476 Send the selected desktop to the given monitor. If *--follow* is passed, the focused desktop will stay focused.
478 *-s*, *--swap* 'DESKTOP_SEL' [*--follow*]::
479 Swap the selected desktop with the given desktop. If *--follow* is passed, the focused desktop will stay focused.
481 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
482 Set or cycle the layout of the selected desktop.
484 *-n*, *--rename* <new_name>::
485 Rename the selected desktop.
487 *-b*, *--bubble* 'CYCLE_DIR'::
488 Bubble the selected desktop in the given direction.
491 Remove the selected desktop.
499 monitor ['MONITOR_SEL'] 'COMMANDS'
501 If 'MONITOR_SEL' is omitted, *focused* is assumed.
505 *-f*, *--focus* ['MONITOR_SEL']::
506 Focus the selected or given monitor.
508 *-s*, *--swap* 'MONITOR_SEL'::
509 Swap the selected monitor with the given monitor.
511 *-a*, *--add-desktops* <name>...::
512 Create desktops with the given names in the selected monitor.
514 *-o*, *--reorder-desktops* <name>...::
515 Reorder the desktops of the selected monitor to match the given order.
517 *-d*, *--reset-desktops* <name>...::
518 Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops.
520 *-g*, *--rectangle* WxH+X+Y::
521 Set the rectangle of the selected monitor.
523 *-n*, *--rename* <new_name>::
524 Rename the selected monitor.
527 Remove the selected monitor.
535 query 'COMMANDS' ['OPTIONS']
540 The optional selectors are references.
542 *-N*, *--nodes* ['NODE_SEL']::
543 List the IDs of the matching nodes.
545 *-D*, *--desktops* ['DESKTOP_SEL']::
546 List the IDs (or names) of the matching desktops.
548 *-M*, *--monitors* ['MONITOR_SEL']::
549 List the IDs (or names) of the matching monitors.
552 Print a JSON representation of the matching item.
557 *-m*,*--monitor* ['MONITOR_SEL']::
558 *-d*,*--desktop* ['DESKTOP_SEL']::
559 *-n*, *--node* ['NODE_SEL']::
560 Constrain matches to the selected monitor, desktop or node. The descriptor can be omitted for '-M', '-D' and '-N'.
563 Print names instead of IDs. Can only be used with '-M' and '-D'.
576 *-d*, *--dump-state*::
577 Dump the current world state on standard output.
579 *-l*, *--load-state* <file_path>::
580 Load a world state from the given file. The path must be absolute.
582 *-a*, *--add-monitor* <name> WxH+X+Y::
583 Add a monitor for the given name and rectangle.
585 *-O*, *--reorder-monitors* <name>...::
586 Reorder the list of monitors to match the given order.
588 *-o*, *--adopt-orphans*::
589 Manage all the unmanaged windows remaining from a previous session.
591 *-h*, *--record-history* on|off::
592 Enable or disable the recording of node focus history.
594 *-g*, *--get-status*::
595 Print the current status information.
608 *-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]::
611 *-r*, *--remove* ^<n>|head|tail|(<class_name>|\*)[:(<instance_name>|*)]...::
612 Remove the given rules.
623 config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-n 'NODE_SEL'] <setting> [<value>]::
624 Get or set the value of <setting>.
631 subscribe ['OPTIONS'] (all|report|monitor|desktop|node|...)*::
632 Continuously print events. See the *EVENTS* section for the description of each event.
638 Print a path to a FIFO from which events can be read and return.
640 *-c*, *--count* 'COUNT'::
641 Stop the corresponding *bspc* process after having received 'COUNT' events.
650 Quit with an optional exit status.
655 If the server can't handle a message, *bspc* will return with a non-zero exit code.
659 Colors are in the form '#RRGGBB', booleans are 'true', 'on', 'false' or 'off'.
661 All the boolean settings are 'false' by default unless stated otherwise.
666 'normal_border_color'::
667 Color of the border of an unfocused window.
669 'active_border_color'::
670 Color of the border of a focused window of an unfocused monitor.
672 'focused_border_color'::
673 Color of the border of a focused window of a focused monitor.
675 'presel_feedback_color'::
676 Color of the *node --presel-{dir,ratio}* message feedback area.
682 Prefix prepended to each of the status lines.
684 'external_rules_command'::
685 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).
688 The insertion scheme used when the insertion point is in automatic mode. Accept the following values: *longest_side*, *alternate*, *spiral*.
691 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*.
693 'directional_focus_tightness'::
694 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*.
696 'removal_adjustment'::
697 Adjust the brother when unlinking a node from the tree in accordance with the automatic insertion scheme.
699 'borderless_monocle'::
700 Remove borders of tiled windows for the *monocle* desktop layout.
703 Remove gaps of tiled windows for the *monocle* desktop layout.
705 'top_monocle_padding'::
706 'right_monocle_padding'::
707 'bottom_monocle_padding'::
708 'left_monocle_padding'::
709 Padding space added at the sides of the screen for the *monocle* desktop layout.
712 Set the desktop layout to *monocle* if there's only one tiled window in the tree.
714 'pointer_motion_interval'::
715 The minimum interval, in milliseconds, between two motion notify events.
718 Keyboard modifier used for moving or resizing windows. Accept the following values: *shift*, *control*, *lock*, *mod1*, *mod2*, *mod3*, *mod4*, *mod5*.
723 Action performed when pressing 'pointer_modifier' + 'button<n>'. Accept the following values: *move*, *resize_side*, *resize_corner*, *focus*, *none*.
726 Button used for focusing a window (or a monitor). The possible values are: *button1*, *button2*, *button3*, *any*, *none*. Defaults to *button1*.
728 'swallow_first_click'::
729 Don't replay the click that makes a window focused if 'click_to_focus' isn't *none*.
731 'focus_follows_pointer'::
732 Focus the window under the pointer.
734 'pointer_follows_focus'::
735 When focusing a window, put the pointer at its center.
737 'pointer_follows_monitor'::
738 When focusing a monitor, put the pointer at its center.
740 'mapping_events_count'::
741 Handle the next *mapping_events_count* mapping notify events. A negative value implies that every event needs to be handled.
743 'ignore_ewmh_focus'::
744 Ignore EWMH focus requests coming from applications.
746 'ignore_ewmh_fullscreen'::
747 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*.
749 'center_pseudo_tiled'::
750 Center pseudo tiled windows into their tiling rectangles. Defaults to 'true'.
753 Apply ICCCM window size hints.
755 'remove_disabled_monitors'::
756 Consider disabled monitors as disconnected.
758 'remove_unplugged_monitors'::
759 Remove unplugged monitors.
761 'merge_overlapping_monitors'::
762 Merge overlapping monitors (the bigger remains).
764 Monitor and Desktop Settings
765 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
771 Padding space added at the sides of the monitor or desktop.
777 Size of the gap that separates windows.
789 Focus the window (or the monitor) under the pointer if the value isn't *none*.
791 'pointer_modifier' + 'button1'::
792 Move the window under the pointer.
794 'pointer_modifier' + 'button2'::
795 Resize the window under the pointer by dragging the nearest side.
797 'pointer_modifier' + 'button3'::
798 Resize the window under the pointer by dragging the nearest corner.
800 The behavior of 'pointer_modifier' + 'button<n>' can be modified through the 'pointer_action<n>' setting.
806 See the next section for the description of the format.
808 'monitor_add <monitor_id> <monitor_name> <monitor_geometry>'::
811 'monitor_rename <monitor_id> <old_name> <new_name>'::
812 A monitor is renamed.
814 'monitor_remove <monitor_id>'::
815 A monitor is removed.
817 'monitor_swap <src_monitor_id> <dst_monitor_id>'::
818 A monitor is swapped.
820 'monitor_focus <monitor_id>'::
821 A monitor is focused.
823 'monitor_geometry <monitor_id> <monitor_geometry>'::
824 The geometry of a monitor changed.
826 'desktop_add <monitor_id> <desktop_id> <desktop_name>'::
829 'desktop_rename <monitor_id> <desktop_id> <old_name> <new_name>'::
830 A desktop is renamed.
832 'desktop_remove <monitor_id> <desktop_id>'::
833 A desktop is removed.
835 'desktop_swap <src_monitor_id> <src_desktop_id> <dst_monitor_id> <dst_desktop_id>'::
836 A desktop is swapped.
838 'desktop_transfer <src_monitor_id> <src_desktop_id> <dst_monitor_id>'::
839 A desktop is transferred.
841 'desktop_focus <monitor_id> <desktop_id>'::
842 A desktop is focused.
844 'desktop_activate <monitor_id> <desktop_id>'::
845 A desktop is activated.
847 'desktop_layout <monitor_id> <desktop_id> tiled|monocle'::
848 The layout of a desktop changed.
850 'node_add <monitor_id> <desktop_id> <ip_id> <node_id>'::
853 'node_remove <monitor_id> <desktop_id> <node_id>'::
856 'node_swap <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
859 'node_transfer <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
860 A node is transferred.
862 'node_focus <monitor_id> <desktop_id> <node_id>'::
865 'node_activate <monitor_id> <desktop_id> <node_id>'::
868 'node_presel <monitor_id> <desktop_id> <node_id> (dir DIR|ratio RATIO|cancel)'::
869 A node is preselected.
871 'node_stack <node_id_1> below|above <node_id_2>'::
872 A node is stacked below or above another node.
874 'node_geometry <monitor_id> <desktop_id> <node_id> <node_geometry>'::
875 The geometry of a window changed.
877 'node_state <monitor_id> <desktop_id> <node_id> tiled|pseudo_tiled|floating|fullscreen on|off'::
878 The state of a window changed.
880 'node_flag <monitor_id> <desktop_id> <node_id> hidden|sticky|private|locked|marked|urgent on|off'::
881 One of the flags of a node changed.
883 'node_layer <monitor_id> <desktop_id> <node_id> below|normal|above'::
884 The layer of a window changed.
886 'pointer_action <monitor_id> <desktop_id> <node_id> move|resize_corner|resize_side begin|end'::
887 A pointer action occured.
889 Please note that *bspwm* initializes monitors before it reads messages on its socket, therefore the initial monitor events can't be received.
894 Each report event message is composed of items separated by colons.
896 Each item has the form '<type><value>' where '<type>' is the first character of the item.
905 Occupied focused desktop.
908 Occupied unfocused desktop.
911 Free focused desktop.
914 Free unfocused desktop.
917 Urgent focused desktop.
920 Urgent unfocused desktop.
923 Layout of the focused desktop of a monitor.
926 State of the focused node of a focused desktop.
929 Active flags of the focused node of a focused desktop.
931 Environment Variables
932 ---------------------
935 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'.
940 * Steven Allen <steven at stebalien.com>
941 * Thomas Adam <thomas at xteddy.org>
942 * Ivan Kanakarakis <ivan.kanak at gmail.com>
947 Bastien Dejean <nihilhill at gmail.com>