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]
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*).
190 DESKTOP_SEL := <desktop_name>
191 | (CYCLE_DIR|last|focused)[.occupied|.free]
198 Selects the desktop in the given direction relative to the active desktop.
201 Selects the previously focused desktop.
204 Selects the currently focused desktop.
210 Only consider occupied desktops.
213 Only consider free desktops.
221 MONITOR_SEL := <monitor_name>
222 | (DIR|CYCLE_DIR|last|focused)[.occupied|.free]
229 Selects the monitor in the given (spacial) direction relative to the active monitor.
232 Selects the monitor in the given (cyclic) direction relative to the active monitor.
235 Selects the previously focused monitor.
238 Selects the currently focused monitor.
244 Only consider monitors where the focused desktop is occupied.
247 Only consider monitors where the focused desktop is free.
259 window ['WINDOW_SEL'] 'OPTIONS'
263 *-f*, *--focus* ['WINDOW_SEL']::
264 Focus the selected or given window.
266 *-d*, *--to-desktop* 'DESKTOP_SEL'::
267 Send the selected window to the given desktop.
269 *-m*, *--to-monitor* 'MONITOR_SEL'::
270 Send the selected window to the given monitor.
272 *-w*, *--to-window* 'WINDOW_SEL'::
273 Transplant the selected window to the given window.
275 *-s*, *--swap* 'WINDOW_SEL'::
276 Swap the selected window with the given window.
278 *-p*, *--presel* 'DIR'|cancel::
279 Preselect the splitting area of the selected window (or cancel the preselection).
281 *-r*, *--ratio* 'RATIO'::
282 Set the splitting ratio of the selected window.
284 *-e*, *--edge* 'DIR' 'RATIO'|pull|push::
285 Set the splitting ratio (or pull, or push) the edge located in the given direction in relation to the selected window.
287 *-t*, *--toggle* floating|fullscreen|locked[=on|off]::
288 Set or toggle the given state for the selected window.
291 Close the selected window.
294 Kill the selected window.
302 desktop ['DESKTOP_SEL'] 'OPTIONS'
306 *-f*, *--focus* ['DESKTOP_SEL']::
307 Focus the selected or given desktop.
309 *-m*, *--to-monitor* 'MONITOR_SEL'::
310 Send the selected desktop to the given monitor.
312 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
313 Set or cycle the layout of the selected desktop.
315 *-n*, *--rename* <new_name>::
316 Rename the selected desktop.
319 Remove the selected desktop.
321 *-c*, *--cancel-presel*::
322 Cancel the preselection of all the windows of the selected desktop.
324 *-F*, *--flip* 'horizontal|vertical'::
325 Flip the tree of the selected desktop.
327 *-R*, *--rotate* '90|270|180'::
328 Rotate the tree of the selected desktop.
331 Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
333 *-C*, *--circulate* forward|backward::
334 Circulate the leaves of the tree of the selected desktop.
342 monitor ['MONITOR_SEL'] 'OPTIONS'
346 *-f*, *--focus* ['MONITOR_SEL']::
347 Focus the selected or given monitor.
349 *-a*, *--add-desktops* <name>...::
350 Create desktops with the given names in the selected monitor.
352 *-r*, *--remove-desktops* <name>...::
353 Remove desktops with the given names.
355 *-p*, *--pad* [<top> <right> <bottom> <left>]::
356 Set or get the padding of the selected monitor.
358 *-n*, *--rename* <new_name>::
359 Rename the selected monitor.
372 List matching windows.
375 List matching desktops.
378 List matching monitors.
381 Print tree rooted at query.
384 Print the history as it relates to the query.
386 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
387 Constrain matches to the selected monitor, desktop or window.
400 *-T*, *--tree* <file_path>::
401 Load the desktop trees from the given file.
403 *-H*, *--history* <file_path>::
404 Load the focus history from the given file.
418 Manage all the unmanaged windows remaining from a previous session.
421 Write the current internal state to the panel FIFO.
423 *--toggle-visibility*::
424 Toggle the visibility of all the managed windows.
437 *-t*, *--track* <x> <y>::
438 Pass the pointer root coordinates for the current pointer action.
440 *-g*, *--grab* focus|move|resize_side|resize_corner::
441 Perform the given pointer action.
454 *-a*, *--add* <pattern> [-d 'DESKTOP_SEL'] [--floating] [--follow]::
455 Create a new rule (<pattern> must match the class or instance name).
457 *-r*, *--rm* <rule_uid>...::
458 Remove the rules with the given UIDs.
460 *-l*, *--list* [<pattern>]::
469 config <key> [<value>]::
470 Get or set the value of <key>.
479 Quit with an optional exit status.
483 Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'.
485 All the boolean settings are 'false' by default.
488 'focused_border_color'::
489 Color of the border of a focused window of a focused monitor.
491 'active_border_color'::
492 Color of the border of a focused window of an unfocused monitor.
494 'normal_border_color'::
495 Color of the border of an unfocused window.
497 'presel_border_color'::
498 Color of the *presel* message feedback.
500 'focused_locked_border_color'::
501 Color of the border of a focused locked window of a focused monitor.
503 'active_locked_border_color'::
504 Color of the border of a focused locked window of an unfocused monitor.
506 'normal_locked_border_color'::
507 Color of the border of an unfocused locked window.
509 'urgent_border_color'::
510 Color of the border of an urgent window.
516 Value of the gap that separates windows.
522 The value that shall be used for the '_NET_WM_NAME' property of the root window.
524 'borderless_monocle'::
525 Remove borders for tiled windows in monocle mode.
528 Remove gaps for tiled windows in monocle mode.
530 'focus_follows_pointer'::
531 Focus the window under the pointer.
533 'pointer_follows_monitor'::
534 When focusing a monitor, put the pointer at its center.
537 Prevent floating windows from being raised when they might cover other floating windows.
539 'apply_shadow_property'::
540 Enable shadows for floating windows via the '_COMPTON_SHADOW' property.
543 Interpret two consecutive identical *use* messages as an *alternate* message.
546 Interpret two consecutive identical *presel* messages as a *cancel* message.
548 'history_aware_focus'::
549 Give priority to the focus history when focusing nodes.
551 Environment Variables
552 ---------------------
555 The path of the socket used for the communication between *bspc* and *bspwm*.
560 * Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.).
561 * A custom panel if the '-s' flag is used (have a look at the files in 'examples/panel').
566 * Configured and controlled through messages.
567 * Multiple monitors support (via 'RandR').
568 * EWMH support (*tint2* works).
574 * Steven Allen <steven at stebalien.com>
575 * Thomas Adam <thomas at xteddy.org>
576 * Ivan Kanakarakis <ivan.kanak at gmail.com>
581 Bastien Dejean <baskerville at lavabit.com>
586 bspwm at librelist.com
589 vim: set ft=asciidoc: