1 image:https://github.com/baskerville/bspwm/raw/master/logo/bspwm-logo.png[logo]
4 :man version: {revnumber}
5 :man manual: Bspwm Manual
13 bspwm - Tiling window manager based on binary space partitioning
18 *bspwm* [*-h*|*-v*|*-s* 'PANEL_FIFO'|*-p* 'PANEL_PREFIX']
20 *bspc* 'COMMAND' ['ARGUMENTS']
25 *bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree.
27 It is controlled and configured via *bspc*.
34 Print the synopsis and exit.
37 Print the version and exit.
40 Write the internal state to the given FIFO.
43 Start every line written to the 'PANEL_FIFO' with the given prefix.
49 *bspwm* have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
51 Its configuration file is '$XDG_CONFIG_HOME/bspwm/autostart'.
53 Keyboard and pointer bindings are defined with https://github.com/baskerville/sxhkd[sxhkd].
55 Example configuration files can be found in the *examples* directory.
60 New windows are inserted in the tree as close as possible to the focused window.
62 There is only two splitting modes: 'automatic' and 'manual'.
64 The default mode is 'automatic'. The 'manual' mode is entered by sending a *preselection* message.
66 Example: insertion of a new node (number 4) into the given tree in 'automatic' mode:
76 +-------------------------+ +-------------------------+
80 | 3 |------------| --> | 4 |------------|
84 +-------------------------+ +-------------------------+
87 Same departure, but the mode is 'manual', and a *window --presel up* message was sent beforehand:
96 +-------------------------+ +-------------------------+
100 | 3 |------------| --> |------------|------------|
104 +-------------------------+ +-------------------------+
110 Each monitor contains at least one desktop.
112 Each desktop contains at most one tree.
118 DIR := left | right | up | down
119 CYCLE_DIR := next | prev
125 Selectors are used to select a target window, desktop, or monitor. A selector
126 can either describe the target relatively or name it globally.
128 Descriptive (relative) selectors consist of a primary selector and any number
129 of non-conflicting modifiers as follows:
131 PRIMARY_SELECTOR[.MODIFIER]*
133 For obvious reasons, neither desktops nor monitors names may be valid
134 descriptive selectors.
142 WINDOW_SEL := <window_id>
143 | (DIR|CYCLE_DIR|biggest|last|focused)[.floating|.tiled][.like|.unlike]
150 Selects the window in the given (spacial) direction relative to the active
154 Selects the window in the given (cyclic) direction.
157 Selects the biggest window on the current desktop.
160 Selects the previously focused window on the current desktop.
163 Selects the currently focused window.
169 Only consider floating windows.
172 Only consider tiled windows.
175 Only consider windows that have the same class as the current window.
178 Only consider windows that have a different class than the current window.
186 DESKTOP_SEL := <desktop_name>
187 | (CYCLE_DIR|last|focused)[.occupied|.free]
194 Selects the desktop in the given direction relative to the active desktop.
197 Selects the previously focused focused desktop.
200 Selects the currently focused desktop.
206 Only consider occupied desktops.
209 Only consider free desktops.
217 MONITOR_SEL := <monitor_name>
218 | (DIR|CYCLE_DIR|last|focused)[.occupied|.free]
225 Selects the monitor in the given (spacial) direction relative to the active monitor.
228 Selects the monitor in the given (cyclic) direction relative to the active monitor.
231 Selects the previously focused focused monitor.
234 Selects the currently focused monitor.
240 Only consider monitors where the focused desktop is occupied.
243 Only consider monitors where the focused desktop is free.
255 window ['WINDOW_SEL'] 'OPTIONS'
259 *-f*, *--focus* ['WINDOW_SEL']::
260 Focus the selected or given window.
262 *-d*, *--to-desktop* 'DESKTOP_SEL'::
263 Send the selected window to the given desktop.
265 *-m*, *--to-monitor* 'MONITOR_SEL'::
266 Send the selected window to the given monitor.
268 *-w*, *--to-window* 'WINDOW_SEL'::
269 Transplant the selected window to the given window.
271 *-s*, *--swap* 'WINDOW_SEL'::
272 Swap the selected window with the given window.
274 *-p*, *--presel* 'DIR'|cancel::
275 Preselect the splitting area of the selected window (or cancel the preselection).
277 *-r*, *--ratio* 'RATIO'::
278 Set the splitting ratio of the selected window.
280 *-e*, *--edge* 'DIR' 'RATIO'|pull|push::
281 Set the splitting ratio (or pull, or push) the edge located in the given direction in relation to the selected window.
283 *-t*, *--toggle* floating|fullscreen|locked[=on|off]::
284 Set or toggle the given state for the selected window.
287 Close the selected window.
290 Kill the selected window.
298 desktop ['DESKTOP_SEL'] 'OPTIONS'
302 *-f*, *--focus* ['DESKTOP_SEL']::
303 Focus the selected or given desktop.
305 *-m*, *--to-monitor* 'MONITOR_SEL'::
306 Send the selected desktop to the given monitor.
308 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
309 Set or cycle the layout of the selected desktop.
311 *-n*, *--rename* <new_name>::
312 Rename the selected desktop.
315 Remove the selected desktop.
317 *-c*, *--cancel-presel*::
318 Cancel the preselection of all the windows of the selected desktop.
320 *-F*, *--flip* 'horizontal|vertical'::
321 Flip the tree of the selected desktop.
323 *-R*, *--rotate* '90|270|180'::
324 Rotate the tree of the selected desktop.
327 Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
329 *-C*, *--circulate* forward|backward::
330 Circulate the leaves of the tree of the selected desktop.
338 monitor ['MONITOR_SEL'] 'OPTIONS'
342 *-f*, *--focus* ['MONITOR_SEL']::
343 Focus the selected or given monitor.
345 *-a*, *--add-desktops* <name>...::
346 Create desktops with the given names in the selected monitor.
348 *-r*, *--remove-desktops* <name>...::
349 Remove desktops with the given names.
351 *-p*, *--pad* <top> <right> <bottom> <left>::
352 Set the padding of the selected monitor.
354 *-n*, *--rename* <new_name>::
355 Rename the selected monitor.
368 List matching windows.
371 List matching desktops.
374 List matching monitors.
377 Print tree rooted at query.
380 Print the history as it relates to the query.
382 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
383 Constrain matches to the selected monitor, desktop or window.
396 *-T*, *--tree* <file_path>::
397 Load the desktop trees from the given file.
399 *-H*, *--history* <file_path>::
400 Load the focus history from the given file.
413 *--adopt-orphans* <file_path>::
414 Manage all the unmanaged windows remaining from a previous session.
416 *--put-status* <file_path>::
417 Write the current internal state to the panel FIFO.
419 *--toggle-visibility*::
420 Toggle the visibility of all the managed windows.
433 *-t*, *--track* <x> <y>::
434 Pass the pointer root coordinates for the current pointer action.
436 *-g*, *--grab* focus|move|resize_side|resize_corner::
437 Perform the given pointer action.
450 *-a*, *--add* <pattern> [-d 'DESKTOP_SEL'] [--floating] [--follow]::
451 Create a new rule (<pattern> must match the class or instance name).
453 *-r*, *--rm* <rule_uid>...::
454 Remove the rules with the given UIDs.
456 *-l*, *--list* [<pattern>]::
465 config <key> [<value>]::
466 Get or set the value of <key>.
475 Quit with an optional exit status.
479 Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'.
481 All the boolean settings are 'false' by default.
484 'focused_border_color'::
485 Color of the border of a focused window of a focused monitor.
487 'active_border_color'::
488 Color of the border of a focused window of an unfocused monitor.
490 'normal_border_color'::
491 Color of the border of an unfocused window.
493 'presel_border_color'::
494 Color of the *presel* message feedback.
496 'focused_locked_border_color'::
497 Color of the border of a focused locked window of a focused monitor.
499 'active_locked_border_color'::
500 Color of the border of a focused locked window of an unfocused monitor.
502 'normal_locked_border_color'::
503 Color of the border of an unfocused locked window.
505 'urgent_border_color'::
506 Color of the border of an urgent window.
512 Value of the gap that separates windows.
521 Padding space added at the sides of the current monitor.
524 The value that shall be used for the '_NET_WM_NAME' property of the root window.
526 'borderless_monocle'::
527 Remove borders for tiled windows in monocle mode.
530 Remove gaps for tiled windows in monocle mode.
532 'focus_follows_pointer'::
533 Focus the window under the pointer.
535 'pointer_follows_monitor'::
536 When focusing a monitor, put the pointer at its center.
538 'monitor_focus_fallback'::
539 If the focus message fails, try to focus the nearest monitor in the same direction.
542 Prevent floating windows from being raised when they might cover other floating windows.
544 'apply_shadow_property'::
545 Enable shadows for floating windows via the '_COMPTON_SHADOW' property.
548 Interpret two consecutive identical *use* messages as an *alternate* message.
551 Interpret two consecutive identical *presel* messages as a *cancel* message.
553 'focus_by_distance'::
554 Use window or leaf distance for focus movement.
556 'history_aware_focus'::
557 Give priority to the focus history when focusing nodes.
559 Environment Variables
560 ---------------------
563 The path of the socket used for the communication between *bspc* and *bspwm*.
568 * Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.).
569 * A custom panel if the '-s' flag is used (have a look at the files in 'examples/panel').
574 * Configured and controlled through messages.
575 * Multiple monitors support (via 'RandR').
576 * EWMH support (*tint2* works).
582 * Steven Allen <steven at stebalien.com>
583 * Thomas Adam <thomas at xteddy.org>
584 * Ivan Kanakarakis <ivan.kanak at gmail.com>
589 Bastien Dejean <baskerville at lavabit.com>
594 bspwm at librelist.com
597 vim: set ft=asciidoc: