2 :man version: {revnumber}
3 :man manual: Bspwm Manual
11 bspwm - Tiling window manager based on binary space partitioning
16 *bspwm* [*-h*|*-v*|*-s* 'PANEL_FIFO'|*-p* 'PANEL_PREFIX']
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 Write the internal state to the given FIFO.
41 Start every line written to the 'PANEL_FIFO' with the given prefix.
47 *bspwm* have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
49 Its configuration file is '$XDG_CONFIG_HOME/bspwm/autostart'.
51 Keyboard and pointer bindings are defined with https://github.com/baskerville/sxhkd[sxhkd].
53 Example configuration files can be found in the *examples* directory.
58 New windows are inserted in the tree as close as possible to the focused window.
60 There is only two splitting modes: 'automatic' and 'manual'.
62 The default mode is 'automatic'. The 'manual' mode is entered by sending a *preselection* message.
64 Example: insertion of a new node (number 4) into the given tree in 'automatic' mode:
74 +-------------------------+ +-------------------------+
78 | 3 |------------| --> | 4 |------------|
82 +-------------------------+ +-------------------------+
85 Same departure, but the mode is 'manual', and a *window --presel up* message was sent beforehand:
94 +-------------------------+ +-------------------------+
98 | 3 |------------| --> |------------|------------|
102 +-------------------------+ +-------------------------+
108 Each monitor contains at least one desktop.
110 Each desktop contains at most one tree.
116 DIR := left | right | up | down
117 CYCLE_DIR := next | prev
123 Selectors are used to select a target window, desktop, or monitor. A selector
124 can either describe the target relatively or name it globally.
126 Descriptive (relative) selectors consist of a primary selector and any number
127 of non-conflicting modifiers as follows:
129 PRIMARY_SELECTOR[.MODIFIER]*
131 For obvious reasons, neither desktops nor monitors names may be valid
132 descriptive selectors.
140 WINDOW_SEL := <window_id>
141 | (DIR|CYCLE_DIR|biggest|last|focused)[.floating|.tiled][.like|.unlike][.urgent|.nonurgent]
148 Selects the window in the given (spacial) direction relative to the active
152 Selects the window in the given (cyclic) direction.
155 Selects the biggest window on the current desktop.
158 Selects the previously focused window on the current desktop.
161 Selects the currently focused window.
167 Only consider floating windows.
170 Only consider tiled windows.
173 Only consider windows that have the same class as the current window.
176 Only consider windows that have a different class than the current window.
179 Only consider windows in automatic splitting mode.
182 Only consider windows in manual splitting mode (see *--presel*).
185 Only consider urgent windows.
188 Only consider nonurgent windows.
196 DESKTOP_SEL := <desktop_name>
197 | (CYCLE_DIR|last|focused)[.occupied|.free][.urgent|.nonurgent]
204 Selects the desktop in the given direction relative to the active desktop.
207 Selects the previously focused desktop.
210 Selects the currently focused desktop.
216 Only consider occupied desktops.
219 Only consider free desktops.
222 Only consider urgent desktops.
225 Only consider nonurgent desktops.
233 MONITOR_SEL := <monitor_name>
234 | (DIR|CYCLE_DIR|last|focused)[.occupied|.free]
241 Selects the monitor in the given (spacial) direction relative to the active monitor.
244 Selects the monitor in the given (cyclic) direction relative to the active monitor.
247 Selects the previously focused monitor.
250 Selects the currently focused monitor.
256 Only consider monitors where the focused desktop is occupied.
259 Only consider monitors where the focused desktop is free.
271 window ['WINDOW_SEL'] 'OPTIONS'
275 *-f*, *--focus* ['WINDOW_SEL']::
276 Focus the selected or given window.
278 *-d*, *--to-desktop* 'DESKTOP_SEL'::
279 Send the selected window to the given desktop.
281 *-m*, *--to-monitor* 'MONITOR_SEL'::
282 Send the selected window to the given monitor.
284 *-w*, *--to-window* 'WINDOW_SEL'::
285 Transplant the selected window to the given window.
287 *-s*, *--swap* 'WINDOW_SEL'::
288 Swap the selected window with the given window.
290 *-p*, *--presel* 'DIR'|cancel::
291 Preselect the splitting area of the selected window (or cancel the preselection).
293 *-r*, *--ratio* 'RATIO'::
294 Set the splitting ratio of the selected window (0 < 'RATIO' < 1).
296 *-e*, *--edge* 'DIR' 'RATIO'|pull|push::
297 Set the splitting ratio (or pull, or push) the edge located in the given direction in relation to the selected window.
299 *-t*, *--toggle* floating|fullscreen|locked[=on|off]::
300 Set or toggle the given state for the selected window.
303 Close the selected window.
306 Kill the selected window.
314 desktop ['DESKTOP_SEL'] 'OPTIONS'
318 *-f*, *--focus* ['DESKTOP_SEL']::
319 Focus the selected or given desktop.
321 *-m*, *--to-monitor* 'MONITOR_SEL'::
322 Send the selected desktop to the given monitor.
324 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
325 Set or cycle the layout of the selected desktop.
327 *-n*, *--rename* <new_name>::
328 Rename the selected desktop.
331 Remove the selected desktop.
333 *-c*, *--cancel-presel*::
334 Cancel the preselection of all the windows of the selected desktop.
336 *-F*, *--flip* 'horizontal|vertical'::
337 Flip the tree of the selected desktop.
339 *-R*, *--rotate* '90|270|180'::
340 Rotate the tree of the selected desktop.
343 Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
345 *-C*, *--circulate* forward|backward::
346 Circulate the leaves of the tree of the selected desktop.
354 monitor ['MONITOR_SEL'] 'OPTIONS'
358 *-f*, *--focus* ['MONITOR_SEL']::
359 Focus the selected or given monitor.
361 *-a*, *--add-desktops* <name>...::
362 Create desktops with the given names in the selected monitor.
364 *-r*, *--remove-desktops* <name>...::
365 Remove desktops with the given names.
367 *-p*, *--pad* <top> <right> <bottom> <left>::
368 Set the padding of the selected monitor.
370 *-n*, *--rename* <new_name>::
371 Rename the selected monitor.
384 List matching windows.
387 List matching desktops.
390 List matching monitors.
393 Print tree rooted at query.
396 Print the history as it relates to the query.
398 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
399 Constrain matches to the selected monitor, desktop or window.
412 *-T*, *--tree* <file_path>::
413 Load the desktop trees from the given file.
415 *-H*, *--history* <file_path>::
416 Load the focus history from the given file.
430 Manage all the unmanaged windows remaining from a previous session.
433 Write the current internal state to the panel FIFO.
435 *--toggle-visibility*::
436 Toggle the visibility of all the managed windows.
449 *-t*, *--track* <x> <y>::
450 Pass the pointer root coordinates for the current pointer action.
452 *-g*, *--grab* focus|move|resize_side|resize_corner::
453 Perform the given pointer action.
466 *-a*, *--add* <pattern> [-d 'DESKTOP_SEL' [--follow]] [--floating]::
467 Create a new rule (<pattern> must match the class or instance name).
469 *-r*, *--rm* <rule_uid>...::
470 Remove the rules with the given UIDs.
472 *-l*, *--list* [<pattern>]::
481 config <key> [<value>]::
482 Get or set the value of <key>.
491 Quit with an optional exit status.
495 Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'.
497 All the boolean settings are 'false' by default.
500 'focused_border_color'::
501 Color of the border of a focused window of a focused monitor.
503 'active_border_color'::
504 Color of the border of a focused window of an unfocused monitor.
506 'normal_border_color'::
507 Color of the border of an unfocused window.
509 'presel_border_color'::
510 Color of the *presel* message feedback.
512 'focused_locked_border_color'::
513 Color of the border of a focused locked window of a focused monitor.
515 'active_locked_border_color'::
516 Color of the border of a focused locked window of an unfocused monitor.
518 'normal_locked_border_color'::
519 Color of the border of an unfocused locked window.
521 'urgent_border_color'::
522 Color of the border of an urgent window.
528 Value of the gap that separates windows.
534 The value that shall be used for the '_NET_WM_NAME' property of the root window.
536 'borderless_monocle'::
537 Remove borders for tiled windows in monocle mode.
540 Remove gaps for tiled windows in monocle mode.
542 'focus_follows_pointer'::
543 Focus the window under the pointer.
545 'pointer_follows_monitor'::
546 When focusing a monitor, put the pointer at its center.
549 Prevent floating windows from being raised when they might cover other floating windows.
551 'apply_shadow_property'::
552 Enable shadows for floating windows via the '_COMPTON_SHADOW' property.
555 Interpret two consecutive identical *use* messages as an *alternate* message.
558 Interpret two consecutive identical *presel* messages as a *cancel* message.
560 'history_aware_focus'::
561 Give priority to the focus history when focusing nodes.
563 Environment Variables
564 ---------------------
567 The path of the socket used for the communication between *bspc* and *bspwm*.
572 * Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.).
573 * A custom panel if the '-s' flag is used (have a look at the files in 'examples/panel').
578 * Configured and controlled through messages.
579 * Multiple monitors support (via 'RandR').
580 * EWMH support (*tint2* works).
586 * Steven Allen <steven at stebalien.com>
587 * Thomas Adam <thomas at xteddy.org>
588 * Ivan Kanakarakis <ivan.kanak at gmail.com>
593 Bastien Dejean <baskerville at lavabit.com>
598 bspwm at librelist.com
601 vim: set ft=asciidoc: