bspwm/doc/bspwm.1.asciidoc

: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']

*bspc* 'DOMAIN' ['SELECTOR'] 'COMMANDS'

*bspc* 'COMMAND' ['OPTIONS'] ['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.

Common Definitions
------------------

----
DIR         := north | west | south | east
CYCLE_DIR   := next | prev
----

Selectors
---------

Selectors are used to select a target node, desktop, or monitor. A selector
can either describe the target relatively or name it globally.

Selectors consist of an optional reference, a descriptor and any number of
non-conflicting modifiers as follows:

	[REFERENCE#]DESCRIPTOR(.MODIFIER)*

The relative targets are computed in relation to the given reference (the
default reference value is *focused*).

An exclamation mark can be prepended to any modifier in order to reverse its
meaning.

Node
~~~~

Select a node.

----
NODE_SEL := [NODE_SEL#](DIR|CYCLE_DIR|PATH|last|older|newer|focused|pointed|biggest|<node_id>)[.[!]focused][.[!]automatic][.[!]local][.[!]active][.[!]leaf][.[!]window][.[!]STATE][.[!]FLAG][.[!]LAYER][.[!]same_class][.[!]descendant_of][.[!]ancestor_of]

STATE := tiled|pseudo_tiled|floating|fullscreen

FLAG := hidden|sticky|private|locked|urgent

LAYER := below|normal|above

PATH := @[DESKTOP_SEL:][[/]JUMP](/JUMP)*

JUMP := first|1|second|2|brother|parent|DIR
----

Descriptors
^^^^^^^^^^^

'DIR'::
	Selects the window in the given (spacial) direction relative to the reference node.

'CYCLE_DIR'::
	Selects the window in the given (cyclic) direction relative to the reference node.

'PATH'::
	Selects the node at the given path.

last::
	Selects the previously focused node relative to the reference node.

older::
	Selects the node older than the reference node in the history.

newer::
	Selects the node newer than the reference node in the history.

focused::
	Selects the currently focused node.

pointed::
	Selects the window under the pointer.

biggest::
	Selects the biggest window.

<node_id>::
	Selects the node with the given ID.

Path Jumps
^^^^^^^^^^

The initial node is the focused node (or the root if the path starts with '/') of the reference desktop (or the selected desktop if the path has a 'DESKTOP_SEL' prefix).

1|first::
	Jumps to the first child.

2|second::
	Jumps to the second child.

brother::
	Jumps to the brother node.

parent::
	Jumps to the parent node.

'DIR'::
	Jumps to the node holding the edge in the given direction.

Modifiers
^^^^^^^^^

[!]focused::
	Only consider focused or unfocused nodes.

[!]automatic::
	Only consider nodes in automatic or manual insertion mode. See also *--presel-dir* under *Node* in the *DOMAINS* section below.

[!]local::
	Only consider nodes in or not in the reference desktop.

[!]active::
	Only consider nodes in or not in the active desktop of their monitor.

[!]leaf::
	Only consider leaves or internal nodes.

[!]window::
	Only consider nodes that hold or don't hold a window.

[!](tiled|pseudo_tiled|floating|fullscreen)::
	Only consider windows in or not in the given state.

[!]same_class::
	Only consider windows that have or don't have the same class as the reference window.

[!]descendant_of::
	Only consider nodes that are or aren't descendants of the reference node.

[!]ancestor_of::
	Only consider nodes that are or aren't ancestors of the reference node.

[!](hidden|sticky|private|locked|urgent)::
	Only consider windows that have or don't have the given flag set.

[!](below|normal|above)::
	Only consider windows in or not in the given layer.

Desktop
~~~~~~~

Select a desktop.

----
DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|last|older|newer|[MONITOR_SEL:](focused|^<n>)|<desktop_id>|<desktop_name>)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
----

Descriptors
^^^^^^^^^^^

'CYCLE_DIR'::
	Selects the desktop in the given direction relative to the reference desktop.

last::
	Selects the previously focused desktop relative to the reference desktop.

older::
	Selects the desktop older than the reference desktop in the history.

newer::
	Selects the desktop newer than the reference desktop in the history.

focused::
	Selects the currently focused desktop.

^<n>::
	Selects the nth desktop.

<desktop_id>::
	Selects the desktop with the given ID.

<desktop_name>::
	Selects the desktop with the given name.

Modifiers
^^^^^^^^^

[!]occupied::
	Only consider occupied or free desktops.

[!]focused::
	Only consider focused or unfocused desktops.

[!]urgent::
	Only consider urgent or non urgent desktops.

[!]local::
	Only consider desktops inside or outside of the reference monitor.

Monitor
~~~~~~~

Select a monitor.

----
MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|last|older|newer|focused|primary|^<n>|<monitor_id>|<monitor_name>)[.[!]occupied][.[!]focused]
----

Descriptors
^^^^^^^^^^^

'DIR'::
	Selects the monitor in the given (spacial) direction relative to the reference monitor.

'CYCLE_DIR'::
	Selects the monitor in the given (cyclic) direction relative to the reference monitor.

last::
	Selects the previously focused monitor relative to the reference monitor.

older::
	Selects the monitor older than the reference monitor in the history.

newer::
	Selects the monitor newer than the reference monitor in the history.

focused::
	Selects the currently focused monitor.

primary::
	Selects the primary monitor.

^<n>::
	Selects the nth monitor.

<monitor_id>::
	Selects the monitor with the given ID.

<monitor_name>::
	Selects the monitor with the given name.


Modifiers
^^^^^^^^^

[!]occupied::
	Only consider monitors where the focused desktop is occupied or free.

[!]focused::
	Only consider focused or unfocused monitors.


Window States
-------------

tiled::
	Its size and position are determined by the splitting type and ratio of each node of its path in the window tree.

pseudo_tiled::
	Has an unrestricted size while being centered in its tiling space.

floating::
	Can be moved/resized freely. Although it doesn't occupy any tiling space, it is still part of the window tree.

fullscreen::
	Fills its monitor rectangle and has no borders. It is send in the ABOVE layer by default.


Node Flags
----------

hidden::
	Is hidden and doesn't occupy any tiling space.

sticky::
	Stays in the focused desktop of its monitor.

private::
	Tries to keep the same tiling position/size.

locked::
	Ignores the *node --close* message.

urgent::
	Has its urgency hint set. This flag is set externally.


Stacking Layers
--------------

There's three stacking layers: BELOW, NORMAL and ABOVE.

In each layer, the window are orderered as follow: tiled & pseudo-tiled < fullscreen < floating.


Domains
-------

Node
~~~~

General Syntax
^^^^^^^^^^^^^^

node ['NODE_SEL'] 'COMMANDS'

If 'NODE_SEL' is omitted, *focused* is assumed.

Commands
^^^^^^^^
*-f*, *--focus* ['NODE_SEL']::
	Focus the selected or given node.

*-a*, *--activate* ['NODE_SEL']::
	Activate the selected or given node.

*-d*, *--to-desktop* 'DESKTOP_SEL'::
	Send the selected node to the given desktop.

*-m*, *--to-monitor* 'MONITOR_SEL'::
	Send the selected node to the given monitor.

*-n*, *--to-node* 'NODE_SEL'::
	Transplant the selected node to the given node.

*-s*, *--swap* 'NODE_SEL'::
	Swap the selected node with the given node.

*-p*, *--presel-dir* \[~]'DIR'|cancel::
	Preselect the splitting area of the selected node (or cancel the preselection). If *~* is prepended to 'DIR' and the current preselection direction matches 'DIR', then the argument is interpreted as *cancel*. A node with a preselected area is said to be in "manual insertion mode".

*-o*, *--presel-ratio* 'RATIO'::
	Set the splitting ratio of the preselection area.

*-v*, *--move* 'dx' 'dy'::
	Move the selected window by 'dx' pixels horizontally and 'dy' pixels vertically.

*-z*, *--resize* top|left|bottom|right|top_left|top_right|bottom_right|bottom_left 'dx' 'dy'::
	Resize the selected window by moving the given handle by 'dx' pixels horizontally and 'dy' pixels vertically.

*-r*, *--ratio* 'RATIO'|(+|-)('PIXELS'|'FRACTION')::
	Set the splitting ratio of the selected node (0 < 'RATIO' < 1).

*-R*, *--rotate* '90|270|180'::
	Rotate the tree rooted at the selected node.

*-F*, *--flip* 'horizontal|vertical'::
	Flip the the tree rooted at selected node.

*-E*, *--equalize*::
	Reset the split ratios of the tree rooted at the selected node to their default value.

*-B*, *--balance*::
	Adjust the split ratios of the tree rooted at the selected node so that all windows occupy the same area.

*-C*, *--circulate* forward|backward::
	Circulate the windows of the tree rooted at the selected node.

*-t*, *--state* [~](tiled|pseudo_tiled|floating|fullscreen)::
	Set the state of the selected window. If *~* is present and the current state matches the given state, then the argument is interpreted as the last state.

*-g*, *--flag* hidden|sticky|private|locked[=on|off]::
	Set or toggle the given flag for the selected node.

*-l*, *--layer* below|normal|above::
	Set the stacking layer of the selected window.

*-i*, *--insert-receptacle*::
	Insert a receptacle node at the selected node.

*-c*, *--close*::
	Close the windows rooted at the selected node.

*-k*, *--kill*::
	Kill the windows rooted at the selected node.

Desktop
~~~~~~~

General Syntax
^^^^^^^^^^^^^^

desktop ['DESKTOP_SEL'] 'COMMANDS'

If 'DESKTOP_SEL' is omitted, *focused* is assumed.

COMMANDS
^^^^^^^^
*-f*, *--focus* ['DESKTOP_SEL']::
	Focus the selected or given desktop.

*-a*, *--activate* ['DESKTOP_SEL']::
	Activate 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* <new_name>::
	Rename the selected desktop.

*-s*, *--swap* 'DESKTOP_SEL'::
	Swap the selected desktop with the given desktop.

*-b*, *--bubble* 'CYCLE_DIR'::
	Bubble the selected desktop in the given direction.

*-r*, *--remove*::
	Remove the selected desktop.

Monitor
~~~~~~~

General Syntax
^^^^^^^^^^^^^^

monitor ['MONITOR_SEL'] 'COMMANDS'

If 'MONITOR_SEL' is omitted, *focused* is assumed.

Commands
^^^^^^^^
*-f*, *--focus* ['MONITOR_SEL']::
	Focus the selected or given monitor.

*-s*, *--swap* 'MONITOR_SEL'::
	Swap the selected monitor with the given monitor.

*-a*, *--add-desktops* <name>...::
	Create desktops with the given names in the selected monitor.

*-o*, *--reorder-desktops* <name>...::
	Reorder the desktops of the selected monitor to match the given order.

*-d*, *--reset-desktops* <name>...::
	Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops.

*-g*, *--rectangle* WxH+X+Y::
	Set the rectangle of the selected monitor.

*-n*, *--rename* <new_name>::
	Rename the selected monitor.

*-r*, *--remove*::
	Remove the selected monitor.

Query
~~~~~

General Syntax
^^^^^^^^^^^^^^

query 'COMMANDS' ['OPTIONS']

Commands
^^^^^^^^

The optional selectors are references.

*-N*, *--nodes* ['NODE_SEL']::
	List the IDs of the matching nodes.

*-D*, *--desktops* ['DESKTOP_SEL']::
	List the IDs (or names) of the matching desktops.

*-M*, *--monitors* ['MONITOR_SEL']::
	List the IDs (or names) of the matching monitors.

*-T*, *--tree*::
	Print a JSON representation of the matching item.

Options
^^^^^^^

*-m*,*--monitor* ['MONITOR_SEL']::
*-d*,*--desktop* ['DESKTOP_SEL']::
*-n*, *--node* ['NODE_SEL']::
	Constrain matches to the selected monitor, desktop or node. The descriptor can be omitted for '-M', '-D' and '-N'.

*--names*::
	Print names instead of IDs.

Wm
~~

General Syntax
^^^^^^^^^^^^^^

wm 'COMMANDS'

Commands
^^^^^^^^

*-d*, *--dump-state*::
	Dump the current world state on standard output.

*-l*, *--load-state* <file_path>::
	Load a world state from the given file.

*-a*, *--add-monitor* <name> WxH+X+Y::
	Add a monitor for the given name and rectangle.

*-o*, *--adopt-orphans*::
	Manage all the unmanaged windows remaining from a previous session.

*-h*, *--record-history* on|off::
	Enable or disable the recording of node focus history.

*-g*, *--get-status*::
	Print the current status information.

Rule
~~~~

General Syntax
^^^^^^^^^^^^^^

rule 'COMMANDS'

Commands
^^^^^^^^

*-a*, *--add* (<class_name>|\*)[:(<instance_name>|\*)] [*-o*|*--one-shot*] [monitor=MONITOR_SEL|desktop=DESKTOP_SEL|node=NODE_SEL] [state=STATE] [layer=LAYER] [split_dir=DIR] [split_ratio=RATIO] [(hidden|sticky|private|locked|center|follow|manage|focus|border)=(on|off)] [rectangle=WxH+X+Y]::
	Create a new rule.

*-r*, *--remove* ^<n>|head|tail|(<class_name>|\*)[:(<instance_name>|*)]...::
	Remove the given rules.

*-l*, *--list*::
	List the rules.

Config
~~~~~~

General Syntax
^^^^^^^^^^^^^^

config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-n 'NODE_SEL'] <setting> [<value>]::
	Get or set the value of <setting>.

Subscribe
~~~~~~~~~

General Syntax
^^^^^^^^^^^^^^
subscribe [-c|--count 'COUNT'] (all|report|monitor|desktop|node|...)*::
	Continuously print status information. See the *EVENTS* section for the detailed description of each event. If a 'COUNT' argument is provided, then the subscriber will return after having received 'COUNT' events.

Quit
~~~~

General Syntax
^^^^^^^^^^^^^^

quit [<status>]::
	Quit with an optional exit status.

Exit Codes
----------

If the server can't handle a message, *bspc* will return with a non-zero exit code.

Settings
--------
Colors are in the form '#RRGGBB', booleans are 'true', 'on', 'false' or 'off'.

All the boolean settings are 'false' by default unless stated otherwise.

Global Settings
~~~~~~~~~~~~~~~

'normal_border_color'::
	Color of the border of an unfocused window.

'active_border_color'::
	Color of the border of a focused window of an unfocused monitor.

'focused_border_color'::
	Color of the border of a focused window of a focused monitor.

'presel_feedback_color'::
	Color of the *node --presel-{dir,ratio}* message feedback area.

'split_ratio'::
	Default split ratio.

'status_prefix'::
	Prefix prepended to each of the status lines.

'external_rules_command'::
	External command used to retrieve rule consequences. The command will receive the following arguments: window ID, class and instance names, monitor, desktop and node selectors. The output of that command must have the following format: *key1=value1 key2=value2 ...* (the valid key/value pairs are given in the description of the 'rule' command).

'initial_polarity'::
	On which child should a new window be attached when adding a window on a single window tree in automatic mode. Accept the following values: *first_child*, *second_child*.

'directional_focus_tightness'::
	The tightness of the algorithm used to decide whether a window is on the 'DIR' side of another window. Accept the following values: *high*, *low*.

'borderless_monocle'::
	Remove borders of tiled windows for the *monocle* desktop layout.

'gapless_monocle'::
	Remove gaps of tiled windows for the *monocle* desktop layout.

'paddingless_monocle'::
	Remove padding space for the *monocle* desktop layout.

'single_monocle'::
	Set the desktop layout to *monocle* if there's only one tiled window in the tree.

'pointer_motion_interval'::
	The minimum interval, in milliseconds, between two motion notify events.

'pointer_modifier'::
	Keyboard modifier used for moving or resizing windows. Accept the following values: *shift*, *control*, *lock*, *mod1*, *mod2*, *mod3*, *mod4*, *mod5*.

'pointer_action1'::
'pointer_action2'::
'pointer_action3'::
	Action performed when pressing 'pointer_modifier' + 'button<n>'. Accept the following values: *move*, *resize_side*, *resize_corner*, *focus*, *none*.

'click_to_focus'::
	Button used for focusing a window (or a monitor). The possible values are: *button1*, *button2*, *button3*, *any*, *none*.

'swallow_first_click'::
	Don't replay the click that makes a window focused if 'click_to_focus' isn't *none*.

'focus_follows_pointer'::
	Focus the window under the pointer.

'pointer_follows_focus'::
	When focusing a window, put the pointer at its center.

'pointer_follows_monitor'::
	When focusing a monitor, put the pointer at its center.

'ignore_ewmh_focus'::
	Ignore EWMH focus requests coming from applications.

'center_pseudo_tiled'::
	Center pseudo tiled windows into their tiling rectangles. Defaults to 'true'.

'honor_size_hints'::
	Apply ICCCM window size hints.

'remove_disabled_monitors'::
	Consider disabled monitors as disconnected.

'remove_unplugged_monitors'::
	Remove unplugged monitors.

'merge_overlapping_monitors'::
	Merge overlapping monitors (the bigger remains).

Monitor and Desktop Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

'top_padding'::
'right_padding'::
'bottom_padding'::
'left_padding'::
	Padding space added at the sides of the monitor or desktop.

Desktop Settings
~~~~~~~~~~~~~~~~

'window_gap'::
	Size of the gap that separates windows.

Node Settings
~~~~~~~~~~~~~

'border_width'::
	Window border width.

Pointer Bindings
----------------

'click_to_focus'::
	Focus the window (or the monitor) under the pointer if the value isn't *none*.

'pointer_modifier' + 'button1'::
	Move the window under the pointer.

'pointer_modifier' + 'button2'::
	Resize the window under the pointer by dragging the nearest side.

'pointer_modifier' + 'button3'::
	Resize the window under the pointer by dragging the nearest corner.

The behavior of 'pointer_modifier' + 'button<n>' can be modified through the 'pointer_action<n>' setting.

Events
------

'report'::
	See the next section for the description of the format.

'monitor_add <monitor_id> <monitor_name> <monitor_geometry>'::
	A monitor is added.

'monitor_rename <monitor_id> <old_name> <new_name>'::
	A monitor is renamed.

'monitor_remove <monitor_id>'::
	A monitor is removed.

'monitor_swap <src_monitor_id> <dst_monitor_id>'::
	A monitor is swapped.

'monitor_focus <monitor_id>'::
	A monitor is focused.

'monitor_geometry <monitor_id> <monitor_geometry>'::
	The geometry of a monitor changed.

'desktop_add <monitor_id> <desktop_id> <desktop_name>'::
	A desktop is added.

'desktop_rename <monitor_id> <desktop_id> <old_name> <new_name>'::
	A desktop is renamed.

'desktop_remove <monitor_id> <desktop_id>'::
	A desktop is removed.

'desktop_swap <src_monitor_id> <src_desktop_id> <dst_monitor_id> <dst_desktop_id>'::
	A desktop is swapped.

'desktop_transfer <src_monitor_id> <src_desktop_id> <dst_monitor_id>'::
	A desktop is transferred.

'desktop_focus <monitor_id> <desktop_id>'::
	A desktop is focused.

'desktop_activate <monitor_id> <desktop_id>'::
	A desktop is activated.

'desktop_layout <monitor_id> <desktop_id> tiled|monocle'::
	The layout of a desktop changed.

'node_manage <monitor_id> <desktop_id> <node_id> <ip_id>'::
	A window is managed.

'node_unmanage <monitor_id> <desktop_id> <node_id>'::
	A window is unmanaged.

'node_swap <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
	A node is swapped.

'node_transfer <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
	A node is transferred.

'node_focus <monitor_id> <desktop_id> <node_id>'::
	A node is focused.

'node_activate <monitor_id> <desktop_id> <node_id>'::
	A node is activated.

'node_presel <monitor_id> <desktop_id> <node_id> (dir DIR|ratio RATIO|cancel)'::
	A node is preselected.

'node_stack <node_id_1> below|above <node_id_2>'::
	A node is stacked below or above another node.

'node_geometry <monitor_id> <desktop_id> <node_id> <node_geometry>'::
	The geometry of a window changed.

'node_state <monitor_id> <desktop_id> <node_id> tiled|pseudo_tiled|floating|fullscreen on|off'::
	The state of a window changed.

'node_flag <monitor_id> <desktop_id> <node_id> hidden|sticky|private|locked|urgent on|off'::
	One of the flags of a node changed.

'node_layer <monitor_id> <desktop_id> <node_id> below|normal|above'::
	The layer of a window changed.

'pointer_action <monitor_id> <desktop_id> <node_id> move|resize_corner|resize_side begin|end'::
	A pointer action occured.

Please note that *bspwm* initializes monitors before it reads messages on its socket, therefore the initial monitor events can't be received.

Report Format
-------------

Each report event message is composed of items separated by colons.

Each item has the form '<type><value>' where '<type>' is the first character of the item.

'M<monitor_name>'::
	Focused monitor.

'm<monitor_name>'::
	Unfocused monitor.

'O<desktop_name>'::
	Occupied focused desktop.

'o<desktop_name>'::
	Occupied unfocused desktop.

'F<desktop_name>'::
	Free focused desktop.

'f<desktop_name>'::
	Free unfocused desktop.

'U<desktop_name>'::
	Urgent focused desktop.

'u<desktop_name>'::
	Urgent unfocused desktop.

'L(T|M)'::
	Layout of the focused desktop of a monitor.

'T(T|P|F|=|@)'::
	State of the focused node of a focused desktop.

'G(S?P?L?)'::
	Active flags of the focused node of a focused desktop.

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<host_name>_<display_number>_<screen_number>-socket'.

Contributors
------------

* Steven Allen <steven at stebalien.com>
* Thomas Adam <thomas at xteddy.org>
* Ivan Kanakarakis <ivan.kanak at gmail.com>

Author
------

Bastien Dejean <nihilhill at gmail.com>