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][.[!]SPLIT_TYPE]
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 SPLIT_TYPE := horizontal|vertical
91 PATH := @[DESKTOP_SEL:][[/]JUMP](/JUMP)*
93 JUMP := first|1|second|2|brother|parent|DIR
100 Selects the window in the given (spacial) direction relative to the reference node.
103 Selects the node in the given (cyclic) direction relative to the reference node within a depth-first in-order traversal of the tree.
106 Selects the node at the given path.
109 Selects the first node that matches the given selectors.
112 Selects the first ancestor of the reference node that matches the given selectors.
115 Selects the previously focused node relative to the reference node.
118 Selects the newest node in the history of the focused node.
121 Selects the node older than the reference node in the history.
124 Selects the node newer than the reference node in the history.
127 Selects the currently focused node.
130 Selects the leaf under the pointer.
133 Selects the biggest leaf.
136 Selects the smallest leaf.
139 Selects the node with the given ID.
144 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).
147 Jumps to the first child.
150 Jumps to the second child.
153 Jumps to the brother node.
156 Jumps to the parent node.
159 Jumps to the node holding the edge in the given direction.
165 Only consider the focused node.
168 Only consider nodes that are the focused node of their desktop.
171 Only consider nodes in automatic insertion mode. See also *--presel-dir* under *Node* in the *DOMAINS* section below.
174 Only consider nodes in the reference desktop.
177 Only consider leaf nodes.
180 Only consider nodes that hold a window.
182 [!](tiled|pseudo_tiled|floating|fullscreen)::
183 Only consider windows in the given state.
186 Only consider windows that have the same class as the reference window.
189 Only consider nodes that are descendants of the reference node.
192 Only consider nodes that are ancestors of the reference node.
194 [!](hidden|sticky|private|locked|marked|urgent)::
195 Only consider windows that have the given flag set.
197 [!](below|normal|above)::
198 Only consider windows in the given layer.
200 [!](horizontal|vertical)::
201 Only consider nodes with the given split type.
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]
214 [.[!]LAYOUT][.[!]user_LAYOUT]
216 LAYOUT := tiled|monocle
223 Selects the desktop in the given direction relative to the reference desktop.
226 Selects the first desktop that matches the given selectors.
229 Selects the previously focused desktop relative to the reference desktop.
232 Selects the newest desktop in the history of the focused desktops.
235 Selects the desktop older than the reference desktop in the history.
238 Selects the desktop newer than the reference desktop in the history.
241 Selects the currently focused desktop.
244 Selects the nth desktop. If *MONITOR_SEL* is given, selects the nth desktop on the selected monitor.
247 Selects the desktop with the given ID.
250 Selects the desktop with the given name.
256 Only consider the focused desktop.
259 Only consider desktops that are the focused desktop of their monitor.
262 Only consider occupied desktops.
265 Only consider urgent desktops.
268 Only consider desktops inside the reference monitor.
271 Only consider desktops with the given layout.
273 [!](user_tiled|user_monocle)::
274 Only consider desktops which have the given layout as userLayout.
282 MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|any|last|newest|older|newer|
283 focused|pointed|primary|^<n>|
284 <monitor_id>|<monitor_name>)[.[!]focused][.[!]occupied]
291 Selects the monitor in the given (spacial) direction relative to the reference monitor.
294 Selects the monitor in the given (cyclic) direction relative to the reference monitor.
297 Selects the first monitor that matches the given selectors.
300 Selects the previously focused monitor relative to the reference monitor.
303 Selects the newest monitor in the history of the focused monitors.
306 Selects the monitor older than the reference monitor in the history.
309 Selects the monitor newer than the reference monitor in the history.
312 Selects the currently focused monitor.
315 Selects the monitor under the pointer.
318 Selects the primary monitor.
321 Selects the nth monitor.
324 Selects the monitor with the given ID.
327 Selects the monitor with the given name.
334 Only consider the focused monitor.
337 Only consider monitors where the focused desktop is occupied.
345 Its size and position are determined by the window tree.
348 A tiled window that automatically shrinks but doesn't stretch beyond its floating size.
351 Can be moved/resized freely. Although it doesn't use any tiling space, it is still part of the window tree.
354 Fills its monitor rectangle and has no borders.
361 Is hidden and doesn't occupy any tiling space.
364 Stays in the focused desktop of its monitor.
367 Tries to keep the same tiling position/size.
370 Ignores the *node --close* message.
373 Is marked (useful for deferred actions). A marked node becomes unmarked after being sent on a preselected node.
376 Has its urgency hint set. This flag is set externally.
382 There's three stacking layers: BELOW, NORMAL and ABOVE.
384 In each layer, the window are orderered as follow: tiled & pseudo-tiled < floating < fullscreen.
389 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.
401 node ['NODE_SEL'] 'COMMANDS'
403 If 'NODE_SEL' is omitted, *focused* is assumed.
407 *-f*, *--focus* ['NODE_SEL']::
408 Focus the selected or given node.
410 *-a*, *--activate* ['NODE_SEL']::
411 Activate the selected or given node.
413 *-d*, *--to-desktop* 'DESKTOP_SEL' [*--follow*]::
414 Send the selected node to the given desktop. If *--follow* is passed, the focused node will stay focused.
416 *-m*, *--to-monitor* 'MONITOR_SEL' [*--follow*]::
417 Send the selected node to the given monitor. If *--follow* is passed, the focused node will stay focused.
419 *-n*, *--to-node* 'NODE_SEL' [*--follow*]::
420 Send the selected node on the given node. If *--follow* is passed, the focused node will stay focused.
422 *-s*, *--swap* 'NODE_SEL' [*--follow*]::
423 Swap the selected node with the given node. If *--follow* is passed, the focused node will stay focused.
425 *-p*, *--presel-dir* \[~]'DIR'|cancel::
426 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".
428 *-o*, *--presel-ratio* 'RATIO'::
429 Set the splitting ratio of the preselection area.
431 *-v*, *--move* 'dx' 'dy'::
432 Move the selected window by 'dx' pixels horizontally and 'dy' pixels vertically.
434 *-z*, *--resize* top|left|bottom|right|top_left|top_right|bottom_right|bottom_left 'dx' 'dy'::
435 Resize the selected window by moving the given handle by 'dx' pixels horizontally and 'dy' pixels vertically.
437 *-r*, *--ratio* 'RATIO'|(+|-)('PIXELS'|'FRACTION')::
438 Set the splitting ratio of the selected node (0 < 'RATIO' < 1).
440 *-R*, *--rotate* '90|270|180'::
441 Rotate the tree rooted at the selected node.
443 *-F*, *--flip* 'horizontal|vertical'::
444 Flip the tree rooted at selected node.
447 Reset the split ratios of the tree rooted at the selected node to their default value.
450 Adjust the split ratios of the tree rooted at the selected node so that all windows occupy the same area.
452 *-C*, *--circulate* forward|backward::
453 Circulate the windows of the tree rooted at the selected node.
455 *-t*, *--state* \~|\[~]'STATE'::
456 Set the state of the selected window. If *\~* is present and the current state matches 'STATE', then the argument is interpreted as its last state. If the argument is just *~* with 'STATE' omitted, then the state of the selected window is set to its last state.
458 *-g*, *--flag* hidden|sticky|private|locked|marked[=on|off]::
459 Set or toggle the given flag for the selected node.
461 *-l*, *--layer* below|normal|above::
462 Set the stacking layer of the selected window.
464 *-i*, *--insert-receptacle*::
465 Insert a receptacle node at the selected node.
468 Close the windows rooted at the selected node.
471 Kill the windows rooted at the selected node.
479 desktop ['DESKTOP_SEL'] 'COMMANDS'
481 If 'DESKTOP_SEL' is omitted, *focused* is assumed.
485 *-f*, *--focus* ['DESKTOP_SEL']::
486 Focus the selected or given desktop.
488 *-a*, *--activate* ['DESKTOP_SEL']::
489 Activate the selected or given desktop.
491 *-m*, *--to-monitor* 'MONITOR_SEL' [*--follow*]::
492 Send the selected desktop to the given monitor. If *--follow* is passed, the focused desktop will stay focused.
494 *-s*, *--swap* 'DESKTOP_SEL' [*--follow*]::
495 Swap the selected desktop with the given desktop. If *--follow* is passed, the focused desktop will stay focused.
497 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
498 Set or cycle the layout of the selected desktop.
500 *-n*, *--rename* <new_name>::
501 Rename the selected desktop.
503 *-b*, *--bubble* 'CYCLE_DIR'::
504 Bubble the selected desktop in the given direction.
507 Remove the selected desktop.
515 monitor ['MONITOR_SEL'] 'COMMANDS'
517 If 'MONITOR_SEL' is omitted, *focused* is assumed.
521 *-f*, *--focus* ['MONITOR_SEL']::
522 Focus the selected or given monitor.
524 *-s*, *--swap* 'MONITOR_SEL'::
525 Swap the selected monitor with the given monitor.
527 *-a*, *--add-desktops* <name>...::
528 Create desktops with the given names in the selected monitor.
530 *-o*, *--reorder-desktops* <name>...::
531 Reorder the desktops of the selected monitor to match the given order.
533 *-d*, *--reset-desktops* <name>...::
534 Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops.
536 *-g*, *--rectangle* WxH+X+Y::
537 Set the rectangle of the selected monitor.
539 *-n*, *--rename* <new_name>::
540 Rename the selected monitor.
543 Remove the selected monitor.
551 query 'COMMANDS' ['OPTIONS']
556 The optional selectors are references.
558 *-N*, *--nodes* ['NODE_SEL']::
559 List the IDs of the matching nodes.
561 *-D*, *--desktops* ['DESKTOP_SEL']::
562 List the IDs (or names) of the matching desktops.
564 *-M*, *--monitors* ['MONITOR_SEL']::
565 List the IDs (or names) of the matching monitors.
568 Print a JSON representation of the matching item.
573 *-m*,*--monitor* ['MONITOR_SEL'|'MONITOR_MODIFIERS']::
574 *-d*,*--desktop* ['DESKTOP_SEL'|'DESKTOP_MODIFIERS']::
575 *-n*, *--node* ['NODE_SEL'|'NODE_MODIFIERS']::
576 Constrain matches to the selected monitors, desktops or nodes.
579 Print names instead of IDs. Can only be used with '-M' and '-D'.
592 *-d*, *--dump-state*::
593 Dump the current world state on standard output.
595 *-l*, *--load-state* <file_path>::
596 Load a world state from the given file. The path must be absolute.
598 *-a*, *--add-monitor* <name> WxH+X+Y::
599 Add a monitor for the given name and rectangle.
601 *-O*, *--reorder-monitors* <name>...::
602 Reorder the list of monitors to match the given order.
604 *-o*, *--adopt-orphans*::
605 Manage all the unmanaged windows remaining from a previous session.
607 *-h*, *--record-history* on|off::
608 Enable or disable the recording of node focus history.
610 *-g*, *--get-status*::
611 Print the current status information.
614 Restart the window manager
627 *-a*, *--add* (<class_name>|\*)[:(<instance_name>|\*)[:(<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]::
630 *-r*, *--remove* ^<n>|head|tail|(<class_name>|\*)[:(<instance_name>|\*)[:(<name>|*)]]...::
631 Remove the given rules.
642 config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-n 'NODE_SEL'] <setting> [<value>]::
643 Get or set the value of <setting>.
650 subscribe ['OPTIONS'] (all|report|monitor|desktop|node|...)*::
651 Continuously print events. See the *EVENTS* section for the description of each event.
657 Print a path to a FIFO from which events can be read and return.
659 *-c*, *--count* 'COUNT'::
660 Stop the corresponding *bspc* process after having received 'COUNT' events.
669 Quit with an optional exit status.
674 If the server can't handle a message, *bspc* will return with a non-zero exit code.
678 Colors are in the form '#RRGGBB', booleans are 'true', 'on', 'false' or 'off'.
680 All the boolean settings are 'false' by default unless stated otherwise.
685 'normal_border_color'::
686 Color of the border of an unfocused window.
688 'active_border_color'::
689 Color of the border of a focused window of an unfocused monitor.
691 'focused_border_color'::
692 Color of the border of a focused window of a focused monitor.
694 'presel_feedback_color'::
695 Color of the *node --presel-{dir,ratio}* message feedback area.
701 Prefix prepended to each of the status lines.
703 'external_rules_command'::
704 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).
707 The insertion scheme used when the insertion point is in automatic mode. Accept the following values: *longest_side*, *alternate*, *spiral*.
710 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*.
712 'directional_focus_tightness'::
713 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*.
715 'removal_adjustment'::
716 Adjust the brother when unlinking a node from the tree in accordance with the automatic insertion scheme.
719 Draw the preselection feedback area. Defaults to 'true'.
721 'borderless_monocle'::
722 Remove borders of tiled windows for the *monocle* desktop layout.
725 Remove gaps of tiled windows for the *monocle* desktop layout.
727 'top_monocle_padding'::
728 'right_monocle_padding'::
729 'bottom_monocle_padding'::
730 'left_monocle_padding'::
731 Padding space added at the sides of the screen for the *monocle* desktop layout.
734 Set the desktop layout to *monocle* if there's only one tiled window in the tree.
736 'borderless_singleton'::
737 Remove borders of the only window on the only monitor regardless its layout.
739 'pointer_motion_interval'::
740 The minimum interval, in milliseconds, between two motion notify events.
743 Keyboard modifier used for moving or resizing windows. Accept the following values: *shift*, *control*, *lock*, *mod1*, *mod2*, *mod3*, *mod4*, *mod5*.
748 Action performed when pressing 'pointer_modifier' + 'button<n>'. Accept the following values: *move*, *resize_side*, *resize_corner*, *focus*, *none*.
751 Button used for focusing a window (or a monitor). The possible values are: *button1*, *button2*, *button3*, *any*, *none*. Defaults to *button1*.
753 'swallow_first_click'::
754 Don't replay the click that makes a window focused if 'click_to_focus' isn't *none*.
756 'focus_follows_pointer'::
757 Focus the window under the pointer.
759 'pointer_follows_focus'::
760 When focusing a window, put the pointer at its center.
762 'pointer_follows_monitor'::
763 When focusing a monitor, put the pointer at its center.
765 'mapping_events_count'::
766 Handle the next *mapping_events_count* mapping notify events. A negative value implies that every event needs to be handled.
768 'ignore_ewmh_focus'::
769 Ignore EWMH focus requests coming from applications.
771 'ignore_ewmh_fullscreen'::
772 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*.
774 'ignore_ewmh_struts'::
775 Ignore strut hinting from clients requesting to reserve space (i.e. task bars).
777 'center_pseudo_tiled'::
778 Center pseudo tiled windows into their tiling rectangles. Defaults to 'true'.
781 Apply ICCCM window size hints.
783 'remove_disabled_monitors'::
784 Consider disabled monitors as disconnected.
786 'remove_unplugged_monitors'::
787 Remove unplugged monitors.
789 'merge_overlapping_monitors'::
790 Merge overlapping monitors (the bigger remains).
792 Monitor and Desktop Settings
793 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
799 Padding space added at the sides of the monitor or desktop.
805 Size of the gap that separates windows.
817 Focus the window (or the monitor) under the pointer if the value isn't *none*.
819 'pointer_modifier' + 'button1'::
820 Move the window under the pointer.
822 'pointer_modifier' + 'button2'::
823 Resize the window under the pointer by dragging the nearest side.
825 'pointer_modifier' + 'button3'::
826 Resize the window under the pointer by dragging the nearest corner.
828 The behavior of 'pointer_modifier' + 'button<n>' can be modified through the 'pointer_action<n>' setting.
834 See the next section for the description of the format.
836 'monitor_add <monitor_id> <monitor_name> <monitor_geometry>'::
839 'monitor_rename <monitor_id> <old_name> <new_name>'::
840 A monitor is renamed.
842 'monitor_remove <monitor_id>'::
843 A monitor is removed.
845 'monitor_swap <src_monitor_id> <dst_monitor_id>'::
846 A monitor is swapped.
848 'monitor_focus <monitor_id>'::
849 A monitor is focused.
851 'monitor_geometry <monitor_id> <monitor_geometry>'::
852 The geometry of a monitor changed.
854 'desktop_add <monitor_id> <desktop_id> <desktop_name>'::
857 'desktop_rename <monitor_id> <desktop_id> <old_name> <new_name>'::
858 A desktop is renamed.
860 'desktop_remove <monitor_id> <desktop_id>'::
861 A desktop is removed.
863 'desktop_swap <src_monitor_id> <src_desktop_id> <dst_monitor_id> <dst_desktop_id>'::
864 A desktop is swapped.
866 'desktop_transfer <src_monitor_id> <src_desktop_id> <dst_monitor_id>'::
867 A desktop is transferred.
869 'desktop_focus <monitor_id> <desktop_id>'::
870 A desktop is focused.
872 'desktop_activate <monitor_id> <desktop_id>'::
873 A desktop is activated.
875 'desktop_layout <monitor_id> <desktop_id> tiled|monocle'::
876 The layout of a desktop changed.
878 'node_add <monitor_id> <desktop_id> <ip_id> <node_id>'::
881 'node_remove <monitor_id> <desktop_id> <node_id>'::
884 'node_swap <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
887 'node_transfer <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
888 A node is transferred.
890 'node_focus <monitor_id> <desktop_id> <node_id>'::
893 'node_activate <monitor_id> <desktop_id> <node_id>'::
896 'node_presel <monitor_id> <desktop_id> <node_id> (dir DIR|ratio RATIO|cancel)'::
897 A node is preselected.
899 'node_stack <node_id_1> below|above <node_id_2>'::
900 A node is stacked below or above another node.
902 'node_geometry <monitor_id> <desktop_id> <node_id> <node_geometry>'::
903 The geometry of a window changed.
905 'node_state <monitor_id> <desktop_id> <node_id> tiled|pseudo_tiled|floating|fullscreen on|off'::
906 The state of a window changed.
908 'node_flag <monitor_id> <desktop_id> <node_id> hidden|sticky|private|locked|marked|urgent on|off'::
909 One of the flags of a node changed.
911 'node_layer <monitor_id> <desktop_id> <node_id> below|normal|above'::
912 The layer of a window changed.
914 'pointer_action <monitor_id> <desktop_id> <node_id> move|resize_corner|resize_side begin|end'::
915 A pointer action occurred.
917 Please note that *bspwm* initializes monitors before it reads messages on its socket, therefore the initial monitor events can't be received.
922 Each report event message is composed of items separated by colons.
924 Each item has the form '<type><value>' where '<type>' is the first character of the item.
933 Occupied focused desktop.
936 Occupied unfocused desktop.
939 Free focused desktop.
942 Free unfocused desktop.
945 Urgent focused desktop.
948 Urgent unfocused desktop.
951 Layout of the focused desktop of a monitor.
954 State of the focused node of a focused desktop.
957 Active flags of the focused node of a focused desktop.
959 Environment Variables
960 ---------------------
963 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'.
968 * Steven Allen <steven at stebalien.com>
969 * Thomas Adam <thomas at xteddy.org>
970 * Ivan Kanakarakis <ivan.kanak at gmail.com>
975 Bastien Dejean <nihilhill at gmail.com>