:man source: Bspwm :man version: {revnumber} :man manual: Bspwm Manual bspwm(1) ======== Name ---- bspwm - Binary space partitioning window manager Synopsis -------- *bspwm* [*-h*|*-v*|*-c* 'CONFIG_PATH'|*-s* 'PANEL_FIFO'|*-p* 'PANEL_PREFIX'] *bspc* 'COMMAND' ['ARGUMENTS'] Description ----------- *bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree. It is controlled and configured via *bspc*. Options ------- *-h*:: Print the synopsis and exit. *-v*:: Print the version and exit. *-c* 'CONFIG_PATH':: Use the given configuration file. *-s* 'PANEL_FIFO':: Write the internal state to the given FIFO. *-p* 'PANEL_PREFIX':: Start every line written to the 'PANEL_FIFO' with the given prefix. Configuration ------------- *bspwm* has only two sources of informations: the X events it receives and the messages it reads on a dedicated socket. The default configuration file is '$XDG_CONFIG_HOME/bspwm/bspwmrc'. Keyboard and pointer bindings are defined with https://github.com/baskerville/sxhkd[sxhkd]. Example configuration files can be found in the *examples* directory. Splitting Modes --------------- New windows are inserted in the tree as close as possible to the focused window. There is only two splitting modes: 'automatic' and 'manual'. The default mode is 'automatic'. The 'manual' mode is entered by sending a *preselection* message. Example: insertion of a new node (number 4) into the given tree in 'automatic' mode: ---- b c / \ / \ 3 a --> 4 b ^ / \ ^ / \ 2 1 3 a / \ 2 1 +-------------------------+ +-------------------------+ | | | | | | | | 2 | | | 3 | | | | | | | | 3 |------------| --> | 4 |------------| | ^ | | | ^ | | | | | 1 | | | 1 | 2 | | | | | | | | +-------------------------+ +-------------------------+ ---- Same departure, but the mode is 'manual', and a *window --presel up* message was sent beforehand: ---- b b / \ / \ 3 a --> c a ^ / \ / \ / \ 2 1 4 3 2 1 ^ +-------------------------+ +-------------------------+ | | | | | | | | 2 | | 4 | 2 | | | | | ^ | | | 3 |------------| --> |------------|------------| | ^ | | | | | | | 1 | | 3 | 1 | | | | | | | +-------------------------+ +-------------------------+ ---- Containers ---------- Each monitor contains at least one desktop. Each desktop contains at most one tree. Common Definitions ------------------ ---- DIR := left | right | up | down CYCLE_DIR := next | prev ---- Selectors --------- Selectors are used to select a target window, desktop, or monitor. A selector can either describe the target relatively or name it globally. Descriptive (relative) selectors consist of a primary selector and any number of non-conflicting modifiers as follows: PRIMARY_SELECTOR[.MODIFIER]* For obvious reasons, neither desktops nor monitors names may be valid descriptive selectors. Window ~~~~~~ Select a window. ---- WINDOW_SEL := | (DIR|CYCLE_DIR|biggest|last|last_local|older|newer|focused)[.floating|.tiled][.like|.unlike][.automatic|.manual][.urgent|.nonurgent] ---- Primary Selectors ^^^^^^^^^^^^^^^^^ 'DIR':: Selects the window in the given (spacial) direction relative to the active window. 'CYCLE_DIR':: Selects the window in the given (cyclic) direction. biggest:: Selects the biggest window on the current desktop. last:: Selects the previously focused window. last_local:: Selects the previously focused window on the current desktop. older:: Selects the window older than the focused window in the history. newer:: Selects the window newer than the focused window in the history. focused:: Selects the currently focused window. Modifiers ^^^^^^^^^ floating:: Only consider floating windows. tiled:: Only consider tiled windows. like:: Only consider windows that have the same class as the current window. unlike:: Only consider windows that have a different class than the current window. automatic:: Only consider windows in automatic splitting mode. manual:: Only consider windows in manual splitting mode (see *--presel*). urgent:: Only consider urgent windows. nonurgent:: Only consider nonurgent windows. Desktop ~~~~~~~ Select a desktop. ---- DESKTOP_SEL := | ^ | (CYCLE_DIR|last|last_local|focused)[.occupied|.free][.urgent|.nonurgent] ---- Primary Selectors ^^^^^^^^^^^^^^^^^ :: Selects the desktop with the given name. ^:: Selects the nth desktop. 'CYCLE_DIR':: Selects the desktop in the given direction relative to the active desktop. last:: Selects the previously focused desktop. last_local:: Selects the previously focused desktop on the current monitor. focused:: Selects the currently focused desktop. Modifiers ^^^^^^^^^ occupied:: Only consider occupied desktops. free:: Only consider free desktops. urgent:: Only consider urgent desktops. nonurgent:: Only consider nonurgent desktops. Monitor ~~~~~~~ Select a monitor. ---- MONITOR_SEL := | ^ | (DIR|CYCLE_DIR|last|primary|focused)[.occupied|.free] ---- Primary Selectors ^^^^^^^^^^^^^^^^^ :: Selects the monitor with the given name. ^:: Selects the nth monitor. 'DIR':: Selects the monitor in the given (spacial) direction relative to the active monitor. 'CYCLE_DIR':: Selects the monitor in the given (cyclic) direction relative to the active monitor. primary:: Selects the primary monitor. last:: Selects the previously focused monitor. focused:: Selects the currently focused monitor. Modifiers ^^^^^^^^^ occupied:: Only consider monitors where the focused desktop is occupied. free:: Only consider monitors where the focused desktop is free. Commands -------- Window ~~~~~~ General Syntax ^^^^^^^^^^^^^^ window ['WINDOW_SEL'] 'OPTIONS' Options ^^^^^^^ *-f*, *--focus* ['WINDOW_SEL']:: Focus the selected or given window. *-d*, *--to-desktop* 'DESKTOP_SEL':: Send the selected window to the given desktop. *-m*, *--to-monitor* 'MONITOR_SEL':: Send the selected window to the given monitor. *-w*, *--to-window* 'WINDOW_SEL':: Transplant the selected window to the given window. *-s*, *--swap* 'WINDOW_SEL':: Swap the selected window with the given window. *-p*, *--presel* 'DIR'|cancel:: Preselect the splitting area of the selected window (or cancel the preselection). *-r*, *--ratio* 'RATIO':: Set the splitting ratio of the selected window (0 < 'RATIO' < 1). *-e*, *--edge* 'DIR' 'RATIO'|pull|push:: Set the splitting ratio (or pull, or push) the edge located in the given direction in relation to the selected window. *-R*, *--rotate* 'DIR' '90|270|180':: Rotate the tree holding the edge located in the given direction in relation to the selected window. *-t*, *--toggle* floating|fullscreen|locked|sticky|visible[=on|off]:: Set or toggle the given state for the selected window. *-c*, *--close*:: Close the selected window. *-k*, *--kill*:: Kill the selected window. Desktop ~~~~~~~ General Syntax ^^^^^^^^^^^^^^ desktop ['DESKTOP_SEL'] 'OPTIONS' Options ^^^^^^^ *-f*, *--focus* ['DESKTOP_SEL']:: Focus the selected or given desktop. *-m*, *--to-monitor* 'MONITOR_SEL':: Send the selected desktop to the given monitor. *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled:: Set or cycle the layout of the selected desktop. *-n*, *--rename* :: Rename the selected desktop. *-s*, *--swap* 'DESKTOP_SEL':: Swap the selected desktop with the given desktop. *-r*, *--remove*:: Remove the selected desktop. *-c*, *--cancel-presel*:: Cancel the preselection of all the windows of the selected desktop. *-F*, *--flip* 'horizontal|vertical':: Flip the tree of the selected desktop. *-R*, *--rotate* '90|270|180':: Rotate the tree of the selected desktop. *-B*, *--balance*:: Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area. *-C*, *--circulate* forward|backward:: Circulate the leaves of the tree of the selected desktop. Monitor ~~~~~~~ General Syntax ^^^^^^^^^^^^^^ monitor ['MONITOR_SEL'] 'OPTIONS' Options ^^^^^^^ *-f*, *--focus* ['MONITOR_SEL']:: Focus the selected or given monitor. *-a*, *--add-desktops* ...:: Create desktops with the given names in the selected monitor. *-r*, *--remove-desktops* ...:: Remove desktops with the given names. *-n*, *--rename* :: Rename the selected monitor. *-d*, *--reset-desktops* ...:: Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops. *-s*, *--swap* 'MONITOR_SEL':: Swap the selected monitor with the given monitor. Tag ~~~ General Syntax ^^^^^^^^^^^^^^ tag 'OPTIONS' Options ^^^^^^^ *-l*, *--list*:: List the tags. *-a*, *--add* ...:: Create tags with the given names. *-r*, *--remove* |^...:: Remove tags with the given names or indexes. *-e*, *--enumerate-tags* ...:: Rename, add or remove tags depending on whether the number of given names is equal, superior or inferior to the number of existing tags. *-d*, *--desktop* 'DESKTOP_SEL':: Select the given desktop as target for the *-s* and *-t* options. *-w*, *--window* 'WINDOW_SEL':: Select the given window as target for the *-s* and *-t* options. *-s*, *--set-tags* (|^...)|all:: Set the tags of the selected object. *-t*, *--toggle-tags* (|^)[=on|off]...:: Toggle the tags of the selected object. Query ~~~~~ General Syntax ^^^^^^^^^^^^^^ query 'OPTIONS' Options ^^^^^^^ *-W*, *--windows*:: List matching windows. *-D*, *--desktops*:: List matching desktops. *-M*, *--monitors*:: List matching monitors. *-T*, *--tree*:: Print tree rooted at query. *-H*, *--history*:: Print the history as it relates to the query. *-S*, *--stack*:: Print the window stacking order. [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]:: Constrain matches to the selected monitor, desktop or window. Restore ~~~~~~~ General Syntax ^^^^^^^^^^^^^^ restore 'OPTIONS' Options ^^^^^^^ *-T*, *--tree* :: Load the desktop trees from the given file. *-H*, *--history* :: Load the focus history from the given file. *-S*, *--stack* :: Load the window stacking order from the given file. Control ~~~~~~~ General Syntax ^^^^^^^^^^^^^^ control 'OPTIONS' Options ^^^^^^^ *--adopt-orphans*:: Manage all the unmanaged windows remaining from a previous session. *--put-status*:: Write the current internal state to the panel FIFO. *--toggle-visibility*:: Toggle the visibility of all the windows. Pointer ~~~~~~~ General Syntax ^^^^^^^^^^^^^^ pointer 'OPTIONS' Options ^^^^^^^ *-t*, *--track* :: Pass the pointer root coordinates for the current pointer action. *-g*, *--grab* focus|move|resize_side|resize_corner:: Perform the given pointer action. Rule ~~~~ General Syntax ^^^^^^^^^^^^^^ rule 'OPTIONS' Options ^^^^^^^ *-a*, *--add* | [-d 'DESKTOP_SEL' [--follow]] [--tags |^[,...]][--floating] [--fullscreen] [--locked] [--sticky] [--focus] [--unmanage] [--one-shot]:: Create a new rule. *-r*, *--remove* |^|tail|head...:: Remove the rules with the given names or indexes. *-l*, *--list* []:: List the rules. Config ~~~~~~ General Syntax ^^^^^^^^^^^^^^ config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'] []:: Get or set the value of . Quit ~~~~ General Syntax ^^^^^^^^^^^^^^ quit []:: Quit with an optional exit status. Settings -------- Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'. All the boolean settings are 'false' by default. Global Settings ~~~~~~~~~~~~~~~ 'focused_border_color':: Color of the border of a focused window of a focused monitor. 'active_border_color':: Color of the border of a focused window of an unfocused monitor. 'normal_border_color':: Color of the border of an unfocused window. 'presel_border_color':: Color of the *presel* message feedback. 'focused_locked_border_color':: Color of the border of a focused locked window of a focused monitor. 'active_locked_border_color':: Color of the border of a focused locked window of an unfocused monitor. 'normal_locked_border_color':: Color of the border of an unfocused locked window. 'focused_sticky_border_color':: Color of the border of a focused sticky window of a focused monitor. 'active_sticky_border_color':: Color of the border of a focused sticky window of an unfocused monitor. 'normal_sticky_border_color':: Color of the border of an unfocused sticky window. 'urgent_border_color':: Color of the border of an urgent window. 'split_ratio':: Default split ratio. 'growth_factor':: Intensity of the growth involved in pulling or pushing an edge. 'history_aware_focus':: Give priority to the focus history when focusing nodes. 'borderless_monocle':: Remove borders for tiled windows in monocle mode. 'gapless_monocle':: Remove gaps for tiled windows in monocle mode. 'focus_follows_pointer':: Focus the window under the pointer. 'pointer_follows_monitor':: When focusing a monitor, put the pointer at its center. 'auto_alternate':: Interpret two consecutive identical *use* messages as an *alternate* message. 'auto_cancel':: Interpret two consecutive identical *presel* messages as a *cancel* message. 'apply_floating_atom':: Set the value of the '_BSPWM_FLOATING_WINDOW' atom of each window according to its floating state. 'honor_ewmh_focus':: Honor EWMH requests to focus a window. Monitor Settings ~~~~~~~~~~~~~~~~ 'top_padding':: 'right_padding':: 'bottom_padding':: 'left_padding':: Padding space added at the sides of the monitor. Desktop Settings ~~~~~~~~~~~~~~~~ 'window_gap':: Size of the gap that separates windows. 'border_width':: Window border width. Environment Variables --------------------- 'BSPWM_SOCKET':: The path of the socket used for the communication between *bspc* and *bspwm*. If it isn't defined, then the following path is used: '/tmp/bspwm-socket'. Panels ------ * Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.). * A custom panel if the '-s' flag is used (have a look at the files in 'examples/panel'). Key Features ------------ * Configured and controlled through messages. * Multiple monitors support (via 'RandR'). * EWMH support (*tint2* works). * Hybrid tiling. Contributors ------------ * Steven Allen * Thomas Adam * Ivan Kanakarakis Author ------ Bastien Dejean Mailing List ------------ bspwm at librelist.com //// vim: set ft=asciidoc: ////