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* 'COMMAND' ['ARGUMENTS']
23 *bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree.
25 It is controlled and configured via *bspc*.
32 Print the synopsis and exit.
35 Print the version and exit.
38 Use the given configuration file.
44 DIR := left | right | up | down
45 CYCLE_DIR := next | prev
51 Selectors are used to select a target window, desktop, or monitor. A selector
52 can either describe the target relatively or name it globally.
54 Descriptive (relative) selectors consist of a primary selector and any number
55 of non-conflicting modifiers as follows:
57 PRIMARY_SELECTOR[.MODIFIER]*
59 For obvious reasons, neither desktop nor monitor names may be valid descriptive
62 An exclamation mark can be prepended to certain modifiers in order to reverse their meaning.
70 WINDOW_SEL := (<window_id>|DIR|CYCLE_DIR|biggest|last|focused|older|newer)[.[!]automatic][.[!](tiled|pseudo_tiled|floating|fullscreen)][.[!](below|normal|above)][.[!]local][.[!]same_class][.[!]focused][.[!](urgent|sticky|private|locked)]
77 Selects the window in the given (spacial) direction relative to the active window.
80 Selects the window in the given (cyclic) direction.
83 Selects the biggest window on the current desktop.
86 Selects the previously focused window.
89 Selects the currently focused window.
92 Selects the window older than the focused window in the history.
95 Selects the window newer than the focused window in the history.
100 [!](tiled|pseudo_tiled|floating|fullscreen)::
101 Only consider windows having or not having the given state.
104 Only consider windows in automatic or manual insertion mode.
107 Only consider focused or unfocused windows.
110 Only consider windows that have or don't have the same class as the current window.
113 Only consider windows in or not in the current desktop.
115 [!](private|urgent|sticky|locked)::
116 Only consider windows that have or don't have the given flag set.
118 [!](below|normal|above)::
119 Only consider windows in or not in the given layer.
127 DESKTOP_SEL := (<desktop_name>|[MONITOR_SEL:](focused|^<n>)CYCLE_DIR|last|older|newer)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
134 Selects the desktop with the given name.
137 Selects the nth desktop.
140 Selects the desktop in the given direction relative to the active desktop.
143 Selects the previously focused desktop.
146 Selects the currently focused desktop.
149 Selects the desktop older than the focused desktop in the history.
152 Selects the desktop newer than the focused desktop in the history.
158 Only consider occupied or free desktops.
161 Only consider focused or unfocused desktops.
164 Only consider urgent or non urgent desktops.
167 Only consider inside or outside of the current monitor.
175 MONITOR_SEL := (<monitor_name>|^<n>|DIR|CYCLE_DIR|last|primary|focused|older|newer)[.[!]occupied][.[!]focused]
182 Selects the monitor with the given name.
185 Selects the nth monitor.
188 Selects the monitor in the given (spacial) direction relative to the active monitor.
191 Selects the monitor in the given (cyclic) direction relative to the active monitor.
194 Selects the primary monitor.
197 Selects the previously focused monitor.
200 Selects the currently focused monitor.
203 Selects the monitor older than the focused monitor in the history.
206 Selects the monitor newer than the focused monitor in the history.
212 Only consider monitors where the focused desktop is occupied or free.
215 Only consider focused or unfocused monitors.
222 Its size and position are determined by the splitting type and ratio of each node of its path in the window tree.
225 Has an unrestricted size while being centered in its tiling space.
228 Can be moved/resized freely. Although it doesn't occupy any tiling space, it is still part of the window tree.
231 Fills its monitor rectangle and has no borders. It is send in the ABOVE layer by default.
238 Ignores the *window --close* message.
241 Stays in the focused desktop of its monitor.
244 Tries to keep the same tiling position/size.
247 Has its urgency hint set. This flag is set externally.
253 There's three stacking layers: BELOW, NORMAL and ABOVE.
255 In each layer, the window are orderered as follow: tiled & pseudo-tiled < fullscreen < floating.
267 window ['WINDOW_SEL'] 'OPTIONS'
271 *-f*, *--focus* ['WINDOW_SEL']::
272 Focus the selected or given window.
274 *-a*, *--activate* ['WINDOW_SEL']::
275 Activate the selected or given window.
277 *-d*, *--to-desktop* 'DESKTOP_SEL'::
278 Send the selected window to the given desktop.
280 *-m*, *--to-monitor* 'MONITOR_SEL'::
281 Send the selected window to the given monitor.
283 *-w*, *--to-window* 'WINDOW_SEL'::
284 Transplant the selected window to the given window.
286 *-s*, *--swap* 'WINDOW_SEL'::
287 Swap the selected window with the given window.
289 *-p*, *--presel* 'DIR'|cancel::
290 Preselect the splitting area of the selected window (or cancel the preselection).
292 *-r*, *--ratio* 'RATIO'::
293 Set the splitting ratio of the selected window (0 < 'RATIO' < 1).
295 *-e*, *--edge* 'DIR' 'RATIO'|±'PIXELS'::
296 Set or change the splitting ratio of the edge located in the given direction in relation to the selected window.
298 *-R*, *--rotate* 'DIR' '90|270|180'::
299 Rotate the tree holding the edge located in the given direction in relation to the selected window.
301 *-t*, *--state* tiled|pseudo_tiled|floating|fullscreen::
302 Set the state of the selected window.
304 *-g*, *--flag* locked|sticky|private[=on|off]::
305 Set or toggle the given flag for the selected window.
307 *-l*, *--layer* below|normal|above::
308 Set the stacking layer of the selected window.
311 Close the selected window.
314 Kill the selected window.
322 desktop ['DESKTOP_SEL'] 'OPTIONS'
326 *-f*, *--focus* ['DESKTOP_SEL']::
327 Focus the selected or given desktop.
329 *-m*, *--to-monitor* 'MONITOR_SEL'::
330 Send the selected desktop to the given monitor.
332 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
333 Set or cycle the layout of the selected desktop.
335 *-n*, *--rename* <new_name>::
336 Rename the selected desktop.
338 *-s*, *--swap* 'DESKTOP_SEL'::
339 Swap the selected desktop with the given desktop.
341 *-b*, *--bubble* 'CYCLE_DIR'::
342 Bubble the selected desktop in the given direction.
345 Remove the selected desktop.
347 *-c*, *--cancel-presel*::
348 Cancel the preselection of all the windows of the selected desktop.
350 *-F*, *--flip* 'horizontal|vertical'::
351 Flip the tree of the selected desktop.
353 *-R*, *--rotate* '90|270|180'::
354 Rotate the tree of the selected desktop.
357 Reset the split ratios of the tree of the selected desktop.
360 Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
362 *-C*, *--circulate* forward|backward::
363 Circulate the leaves of the tree of the selected desktop.
372 monitor ['MONITOR_SEL'] 'OPTIONS'
376 *-f*, *--focus* ['MONITOR_SEL']::
377 Focus the selected or given monitor.
379 *-a*, *--add-desktops* <name>...::
380 Create desktops with the given names in the selected monitor.
382 *-r*, *--remove-desktops* <name>...::
383 Remove desktops with the given names.
385 *-o*, *--reorder-desktops* <name>...::
386 Reorder the desktops of the selected monitor to match the given order.
388 *-d*, *--reset-desktops* <name>...::
389 Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops. Incidentally reset the settings of the existing desktops.
391 *-n*, *--rename* <new_name>::
392 Rename the selected monitor.
394 *-s*, *--swap* 'MONITOR_SEL'::
395 Swap the selected monitor with the given monitor.
408 List the IDs of the matching windows.
411 List the names of the matching desktops.
414 List the names of the matching monitors.
417 Print a JSON representation of the matching item.
420 Print the focus history as it relates to the query.
423 Print the window stacking order.
425 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
426 Constrain matches to the selected monitor, desktop or window.
439 *-T*, *--tree* <file_path>::
440 Load the desktop trees from the given file.
442 *-H*, *--history* <file_path>::
443 Load the focus history from the given file.
445 *-S*, *--stack* <file_path>::
446 Load the window stacking order from the given file.
460 Manage all the unmanaged windows remaining from a previous session.
462 *--toggle-visibility*::
463 Toggle the visibility of all the windows.
465 *--record-history* on|off::
466 Enable or disable the recording of window focus history.
468 *--subscribe* (all|report|monitor|desktop|window|...)*::
469 Continuously print status information. See the *EVENTS* section for the detailed description of each event.
472 Print the current status information.
485 *-g*, *--grab* focus|move|resize_side|resize_corner::
486 Initiate the given pointer action.
488 *-t*, *--track* <x> <y>::
489 Pass the pointer root coordinates for the current pointer action.
492 Terminate the current pointer action.
505 *-a*, *--add* <class_name>|<instance_name>|* [*-o*|*--one-shot*] [monitor=MONITOR_SEL|desktop=DESKTOP_SEL|window=WINDOW_SEL] [state=STATE] [layer=LAYER] [split_dir=DIR] [split_ratio=RATIO] [(locked|sticky|private|center|follow|manage|focus|border)=(on|off)]::
508 *-r*, *--remove* ^<n>|head|tail|<class_name>|<instance_name>|*...::
509 Remove the given rules.
511 *-l*, *--list* [<class_name>|<instance_name>|*]::
520 config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-w 'WINDOW_SEL'] <key> [<value>]::
521 Get or set the value of <key>.
530 Quit with an optional exit status.
535 If the server can't handle a message, *bspc* will return with one of the following exit codes:
547 Colors are either '#RRGGBB' or http://en.wikipedia.org/wiki/X11_color_names[X color names], booleans are 'true', 'on', 'false' or 'off'.
549 All the boolean settings are 'false' by default unless stated otherwise.
554 'focused_border_color'::
555 Color of the border of a focused window of a focused monitor.
557 'active_border_color'::
558 Color of the border of a focused window of an unfocused monitor.
560 'normal_border_color'::
561 Color of the border of an unfocused window.
563 'presel_border_color'::
564 Color of the *window --presel* message feedback.
566 'focused_locked_border_color'::
567 Color of the border of a focused locked window of a focused monitor.
569 'active_locked_border_color'::
570 Color of the border of a focused locked window of an unfocused monitor.
572 'normal_locked_border_color'::
573 Color of the border of an unfocused locked window.
575 'focused_sticky_border_color'::
576 Color of the border of a focused sticky window of a focused monitor.
578 'active_sticky_border_color'::
579 Color of the border of a focused sticky window of an unfocused monitor.
581 'normal_sticky_border_color'::
582 Color of the border of an unfocused sticky window.
584 'focused_private_border_color'::
585 Color of the border of a focused private window of a focused monitor.
587 'active_private_border_color'::
588 Color of the border of a focused private window of an unfocused monitor.
590 'normal_private_border_color'::
591 Color of the border of an unfocused private window.
593 'urgent_border_color'::
594 Color of the border of an urgent window.
600 Prefix prepended to each of the status lines.
602 'external_rules_command'::
603 External command used to retrieve rule consequences. The command will receive the the ID of the window being processed as its first argument and the class and instance names as second and third arguments. 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).
606 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*.
608 'history_aware_focus'::
609 Give priority to the focus history when focusing nodes.
611 'focus_by_distance'::
612 Base focusing on distances between windows.
614 'borderless_monocle'::
615 Remove borders of tiled windows for the *monocle* desktop layout.
618 Remove gaps of tiled windows for the *monocle* desktop layout.
621 Set the desktop layout to *monocle* if there's only one tiled window in the tree.
623 'focus_follows_pointer'::
624 Focus the window under the pointer.
626 'pointer_follows_focus'::
627 When focusing a window, put the pointer at its center.
629 'pointer_follows_monitor'::
630 When focusing a monitor, put the pointer at its center.
633 Interpret consecutive identical *--focus* arguments as the *last* selector for the *monitor* and *desktop* commands.
636 Interpret consecutive identical *--presel* arguments as *--cancel-presel* option.
638 'ignore_ewmh_focus'::
639 Ignore EWMH focus requests coming from applications.
641 'center_pseudo_tiled'::
642 Center pseudo tiled windows into their tiling rectangles. Defaults to 'true'.
644 'remove_disabled_monitors'::
645 Consider disabled monitors as disconnected.
647 'remove_unplugged_monitors'::
648 Remove unplugged monitors.
650 'merge_overlapping_monitors'::
651 Merge overlapping monitors (the bigger remains).
653 Monitor and Desktop Settings
654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
660 Padding space added at the sides of the monitor or desktop.
662 Default, Desktop Default and Window Settings
663 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
668 Default and Desktop Settings
669 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
672 Size of the gap that separates windows.
679 See the next section for the description of the format.
681 'monitor_add <monitor_name> <monitor_id> <monitor_geometry>'::
684 'monitor_rename <old_name> <new_name>'::
685 A monitor is renamed.
687 'monitor_remove <monitor_name>'::
688 A monitor is removed.
690 'monitor_focus <monitor_name>'::
691 A monitor is focused.
693 'monitor_geometry <monitor_name> <monitor_geometry>'::
694 The geometry of a monitor changed.
696 'desktop_add <monitor_name> <desktop_name>'::
699 'desktop_rename <monitor_name> <old_name> <new_name>'::
700 A desktop is renamed.
702 'desktop_remove <monitor_name> <desktop_name>'::
703 A desktop is removed.
705 'desktop_swap <src_monitor_name> <src_desktop_name> <dst_monitor_name> <dst_desktop_name>'::
706 A desktop is swapped.
708 'desktop_transfer <src_monitor_name> <src_desktop_name> <dst_monitor_name>'::
709 A desktop is transferred.
711 'desktop_focus <monitor_name> <desktop_name>'::
712 A desktop is focused.
714 'desktop_layout <monitor_name> <desktop_name> tiled|monocle'::
715 The layout of a desktop changed.
717 'window_manage <monitor_name> <desktop_name> <window_id> <ip_id>'::
720 'window_unmanage <monitor_name> <desktop_name> <window_id>'::
721 A window is unmanaged.
723 'window_swap <src_monitor_name> <src_desktop_name> <src_window_id> <dst_monitor_name> <dst_desktop_name> <dst_window_id>'::
726 'window_transfer <src_monitor_name> <src_desktop_name> <src_window_id> <dst_monitor_name> <dst_desktop_name> <dst_window_id>'::
727 A window is transferred.
729 'window_focus <monitor_name> <desktop_name> <window_id>'::
732 'window_activate <monitor_name> <desktop_name> <window_id>'::
733 A window is activated.
735 'window_geometry <monitor_name> <desktop_name> <window_id> <window_geometry>'::
736 The geometry of a window changed.
738 'window_state <monitor_name> <desktop_name> <window_id> tiled|pseudo_tiled|floating|fullscreen on|off'::
739 The state of a window changed.
741 'window_flag <monitor_name> <desktop_name> <window_id> sticky|private|locked|urgent on|off'::
742 One of the flags of a window changed.
744 'window_layer <monitor_name> <desktop_name> <window_id> below|normal|above'::
745 The layer of a window changed.
747 Please note that *bspwm* initializes monitors before it reads messages on its socket, therefore the initial monitor events can't be received.
752 Each report event message is composed of items separated by colons.
754 Each item has the form '<type><value>' where '<type>' is the first character of the item.
763 Occupied focused desktop.
766 Occupied unfocused desktop.
769 Free focused desktop.
772 Free unfocused desktop.
775 Urgent focused desktop.
778 Urgent unfocused desktop.
781 Layout of the focused desktop of a monitor.
783 Environment Variables
784 ---------------------
787 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'.
792 * Steven Allen <steven at stebalien.com>
793 * Thomas Adam <thomas at xteddy.org>
794 * Ivan Kanakarakis <ivan.kanak at gmail.com>
799 Bastien Dejean <nihilhill at gmail.com>