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|
79 biggest|<node_id>)[.[!]focused][.[!]automatic][.[!]local][.[!]active]
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 node with the given ID.
136 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).
139 Jumps to the first child.
142 Jumps to the second child.
145 Jumps to the brother node.
148 Jumps to the parent node.
151 Jumps to the node holding the edge in the given direction.
157 Only consider focused or unfocused nodes.
160 Only consider nodes in automatic or manual insertion mode. See also *--presel-dir* under *Node* in the *DOMAINS* section below.
163 Only consider nodes in or not in the reference desktop.
166 Only consider nodes in or not in the active desktop of their monitor.
169 Only consider leaves or internal nodes.
172 Only consider nodes that hold or don't hold a window.
174 [!](tiled|pseudo_tiled|floating|fullscreen)::
175 Only consider windows in or not in the given state.
178 Only consider windows that have or don't have the same class as the reference window.
181 Only consider nodes that are or aren't descendants of the reference node.
184 Only consider nodes that are or aren't ancestors of the reference node.
186 [!](hidden|sticky|private|locked|marked|urgent)::
187 Only consider windows that have or don't have the given flag set.
189 [!](below|normal|above)::
190 Only consider windows in or not in the given layer.
198 DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|any|last|newest|older|newer|
199 [MONITOR_SEL:](focused|^<n>)|
200 <desktop_id>|<desktop_name>)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
207 Selects the desktop in the given direction relative to the reference desktop.
210 Selects the first desktop that matches the given selectors.
213 Selects the previously focused desktop relative to the reference desktop.
216 Selects the newest desktop in the history of the focused desktops.
219 Selects the desktop older than the reference desktop in the history.
222 Selects the desktop newer than the reference desktop in the history.
225 Selects the currently focused desktop.
228 Selects the nth desktop. If *MONITOR_SEL* is given, selects the nth desktop on the selected monitor.
231 Selects the desktop with the given ID.
234 Selects the desktop with the given name.
240 Only consider occupied or free desktops.
243 Only consider focused or unfocused desktops.
246 Only consider urgent or non urgent desktops.
249 Only consider desktops inside or outside of the reference monitor.
257 MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|any|last|newest|older|newer|
258 focused|pointed|primary|^<n>|
259 <monitor_id>|<monitor_name>)[.[!]occupied][.[!]focused]
266 Selects the monitor in the given (spacial) direction relative to the reference monitor.
269 Selects the monitor in the given (cyclic) direction relative to the reference monitor.
272 Selects the first monitor that matches the given selectors.
275 Selects the previously focused monitor relative to the reference monitor.
278 Selects the newest monitor in the history of the focused monitors.
281 Selects the monitor older than the reference monitor in the history.
284 Selects the monitor newer than the reference monitor in the history.
287 Selects the currently focused monitor.
290 Selects the monitor under the pointer.
293 Selects the primary monitor.
296 Selects the nth monitor.
299 Selects the monitor with the given ID.
302 Selects the monitor with the given name.
309 Only consider monitors where the focused desktop is occupied or free.
312 Only consider focused or unfocused monitors.
319 Its size and position are determined by the splitting type and ratio of each node of its path in the window tree.
322 Has an unrestricted size while being centered in its tiling space.
325 Can be moved/resized freely. Although it doesn't occupy any tiling space, it is still part of the window tree.
328 Fills its monitor rectangle and has no borders. It is send in the ABOVE layer by default.
335 Is hidden and doesn't occupy any tiling space.
338 Stays in the focused desktop of its monitor.
341 Tries to keep the same tiling position/size.
344 Ignores the *node --close* message.
347 Is marked (useful for deferred actions). A marked node becomes unmarked after being sent on a preselected node.
350 Has its urgency hint set. This flag is set externally.
356 There's three stacking layers: BELOW, NORMAL and ABOVE.
358 In each layer, the window are orderered as follow: tiled & pseudo-tiled < fullscreen < floating.
363 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 and preselected. 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.
375 node ['NODE_SEL'] 'COMMANDS'
377 If 'NODE_SEL' is omitted, *focused* is assumed.
381 *-f*, *--focus* ['NODE_SEL']::
382 Focus the selected or given node.
384 *-a*, *--activate* ['NODE_SEL']::
385 Activate the selected or given node.
387 *-d*, *--to-desktop* 'DESKTOP_SEL' [*--follow*]::
388 Send the selected node to the given desktop. If *--follow* is passed, the focused node will stay focused.
390 *-m*, *--to-monitor* 'MONITOR_SEL' [*--follow*]::
391 Send the selected node to the given monitor. If *--follow* is passed, the focused node will stay focused.
393 *-n*, *--to-node* 'NODE_SEL' [*--follow*]::
394 Send the selected node on the given node. If *--follow* is passed, the focused node will stay focused.
396 *-s*, *--swap* 'NODE_SEL' [*--follow*]::
397 Swap the selected node with the given node. If *--follow* is passed, the focused node will stay focused.
399 *-p*, *--presel-dir* \[~]'DIR'|cancel::
400 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".
402 *-o*, *--presel-ratio* 'RATIO'::
403 Set the splitting ratio of the preselection area.
405 *-v*, *--move* 'dx' 'dy'::
406 Move the selected window by 'dx' pixels horizontally and 'dy' pixels vertically.
408 *-z*, *--resize* top|left|bottom|right|top_left|top_right|bottom_right|bottom_left 'dx' 'dy'::
409 Resize the selected window by moving the given handle by 'dx' pixels horizontally and 'dy' pixels vertically.
411 *-r*, *--ratio* 'RATIO'|(+|-)('PIXELS'|'FRACTION')::
412 Set the splitting ratio of the selected node (0 < 'RATIO' < 1).
414 *-R*, *--rotate* '90|270|180'::
415 Rotate the tree rooted at the selected node.
417 *-F*, *--flip* 'horizontal|vertical'::
418 Flip the the tree rooted at selected node.
421 Reset the split ratios of the tree rooted at the selected node to their default value.
424 Adjust the split ratios of the tree rooted at the selected node so that all windows occupy the same area.
426 *-C*, *--circulate* forward|backward::
427 Circulate the windows of the tree rooted at the selected node.
429 *-t*, *--state* [~](tiled|pseudo_tiled|floating|fullscreen)::
430 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.
432 *-g*, *--flag* hidden|sticky|private|locked|marked[=on|off]::
433 Set or toggle the given flag for the selected node.
435 *-l*, *--layer* below|normal|above::
436 Set the stacking layer of the selected window.
438 *-i*, *--insert-receptacle*::
439 Insert a receptacle node at the selected node.
442 Close the windows rooted at the selected node.
445 Kill the windows rooted at the selected node.
453 desktop ['DESKTOP_SEL'] 'COMMANDS'
455 If 'DESKTOP_SEL' is omitted, *focused* is assumed.
459 *-f*, *--focus* ['DESKTOP_SEL']::
460 Focus the selected or given desktop.
462 *-a*, *--activate* ['DESKTOP_SEL']::
463 Activate the selected or given desktop.
465 *-m*, *--to-monitor* 'MONITOR_SEL' [*--follow*]::
466 Send the selected desktop to the given monitor. If *--follow* is passed, the focused desktop will stay focused.
468 *-s*, *--swap* 'DESKTOP_SEL' [*--follow*]::
469 Swap the selected desktop with the given desktop. If *--follow* is passed, the focused desktop will stay focused.
471 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
472 Set or cycle the layout of the selected desktop.
474 *-n*, *--rename* <new_name>::
475 Rename the selected desktop.
477 *-b*, *--bubble* 'CYCLE_DIR'::
478 Bubble the selected desktop in the given direction.
481 Remove the selected desktop.
489 monitor ['MONITOR_SEL'] 'COMMANDS'
491 If 'MONITOR_SEL' is omitted, *focused* is assumed.
495 *-f*, *--focus* ['MONITOR_SEL']::
496 Focus the selected or given monitor.
498 *-s*, *--swap* 'MONITOR_SEL'::
499 Swap the selected monitor with the given monitor.
501 *-a*, *--add-desktops* <name>...::
502 Create desktops with the given names in the selected monitor.
504 *-o*, *--reorder-desktops* <name>...::
505 Reorder the desktops of the selected monitor to match the given order.
507 *-d*, *--reset-desktops* <name>...::
508 Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops.
510 *-g*, *--rectangle* WxH+X+Y::
511 Set the rectangle of the selected monitor.
513 *-n*, *--rename* <new_name>::
514 Rename the selected monitor.
517 Remove the selected monitor.
525 query 'COMMANDS' ['OPTIONS']
530 The optional selectors are references.
532 *-N*, *--nodes* ['NODE_SEL']::
533 List the IDs of the matching nodes.
535 *-D*, *--desktops* ['DESKTOP_SEL']::
536 List the IDs (or names) of the matching desktops.
538 *-M*, *--monitors* ['MONITOR_SEL']::
539 List the IDs (or names) of the matching monitors.
542 Print a JSON representation of the matching item.
547 *-m*,*--monitor* ['MONITOR_SEL']::
548 *-d*,*--desktop* ['DESKTOP_SEL']::
549 *-n*, *--node* ['NODE_SEL']::
550 Constrain matches to the selected monitor, desktop or node. The descriptor can be omitted for '-M', '-D' and '-N'.
553 Print names instead of IDs. Can only be used with '-M' and '-D'.
566 *-d*, *--dump-state*::
567 Dump the current world state on standard output.
569 *-l*, *--load-state* <file_path>::
570 Load a world state from the given file.
572 *-a*, *--add-monitor* <name> WxH+X+Y::
573 Add a monitor for the given name and rectangle.
575 *-O*, *--reorder-monitors* <name>...::
576 Reorder the list of monitors to match the given order.
578 *-o*, *--adopt-orphans*::
579 Manage all the unmanaged windows remaining from a previous session.
581 *-h*, *--record-history* on|off::
582 Enable or disable the recording of node focus history.
584 *-g*, *--get-status*::
585 Print the current status information.
598 *-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]::
601 *-r*, *--remove* ^<n>|head|tail|(<class_name>|\*)[:(<instance_name>|*)]...::
602 Remove the given rules.
613 config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-n 'NODE_SEL'] <setting> [<value>]::
614 Get or set the value of <setting>.
621 subscribe ['OPTIONS'] (all|report|monitor|desktop|node|...)*::
622 Continuously print events. See the *EVENTS* section for the description of each event.
628 Print a path to a FIFO from which events can be read and return.
630 *-c*, *--count* 'COUNT'::
631 Stop the corresponding *bspc* process after having received 'COUNT' events.
640 Quit with an optional exit status.
645 If the server can't handle a message, *bspc* will return with a non-zero exit code.
649 Colors are in the form '#RRGGBB', booleans are 'true', 'on', 'false' or 'off'.
651 All the boolean settings are 'false' by default unless stated otherwise.
656 'normal_border_color'::
657 Color of the border of an unfocused window.
659 'active_border_color'::
660 Color of the border of a focused window of an unfocused monitor.
662 'focused_border_color'::
663 Color of the border of a focused window of a focused monitor.
665 'presel_feedback_color'::
666 Color of the *node --presel-{dir,ratio}* message feedback area.
672 Prefix prepended to each of the status lines.
674 'external_rules_command'::
675 External 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).
678 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*.
680 'directional_focus_tightness'::
681 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*.
683 'borderless_monocle'::
684 Remove borders of tiled windows for the *monocle* desktop layout.
687 Remove gaps of tiled windows for the *monocle* desktop layout.
689 'paddingless_monocle'::
690 Remove padding space for the *monocle* desktop layout.
693 Set the desktop layout to *monocle* if there's only one tiled window in the tree.
695 'pointer_motion_interval'::
696 The minimum interval, in milliseconds, between two motion notify events.
699 Keyboard modifier used for moving or resizing windows. Accept the following values: *shift*, *control*, *lock*, *mod1*, *mod2*, *mod3*, *mod4*, *mod5*.
704 Action performed when pressing 'pointer_modifier' + 'button<n>'. Accept the following values: *move*, *resize_side*, *resize_corner*, *focus*, *none*.
707 Button used for focusing a window (or a monitor). The possible values are: *button1*, *button2*, *button3*, *any*, *none*.
709 'swallow_first_click'::
710 Don't replay the click that makes a window focused if 'click_to_focus' isn't *none*.
712 'focus_follows_pointer'::
713 Focus the window under the pointer.
715 'pointer_follows_focus'::
716 When focusing a window, put the pointer at its center.
718 'pointer_follows_monitor'::
719 When focusing a monitor, put the pointer at its center.
721 'mapping_events_count'::
722 Handle the next *mapping_events_count* mapping notify events. A negative value implies that every event needs to be handled.
724 'ignore_ewmh_focus'::
725 Ignore EWMH focus requests coming from applications.
727 'center_pseudo_tiled'::
728 Center pseudo tiled windows into their tiling rectangles. Defaults to 'true'.
731 Apply ICCCM window size hints.
733 'remove_disabled_monitors'::
734 Consider disabled monitors as disconnected.
736 'remove_unplugged_monitors'::
737 Remove unplugged monitors.
739 'merge_overlapping_monitors'::
740 Merge overlapping monitors (the bigger remains).
742 Monitor and Desktop Settings
743 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
749 Padding space added at the sides of the monitor or desktop.
755 Size of the gap that separates windows.
767 Focus the window (or the monitor) under the pointer if the value isn't *none*.
769 'pointer_modifier' + 'button1'::
770 Move the window under the pointer.
772 'pointer_modifier' + 'button2'::
773 Resize the window under the pointer by dragging the nearest side.
775 'pointer_modifier' + 'button3'::
776 Resize the window under the pointer by dragging the nearest corner.
778 The behavior of 'pointer_modifier' + 'button<n>' can be modified through the 'pointer_action<n>' setting.
784 See the next section for the description of the format.
786 'monitor_add <monitor_id> <monitor_name> <monitor_geometry>'::
789 'monitor_rename <monitor_id> <old_name> <new_name>'::
790 A monitor is renamed.
792 'monitor_remove <monitor_id>'::
793 A monitor is removed.
795 'monitor_swap <src_monitor_id> <dst_monitor_id>'::
796 A monitor is swapped.
798 'monitor_focus <monitor_id>'::
799 A monitor is focused.
801 'monitor_geometry <monitor_id> <monitor_geometry>'::
802 The geometry of a monitor changed.
804 'desktop_add <monitor_id> <desktop_id> <desktop_name>'::
807 'desktop_rename <monitor_id> <desktop_id> <old_name> <new_name>'::
808 A desktop is renamed.
810 'desktop_remove <monitor_id> <desktop_id>'::
811 A desktop is removed.
813 'desktop_swap <src_monitor_id> <src_desktop_id> <dst_monitor_id> <dst_desktop_id>'::
814 A desktop is swapped.
816 'desktop_transfer <src_monitor_id> <src_desktop_id> <dst_monitor_id>'::
817 A desktop is transferred.
819 'desktop_focus <monitor_id> <desktop_id>'::
820 A desktop is focused.
822 'desktop_activate <monitor_id> <desktop_id>'::
823 A desktop is activated.
825 'desktop_layout <monitor_id> <desktop_id> tiled|monocle'::
826 The layout of a desktop changed.
828 'node_add <monitor_id> <desktop_id> <ip_id> <node_id>'::
831 'node_remove <monitor_id> <desktop_id> <node_id>'::
834 'node_swap <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
837 'node_transfer <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
838 A node is transferred.
840 'node_focus <monitor_id> <desktop_id> <node_id>'::
843 'node_activate <monitor_id> <desktop_id> <node_id>'::
846 'node_presel <monitor_id> <desktop_id> <node_id> (dir DIR|ratio RATIO|cancel)'::
847 A node is preselected.
849 'node_stack <node_id_1> below|above <node_id_2>'::
850 A node is stacked below or above another node.
852 'node_geometry <monitor_id> <desktop_id> <node_id> <node_geometry>'::
853 The geometry of a window changed.
855 'node_state <monitor_id> <desktop_id> <node_id> tiled|pseudo_tiled|floating|fullscreen on|off'::
856 The state of a window changed.
858 'node_flag <monitor_id> <desktop_id> <node_id> hidden|sticky|private|locked|marked|urgent on|off'::
859 One of the flags of a node changed.
861 'node_layer <monitor_id> <desktop_id> <node_id> below|normal|above'::
862 The layer of a window changed.
864 'pointer_action <monitor_id> <desktop_id> <node_id> move|resize_corner|resize_side begin|end'::
865 A pointer action occured.
867 Please note that *bspwm* initializes monitors before it reads messages on its socket, therefore the initial monitor events can't be received.
872 Each report event message is composed of items separated by colons.
874 Each item has the form '<type><value>' where '<type>' is the first character of the item.
883 Occupied focused desktop.
886 Occupied unfocused desktop.
889 Free focused desktop.
892 Free unfocused desktop.
895 Urgent focused desktop.
898 Urgent unfocused desktop.
901 Layout of the focused desktop of a monitor.
904 State of the focused node of a focused desktop.
907 Active flags of the focused node of a focused desktop.
909 Environment Variables
910 ---------------------
913 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'.
918 * Steven Allen <steven at stebalien.com>
919 * Thomas Adam <thomas at xteddy.org>
920 * Ivan Kanakarakis <ivan.kanak at gmail.com>
925 Bastien Dejean <nihilhill at gmail.com>