3 .\" Author: [see the "Author" section]
4 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
6 .\" Manual: Bspwm Manual
7 .\" Source: Bspwm 0.8.8
10 .TH "BSPWM" "1" "04/29/2014" "Bspwm 0\&.8\&.8" "Bspwm Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
25 .\" disable justification (adjust text to left margin only)
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
31 bspwm \- Binary space partitioning window manager
34 \fBbspwm\fR [\fB\-h\fR|\fB\-v\fR|\fB\-c\fR \fICONFIG_PATH\fR]
36 \fBbspc\fR \fICOMMAND\fR [\fIARGUMENTS\fR]
39 \fBbspwm\fR is a tiling window manager that represents windows as the leaves of a full binary tree\&.
41 It is controlled and configured via \fBbspc\fR\&.
46 Print the synopsis and exit\&.
51 Print the version and exit\&.
54 \fB\-c\fR \fICONFIG_PATH\fR
56 Use the given configuration file\&.
60 \fBbspwm\fR has only two sources of informations: the X events it receives and the messages it reads on a dedicated socket\&.
62 The default configuration file is \fI$XDG_CONFIG_HOME/bspwm/bspwmrc\fR\&.
64 Keyboard and pointer bindings are defined with sxhkd\&.
66 Example configuration files can be found in the \fBexamples\fR directory\&.
69 New windows are inserted in the tree as close as possible to the focused window\&.
71 There is only two splitting modes: \fIautomatic\fR and \fImanual\fR\&.
73 The default mode is \fIautomatic\fR\&. The \fImanual\fR mode is entered by sending a \fBpreselection\fR message\&.
75 Example: insertion of a new node (number 4) into the given tree in \fIautomatic\fR mode:
88 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
92 | 3 |\-\-\-\-\-\-\-\-\-\-\-\-| \-\-> | 4 |\-\-\-\-\-\-\-\-\-\-\-\-|
96 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
102 Same departure, but the mode is \fImanual\fR, and a \fBwindow \-\-presel up\fR message was sent beforehand:
114 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
118 | 3 |\-\-\-\-\-\-\-\-\-\-\-\-| \-\-> |\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-|
122 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
129 Each monitor contains at least one desktop\&.
131 Each desktop contains at most one tree\&.
132 .SH "COMMON DEFINITIONS"
138 DIR := left | right | up | down
139 CYCLE_DIR := next | prev
146 Selectors are used to select a target window, desktop, or monitor\&. A selector can either describe the target relatively or name it globally\&.
148 Descriptive (relative) selectors consist of a primary selector and any number of non\-conflicting modifiers as follows:
154 PRIMARY_SELECTOR[\&.MODIFIER]*
160 For obvious reasons, neither desktops nor monitors names may be valid descriptive selectors\&.
169 WINDOW_SEL := <window_id>
170 | (DIR|CYCLE_DIR|biggest|last|focused|older|newer)[\&.floating|\&.tiled][\&.like|\&.unlike][\&.manual|\&.automatic][\&.urgent][\&.local]
177 .nr an-no-space-flag 1
181 \fBPrimary Selectors\fR
186 Selects the window in the given (spacial) direction relative to the active window\&.
191 Selects the window in the given (cyclic) direction\&.
196 Selects the biggest window on the current desktop\&.
201 Selects the previously focused window\&.
206 Selects the currently focused window\&.
211 Selects the window older than the focused window in the history\&.
216 Selects the window newer than the focused window in the history\&.
221 .nr an-no-space-flag 1
230 Only consider floating windows\&.
235 Only consider tiled windows\&.
240 Only consider windows that have the same class as the current window\&.
245 Only consider windows that have a different class than the current window\&.
250 Only consider windows in manual splitting mode\&.
255 Only consider windows in automatic splitting mode\&.
260 Only consider windows of the current desktop\&.
265 Only consider urgent windows\&.
276 DESKTOP_SEL := <desktop_name>
278 | (CYCLE_DIR|last|[MONITOR_SEL:]focused|older|newer)[\&.occupied|\&.free][\&.urgent][\&.local]
285 .nr an-no-space-flag 1
289 \fBPrimary Selectors\fR
294 Selects the desktop with the given name\&.
299 Selects the nth desktop\&.
304 Selects the desktop in the given direction relative to the active desktop\&.
309 Selects the previously focused desktop\&.
314 Selects the currently focused desktop\&.
319 Selects the desktop older than the focused desktop in the history\&.
324 Selects the desktop newer than the focused desktop in the history\&.
329 .nr an-no-space-flag 1
338 Only consider occupied desktops\&.
343 Only consider free desktops\&.
348 Only consider urgent desktops\&.
353 Only consider desktops of the current monitor\&.
364 MONITOR_SEL := <monitor_name>
366 | (DIR|CYCLE_DIR|last|primary|focused|older|newer)[\&.occupied|\&.free]
373 .nr an-no-space-flag 1
377 \fBPrimary Selectors\fR
382 Selects the monitor with the given name\&.
387 Selects the nth monitor\&.
392 Selects the monitor in the given (spacial) direction relative to the active monitor\&.
397 Selects the monitor in the given (cyclic) direction relative to the active monitor\&.
402 Selects the primary monitor\&.
407 Selects the previously focused monitor\&.
412 Selects the currently focused monitor\&.
417 Selects the monitor older than the focused monitor in the history\&.
422 Selects the monitor newer than the focused monitor in the history\&.
427 .nr an-no-space-flag 1
436 Only consider monitors where the focused desktop is occupied\&.
441 Only consider monitors where the focused desktop is free\&.
448 Is above any tiled window and can be moved/resized freely\&. Although it doesn\(cqt occupy any tiling space, it is still part of the window tree\&.
453 Has a libre size while being centered in its tiling space\&.
458 Fills its monitor rectangle, is above all the other windows and has no borders\&.
470 Stays in the focused desktop of its monitor\&.
475 Tries to keep the same tiling position/size\&.
481 .nr an-no-space-flag 1
488 window [\fIWINDOW_SEL\fR] \fIOPTIONS\fR
492 .nr an-no-space-flag 1
499 \fB\-f\fR, \fB\-\-focus\fR [\fIWINDOW_SEL\fR]
501 Focus the selected or given window\&.
504 \fB\-d\fR, \fB\-\-to\-desktop\fR \fIDESKTOP_SEL\fR
506 Send the selected window to the given desktop\&.
509 \fB\-m\fR, \fB\-\-to\-monitor\fR \fIMONITOR_SEL\fR
511 Send the selected window to the given monitor\&.
514 \fB\-w\fR, \fB\-\-to\-window\fR \fIWINDOW_SEL\fR
516 Transplant the selected window to the given window\&.
519 \fB\-s\fR, \fB\-\-swap\fR \fIWINDOW_SEL\fR
521 Swap the selected window with the given window\&.
524 \fB\-p\fR, \fB\-\-presel\fR \fIDIR\fR|cancel
526 Preselect the splitting area of the selected window (or cancel the preselection)\&.
529 \fB\-r\fR, \fB\-\-ratio\fR \fIRATIO\fR
531 Set the splitting ratio of the selected window (0 <
536 \fB\-e\fR, \fB\-\-edge\fR \fIDIR\fR \fIRATIO\fR|\(+-\fIPIXELS\fR
538 Set or change the splitting ratio of the edge located in the given direction in relation to the selected window\&.
541 \fB\-R\fR, \fB\-\-rotate\fR \fIDIR\fR \fI90|270|180\fR
543 Rotate the tree holding the edge located in the given direction in relation to the selected window\&.
546 \fB\-t\fR, \fB\-\-toggle\fR floating|fullscreen|pseudo_tiled|locked|sticky|private[=on|off]
548 Set or toggle the given state for the selected window\&.
551 \fB\-c\fR, \fB\-\-close\fR
553 Close the selected window\&.
556 \fB\-k\fR, \fB\-\-kill\fR
558 Kill the selected window\&.
564 .nr an-no-space-flag 1
571 desktop [\fIDESKTOP_SEL\fR] \fIOPTIONS\fR
575 .nr an-no-space-flag 1
582 \fB\-f\fR, \fB\-\-focus\fR [\fIDESKTOP_SEL\fR]
584 Focus the selected or given desktop\&.
587 \fB\-m\fR, \fB\-\-to\-monitor\fR \fIMONITOR_SEL\fR
589 Send the selected desktop to the given monitor\&.
592 \fB\-l\fR, \fB\-\-layout\fR \fICYCLE_DIR\fR|monocle|tiled
594 Set or cycle the layout of the selected desktop\&.
597 \fB\-n\fR, \fB\-\-rename\fR <new_name>
599 Rename the selected desktop\&.
602 \fB\-s\fR, \fB\-\-swap\fR \fIDESKTOP_SEL\fR
604 Swap the selected desktop with the given desktop\&.
607 \fB\-r\fR, \fB\-\-remove\fR
609 Remove the selected desktop\&.
612 \fB\-c\fR, \fB\-\-cancel\-presel\fR
614 Cancel the preselection of all the windows of the selected desktop\&.
617 \fB\-F\fR, \fB\-\-flip\fR \fIhorizontal|vertical\fR
619 Flip the tree of the selected desktop\&.
622 \fB\-R\fR, \fB\-\-rotate\fR \fI90|270|180\fR
624 Rotate the tree of the selected desktop\&.
627 \fB\-E\fR, \fB\-\-equalize\fR
629 Reset the split ratios of the tree of the selected desktop\&.
632 \fB\-B\fR, \fB\-\-balance\fR
634 Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area\&.
637 \fB\-C\fR, \fB\-\-circulate\fR forward|backward
639 Circulate the leaves of the tree of the selected desktop\&.
642 \fB\-t\fR, \fB\-\-toggle\fR floating[=on|off]
644 Set or toggle the given state for the selected desktop\&.
650 .nr an-no-space-flag 1
657 monitor [\fIMONITOR_SEL\fR] \fIOPTIONS\fR
661 .nr an-no-space-flag 1
668 \fB\-f\fR, \fB\-\-focus\fR [\fIMONITOR_SEL\fR]
670 Focus the selected or given monitor\&.
673 \fB\-a\fR, \fB\-\-add\-desktops\fR <name>\&...
675 Create desktops with the given names in the selected monitor\&.
678 \fB\-r\fR, \fB\-\-remove\-desktops\fR <name>\&...
680 Remove desktops with the given names\&.
683 \fB\-o\fR, \fB\-\-reorder\-desktops\fR <name>\&...
685 Reorder the desktops of the selected monitor to match the given order\&.
688 \fB\-d\fR, \fB\-\-reset\-desktops\fR <name>\&...
690 Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops\&.
693 \fB\-n\fR, \fB\-\-rename\fR <new_name>
695 Rename the selected monitor\&.
698 \fB\-s\fR, \fB\-\-swap\fR \fIMONITOR_SEL\fR
700 Swap the selected monitor with the given monitor\&.
706 .nr an-no-space-flag 1
717 .nr an-no-space-flag 1
724 \fB\-W\fR, \fB\-\-windows\fR
726 List matching windows\&.
729 \fB\-D\fR, \fB\-\-desktops\fR
731 List matching desktops\&.
734 \fB\-M\fR, \fB\-\-monitors\fR
736 List matching monitors\&.
739 \fB\-T\fR, \fB\-\-tree\fR
741 Print tree rooted at query\&.
744 \fB\-H\fR, \fB\-\-history\fR
746 Print the history as it relates to the query\&.
749 \fB\-S\fR, \fB\-\-stack\fR
751 Print the window stacking order\&.
754 [\fB\-m\fR,\fB\-\-monitor\fR [\fIMONITOR_SEL\fR]] | [\fB\-d\fR,\fB\-\-desktop\fR [\fIDESKTOP_SEL\fR]] | [\fB\-w\fR, \fB\-\-window\fR [\fIWINDOW_SEL\fR]]
756 Constrain matches to the selected monitor, desktop or window\&.
762 .nr an-no-space-flag 1
769 restore \fIOPTIONS\fR
773 .nr an-no-space-flag 1
780 \fB\-T\fR, \fB\-\-tree\fR <file_path>
782 Load the desktop trees from the given file\&.
785 \fB\-H\fR, \fB\-\-history\fR <file_path>
787 Load the focus history from the given file\&.
790 \fB\-S\fR, \fB\-\-stack\fR <file_path>
792 Load the window stacking order from the given file\&.
798 .nr an-no-space-flag 1
805 control \fIOPTIONS\fR
809 .nr an-no-space-flag 1
816 \fB\-\-adopt\-orphans\fR
818 Manage all the unmanaged windows remaining from a previous session\&.
821 \fB\-\-toggle\-visibility\fR
823 Toggle the visibility of all the windows\&.
826 \fB\-\-record\-history\fR on|off
828 Enable or disable the recording of window focus history\&.
833 Continuously print status informations\&.
836 \fB\-\-get\-status\fR
838 Print the current status informations\&.
844 .nr an-no-space-flag 1
851 pointer \fIOPTIONS\fR
855 .nr an-no-space-flag 1
862 \fB\-g\fR, \fB\-\-grab\fR focus|move|resize_side|resize_corner
864 Initiate the given pointer action\&.
867 \fB\-t\fR, \fB\-\-track\fR <x> <y>
869 Pass the pointer root coordinates for the current pointer action\&.
872 \fB\-u\fR, \fB\-\-ungrab\fR
874 Terminate the current pointer action\&.
880 .nr an-no-space-flag 1
891 .nr an-no-space-flag 1
898 \fB\-a\fR, \fB\-\-add\fR <class_name>|<instance_name>|* [\fB\-o\fR|\fB\-\-one\-shot\fR] [monitor=MONITOR_SEL|desktop=DESKTOP_SEL|window=WINDOW_SEL] [(floating|fullscreen|pseudo_tiled|locked|sticky|private|center|follow|manage|focus)=(true|false)] [split_dir=DIR]
903 \fB\-r\fR, \fB\-\-remove\fR ^<n>|head|tail|<class_name>|<instance_name>|*\&...
905 Remove the given rules\&.
908 \fB\-l\fR, \fB\-\-list\fR [<class_name>|<instance_name>|*]
916 .nr an-no-space-flag 1
923 config [\-m \fIMONITOR_SEL\fR|\-d \fIDESKTOP_SEL\fR|\-w \fIWINDOW_SEL\fR] <key> [<value>]
925 Get or set the value of <key>\&.
931 .nr an-no-space-flag 1
940 Quit with an optional exit status\&.
945 If the server can\(cqt handle a message, \fBbspc\fR will return with one of the following exit codes:
963 Colors are either X color names or \fI#RRGGBB\fR, booleans are \fItrue\fR or \fIfalse\fR\&.
965 All the boolean settings are \fIfalse\fR by default\&.
966 .SS "Global Settings"
968 \fIfocused_border_color\fR
970 Color of the border of a focused window of a focused monitor\&.
973 \fIactive_border_color\fR
975 Color of the border of a focused window of an unfocused monitor\&.
978 \fInormal_border_color\fR
980 Color of the border of an unfocused window\&.
983 \fIpresel_border_color\fR
990 \fIfocused_locked_border_color\fR
992 Color of the border of a focused locked window of a focused monitor\&.
995 \fIactive_locked_border_color\fR
997 Color of the border of a focused locked window of an unfocused monitor\&.
1000 \fInormal_locked_border_color\fR
1002 Color of the border of an unfocused locked window\&.
1005 \fIfocused_sticky_border_color\fR
1007 Color of the border of a focused sticky window of a focused monitor\&.
1010 \fIactive_sticky_border_color\fR
1012 Color of the border of a focused sticky window of an unfocused monitor\&.
1015 \fInormal_sticky_border_color\fR
1017 Color of the border of an unfocused sticky window\&.
1020 \fIfocused_private_border_color\fR
1022 Color of the border of a focused private window of a focused monitor\&.
1025 \fIactive_private_border_color\fR
1027 Color of the border of a focused private window of an unfocused monitor\&.
1030 \fInormal_private_border_color\fR
1032 Color of the border of an unfocused private window\&.
1035 \fIurgent_border_color\fR
1037 Color of the border of an urgent window\&.
1042 Default split ratio\&.
1047 Prefix prepended to each of the status lines\&.
1050 \fIexternal_rules_command\fR
1052 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:
1053 \fBkey1=value1 key2=value2 \&...\fR
1054 (the valid key/value pairs are given in the description of the
1059 \fIhistory_aware_focus\fR
1061 Give priority to the focus history when focusing nodes\&.
1064 \fIborderless_monocle\fR
1066 Remove borders for tiled windows in monocle mode\&.
1069 \fIgapless_monocle\fR
1071 Remove gaps for tiled windows in monocle mode\&.
1074 \fIfocus_follows_pointer\fR
1076 Focus the window under the pointer\&.
1079 \fIpointer_follows_monitor\fR
1081 When focusing a monitor, put the pointer at its center\&.
1084 \fIauto_alternate\fR
1086 Interpret two consecutive identical
1095 Interpret two consecutive identical
1102 \fIapply_floating_atom\fR
1104 Set the value of the
1105 \fI_BSPWM_FLOATING_WINDOW\fR
1106 atom of each window according to its floating state\&.
1109 \fIignore_ewmh_focus\fR
1111 Ignore EWMH focus requests coming from applications\&.
1114 \fIremove_disabled_monitor\fR
1116 Consider disabled monitors as disconnected\&.
1119 \fIpersistent_monitors\fR
1121 Don\(cqt remove unplugged monitors\&.
1123 .SS "Monitor and Desktop Settings"
1125 \fItop_padding\fR, \fIright_padding\fR, \fIbottom_padding\fR, \fIleft_padding\fR
1127 Padding space added at the sides of the monitor or desktop\&.
1129 .SS "Desktop and Window Settings"
1133 Window border width\&.
1135 .SS "Desktop Settings"
1139 Size of the gap that separates windows\&.
1143 Status informations are composed of items separated by colons\&.
1145 Each item has the form \fI<type><value>\fR where \fI<type>\fR is the first character of the item\&.
1147 \fIM<monitor_name>\fR
1152 \fIm<monitor_name>\fR
1154 Unfocused monitor\&.
1157 \fIO<desktop_name>\fR
1159 Occupied focused desktop\&.
1162 \fIo<desktop_name>\fR
1164 Occupied unfocused desktop\&.
1167 \fIF<desktop_name>\fR
1169 Free focused desktop\&.
1172 \fIf<desktop_name>\fR
1174 Free unfocused desktop\&.
1177 \fIU<desktop_name>\fR
1179 Urgent focused desktop\&.
1182 \fIu<desktop_name>\fR
1184 Urgent unfocused desktop\&.
1187 \fIL(tiled|monocle)\fR
1189 Layout of the focused desktop of the focused monitor\&.
1191 .SH "ENVIRONMENT VARIABLES"
1195 The path of the socket used for the communication between
1198 \fBbspwm\fR\&. If it isn\(cqt defined, then the following path is used:
1199 \fI/tmp/bspwm<display_name>\-socket\fR\&.
1205 \h'-04'\(bu\h'+03'\c
1211 Any EWMH compliant panel (e\&.g\&.:
1213 \fIbmpanel2\fR, etc\&.)\&.
1218 \h'-04'\(bu\h'+03'\c
1224 A custom panel if the
1226 flag is used (have a look at the files in
1227 \fIexamples/panel\fR)\&.
1233 \h'-04'\(bu\h'+03'\c
1239 Configured and controlled through messages\&.
1244 \h'-04'\(bu\h'+03'\c
1250 Multiple monitors support (via
1256 \h'-04'\(bu\h'+03'\c
1262 EWMH support (\fBtint2\fR
1268 \h'-04'\(bu\h'+03'\c
1280 \h'-04'\(bu\h'+03'\c
1286 Steven Allen <steven at stebalien\&.com>
1291 \h'-04'\(bu\h'+03'\c
1297 Thomas Adam <thomas at xteddy\&.org>
1302 \h'-04'\(bu\h'+03'\c
1308 Ivan Kanakarakis <ivan\&.kanak at gmail\&.com>
1312 Bastien Dejean <nihilhill at gmail\&.com>
1315 bspwm at librelist\&.com