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.9
10 .TH "BSPWM" "1" "11/23/2014" "Bspwm 0\&.8\&.9" "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 are 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 action, 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 desktop nor monitor 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][\&.unfocused]
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\&.
270 Only consider windows other than the focused window\&.
281 DESKTOP_SEL := <desktop_name>
283 | (CYCLE_DIR|last|[MONITOR_SEL:]focused|older|newer)[\&.occupied|\&.free][\&.urgent][\&.local]
290 .nr an-no-space-flag 1
294 \fBPrimary Selectors\fR
299 Selects the desktop with the given name\&.
304 Selects the nth desktop\&.
309 Selects the desktop in the given direction relative to the active desktop\&.
314 Selects the previously focused desktop\&.
319 Selects the currently focused desktop\&.
324 Selects the desktop older than the focused desktop in the history\&.
329 Selects the desktop newer than the focused desktop in the history\&.
334 .nr an-no-space-flag 1
343 Only consider occupied desktops\&.
348 Only consider free desktops\&.
353 Only consider urgent desktops\&.
358 Only consider desktops of the current monitor\&.
369 MONITOR_SEL := <monitor_name>
371 | (DIR|CYCLE_DIR|last|primary|focused|older|newer)[\&.occupied|\&.free]
378 .nr an-no-space-flag 1
382 \fBPrimary Selectors\fR
387 Selects the monitor with the given name\&.
392 Selects the nth monitor\&.
397 Selects the monitor in the given (spacial) direction relative to the active monitor\&.
402 Selects the monitor in the given (cyclic) direction relative to the active monitor\&.
407 Selects the primary monitor\&.
412 Selects the previously focused monitor\&.
417 Selects the currently focused monitor\&.
422 Selects the monitor older than the focused monitor in the history\&.
427 Selects the monitor newer than the focused monitor in the history\&.
432 .nr an-no-space-flag 1
441 Only consider monitors where the focused desktop is occupied\&.
446 Only consider monitors where the focused desktop is free\&.
453 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\&.
458 Has an unrestricted size while being centered in its tiling space\&.
463 Fills its monitor rectangle, is above all the other windows and has no borders\&.
475 Stays in the focused desktop of its monitor\&.
480 Tries to keep the same tiling position/size\&.
486 .nr an-no-space-flag 1
493 window [\fIWINDOW_SEL\fR] \fIOPTIONS\fR
497 .nr an-no-space-flag 1
504 \fB\-f\fR, \fB\-\-focus\fR [\fIWINDOW_SEL\fR]
506 Focus the selected or given window\&.
509 \fB\-d\fR, \fB\-\-to\-desktop\fR \fIDESKTOP_SEL\fR
511 Send the selected window to the given desktop\&.
514 \fB\-m\fR, \fB\-\-to\-monitor\fR \fIMONITOR_SEL\fR
516 Send the selected window to the given monitor\&.
519 \fB\-w\fR, \fB\-\-to\-window\fR \fIWINDOW_SEL\fR
521 Transplant the selected window to the given window\&.
524 \fB\-s\fR, \fB\-\-swap\fR \fIWINDOW_SEL\fR
526 Swap the selected window with the given window\&.
529 \fB\-p\fR, \fB\-\-presel\fR \fIDIR\fR|cancel
531 Preselect the splitting area of the selected window (or cancel the preselection)\&.
534 \fB\-r\fR, \fB\-\-ratio\fR \fIRATIO\fR
536 Set the splitting ratio of the selected window (0 <
541 \fB\-e\fR, \fB\-\-edge\fR \fIDIR\fR \fIRATIO\fR|\(+-\fIPIXELS\fR
543 Set or change the splitting ratio of the edge located in the given direction in relation to the selected window\&.
546 \fB\-R\fR, \fB\-\-rotate\fR \fIDIR\fR \fI90|270|180\fR
548 Rotate the tree holding the edge located in the given direction in relation to the selected window\&.
551 \fB\-t\fR, \fB\-\-toggle\fR floating|fullscreen|pseudo_tiled|locked|sticky|private[=on|off]
553 Set or toggle the given state for the selected window\&.
556 \fB\-c\fR, \fB\-\-close\fR
558 Close the selected window\&.
561 \fB\-k\fR, \fB\-\-kill\fR
563 Kill the selected window\&.
569 .nr an-no-space-flag 1
576 desktop [\fIDESKTOP_SEL\fR] \fIOPTIONS\fR
580 .nr an-no-space-flag 1
587 \fB\-f\fR, \fB\-\-focus\fR [\fIDESKTOP_SEL\fR]
589 Focus the selected or given desktop\&.
592 \fB\-m\fR, \fB\-\-to\-monitor\fR \fIMONITOR_SEL\fR
594 Send the selected desktop to the given monitor\&.
597 \fB\-l\fR, \fB\-\-layout\fR \fICYCLE_DIR\fR|monocle|tiled
599 Set or cycle the layout of the selected desktop\&.
602 \fB\-n\fR, \fB\-\-rename\fR <new_name>
604 Rename the selected desktop\&.
607 \fB\-s\fR, \fB\-\-swap\fR \fIDESKTOP_SEL\fR
609 Swap the selected desktop with the given desktop\&.
612 \fB\-r\fR, \fB\-\-remove\fR
614 Remove the selected desktop\&.
617 \fB\-c\fR, \fB\-\-cancel\-presel\fR
619 Cancel the preselection of all the windows of the selected desktop\&.
622 \fB\-F\fR, \fB\-\-flip\fR \fIhorizontal|vertical\fR
624 Flip the tree of the selected desktop\&.
627 \fB\-R\fR, \fB\-\-rotate\fR \fI90|270|180\fR
629 Rotate the tree of the selected desktop\&.
632 \fB\-E\fR, \fB\-\-equalize\fR
634 Reset the split ratios of the tree of the selected desktop\&.
637 \fB\-B\fR, \fB\-\-balance\fR
639 Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area\&.
642 \fB\-C\fR, \fB\-\-circulate\fR forward|backward
644 Circulate the leaves of the tree of the selected desktop\&.
647 \fB\-t\fR, \fB\-\-toggle\fR floating[=on|off]
649 Set or toggle the given state for the selected desktop\&.
655 .nr an-no-space-flag 1
662 monitor [\fIMONITOR_SEL\fR] \fIOPTIONS\fR
666 .nr an-no-space-flag 1
673 \fB\-f\fR, \fB\-\-focus\fR [\fIMONITOR_SEL\fR]
675 Focus the selected or given monitor\&.
678 \fB\-a\fR, \fB\-\-add\-desktops\fR <name>\&...
680 Create desktops with the given names in the selected monitor\&.
683 \fB\-r\fR, \fB\-\-remove\-desktops\fR <name>\&...
685 Remove desktops with the given names\&.
688 \fB\-o\fR, \fB\-\-reorder\-desktops\fR <name>\&...
690 Reorder the desktops of the selected monitor to match the given order\&.
693 \fB\-d\fR, \fB\-\-reset\-desktops\fR <name>\&...
695 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\&.
698 \fB\-n\fR, \fB\-\-rename\fR <new_name>
700 Rename the selected monitor\&.
703 \fB\-s\fR, \fB\-\-swap\fR \fIMONITOR_SEL\fR
705 Swap the selected monitor with the given monitor\&.
711 .nr an-no-space-flag 1
722 .nr an-no-space-flag 1
729 \fB\-W\fR, \fB\-\-windows\fR
731 List matching windows\&.
734 \fB\-D\fR, \fB\-\-desktops\fR
736 List matching desktops\&.
739 \fB\-M\fR, \fB\-\-monitors\fR
741 List matching monitors\&.
744 \fB\-T\fR, \fB\-\-tree\fR
746 Print tree rooted at query\&.
749 \fB\-H\fR, \fB\-\-history\fR
751 Print the history as it relates to the query\&.
754 \fB\-S\fR, \fB\-\-stack\fR
756 Print the window stacking order\&.
759 [\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]]
761 Constrain matches to the selected monitor, desktop or window\&.
767 .nr an-no-space-flag 1
774 restore \fIOPTIONS\fR
778 .nr an-no-space-flag 1
785 \fB\-T\fR, \fB\-\-tree\fR <file_path>
787 Load the desktop trees from the given file\&.
790 \fB\-H\fR, \fB\-\-history\fR <file_path>
792 Load the focus history from the given file\&.
795 \fB\-S\fR, \fB\-\-stack\fR <file_path>
797 Load the window stacking order from the given file\&.
803 .nr an-no-space-flag 1
810 control \fIOPTIONS\fR
814 .nr an-no-space-flag 1
821 \fB\-\-adopt\-orphans\fR
823 Manage all the unmanaged windows remaining from a previous session\&.
826 \fB\-\-toggle\-visibility\fR
828 Toggle the visibility of all the windows\&.
831 \fB\-\-record\-history\fR on|off
833 Enable or disable the recording of window focus history\&.
838 Continuously print status information\&.
841 \fB\-\-get\-status\fR
843 Print the current status information\&.
849 .nr an-no-space-flag 1
856 pointer \fIOPTIONS\fR
860 .nr an-no-space-flag 1
867 \fB\-g\fR, \fB\-\-grab\fR focus|move|resize_side|resize_corner
869 Initiate the given pointer action\&.
872 \fB\-t\fR, \fB\-\-track\fR <x> <y>
874 Pass the pointer root coordinates for the current pointer action\&.
877 \fB\-u\fR, \fB\-\-ungrab\fR
879 Terminate the current pointer action\&.
885 .nr an-no-space-flag 1
896 .nr an-no-space-flag 1
903 \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|border)=(on|off)] [split_dir=DIR]
908 \fB\-r\fR, \fB\-\-remove\fR ^<n>|head|tail|<class_name>|<instance_name>|*\&...
910 Remove the given rules\&.
913 \fB\-l\fR, \fB\-\-list\fR [<class_name>|<instance_name>|*]
921 .nr an-no-space-flag 1
928 config [\-m \fIMONITOR_SEL\fR|\-d \fIDESKTOP_SEL\fR|\-w \fIWINDOW_SEL\fR] <key> [<value>]
930 Get or set the value of <key>\&.
936 .nr an-no-space-flag 1
945 Quit with an optional exit status\&.
950 If the server can\(cqt handle a message, \fBbspc\fR will return with one of the following exit codes:
968 Colors are either X color names or \fI#RRGGBB\fR, booleans are \fItrue\fR or \fIfalse\fR\&.
970 All the boolean settings are \fIfalse\fR by default\&.
971 .SS "Global Settings"
973 \fIfocused_border_color\fR
975 Color of the border of a focused window of a focused monitor\&.
978 \fIactive_border_color\fR
980 Color of the border of a focused window of an unfocused monitor\&.
983 \fInormal_border_color\fR
985 Color of the border of an unfocused window\&.
988 \fIpresel_border_color\fR
995 \fIfocused_locked_border_color\fR
997 Color of the border of a focused locked window of a focused monitor\&.
1000 \fIactive_locked_border_color\fR
1002 Color of the border of a focused locked window of an unfocused monitor\&.
1005 \fInormal_locked_border_color\fR
1007 Color of the border of an unfocused locked window\&.
1010 \fIfocused_sticky_border_color\fR
1012 Color of the border of a focused sticky window of a focused monitor\&.
1015 \fIactive_sticky_border_color\fR
1017 Color of the border of a focused sticky window of an unfocused monitor\&.
1020 \fInormal_sticky_border_color\fR
1022 Color of the border of an unfocused sticky window\&.
1025 \fIfocused_private_border_color\fR
1027 Color of the border of a focused private window of a focused monitor\&.
1030 \fIactive_private_border_color\fR
1032 Color of the border of a focused private window of an unfocused monitor\&.
1035 \fInormal_private_border_color\fR
1037 Color of the border of an unfocused private window\&.
1040 \fIurgent_border_color\fR
1042 Color of the border of an urgent window\&.
1047 Default split ratio\&.
1052 Prefix prepended to each of the status lines\&.
1055 \fIexternal_rules_command\fR
1057 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:
1058 \fBkey1=value1 key2=value2 \&...\fR
1059 (the valid key/value pairs are given in the description of the
1064 \fIhistory_aware_focus\fR
1066 Give priority to the focus history when focusing nodes\&.
1069 \fIfocus_by_distance\fR
1071 Base focusing on distances between windows\&.
1074 \fIborderless_monocle\fR
1076 Remove borders for tiled windows in monocle mode\&.
1079 \fIgapless_monocle\fR
1081 Remove gaps for tiled windows in monocle mode\&.
1084 \fIfocus_follows_pointer\fR
1086 Focus the window under the pointer\&.
1089 \fIpointer_follows_focus\fR
1091 When focusing a window, put the pointer at its center\&.
1094 \fIpointer_follows_monitor\fR
1096 When focusing a monitor, put the pointer at its center\&.
1099 \fIauto_alternate\fR
1101 Interpret two consecutive identical
1110 Interpret two consecutive identical
1117 \fIapply_floating_atom\fR
1119 Set the value of the
1120 \fI_BSPWM_FLOATING_WINDOW\fR
1121 atom of each window according to its floating state\&.
1124 \fIignore_ewmh_focus\fR
1126 Ignore EWMH focus requests coming from applications\&.
1129 \fIremove_disabled_monitors\fR
1131 Consider disabled monitors as disconnected\&.
1134 \fIremove_unplugged_monitors\fR
1136 Remove unplugged monitors\&.
1139 \fImerge_overlapping_monitors\fR
1141 Merge overlapping monitors (the bigger remains)\&.
1143 .SS "Monitor and Desktop Settings"
1145 \fItop_padding\fR, \fIright_padding\fR, \fIbottom_padding\fR, \fIleft_padding\fR
1147 Padding space added at the sides of the monitor or desktop\&.
1149 .SS "Default, Desktop Default and Window Settings"
1153 Window border width\&.
1155 .SS "Default and Desktop Settings"
1159 Size of the gap that separates windows\&.
1163 Status information is composed of items separated by colons\&.
1165 Each item has the form \fI<type><value>\fR where \fI<type>\fR is the first character of the item\&.
1167 \fIM<monitor_name>\fR
1172 \fIm<monitor_name>\fR
1174 Unfocused monitor\&.
1177 \fIO<desktop_name>\fR
1179 Occupied focused desktop\&.
1182 \fIo<desktop_name>\fR
1184 Occupied unfocused desktop\&.
1187 \fIF<desktop_name>\fR
1189 Free focused desktop\&.
1192 \fIf<desktop_name>\fR
1194 Free unfocused desktop\&.
1197 \fIU<desktop_name>\fR
1199 Urgent focused desktop\&.
1202 \fIu<desktop_name>\fR
1204 Urgent unfocused desktop\&.
1209 Layout of the focused desktop of a monitor\&.
1211 .SH "ENVIRONMENT VARIABLES"
1215 The path of the socket used for the communication between
1218 \fBbspwm\fR\&. If it isn\(cqt defined, then the following path is used:
1219 \fI/tmp/bspwm<host_name>_<display_number>_<screen_number>\-socket\fR\&.
1225 \h'-04'\(bu\h'+03'\c
1231 Any EWMH compliant panel (e\&.g\&.:
1233 \fIbmpanel2\fR, etc\&.)\&.
1238 \h'-04'\(bu\h'+03'\c
1244 A custom panel (have a look at the files in
1245 \fIexamples/panel\fR)\&.
1251 \h'-04'\(bu\h'+03'\c
1257 Configured and controlled through messages\&.
1262 \h'-04'\(bu\h'+03'\c
1268 Multiple monitors support\&.
1273 \h'-04'\(bu\h'+03'\c
1284 \h'-04'\(bu\h'+03'\c
1296 \h'-04'\(bu\h'+03'\c
1302 Steven Allen <steven at stebalien\&.com>
1307 \h'-04'\(bu\h'+03'\c
1313 Thomas Adam <thomas at xteddy\&.org>
1318 \h'-04'\(bu\h'+03'\c
1324 Ivan Kanakarakis <ivan\&.kanak at gmail\&.com>
1328 Bastien Dejean <nihilhill at gmail\&.com>
1331 bspwm at librelist\&.com