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 a descriptor and any number of non-conflicting modifiers
as follows:

	DESCRIPTOR(.MODIFIER)*

An exclamation mark can be prepended to certain modifiers in order to reverse their meaning.

Node
~~~~

Select a node.

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

STATE := tiled|pseudo_tiled|floating|fullscreen

FLAG := urgent|sticky|private|locked

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 active node.

'CYCLE_DIR'::
	Selects the window in the given (cyclic) direction.

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

last::
	Selects the previously focused node.

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

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

focused::
	Selects the currently focused node.

biggest::
	Selects the biggest window on the current desktop.

<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 focused 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.

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

[!]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 current window.

[!](private|urgent|sticky|locked)::
	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 := (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 active desktop.

last::
	Selects the previously focused desktop.

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

newer::
	Selects the desktop newer than the focused 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 inside or outside of the current monitor.

Monitor
~~~~~~~

Select a monitor.

----
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 active monitor.

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

last::
	Selects the previously focused monitor.

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

newer::
	Selects the monitor newer than the focused 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
----------

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

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

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

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'

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*.

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

*-r*, *--ratio* 'RATIO'|(+|-)'PIXELS'::
	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* locked|sticky|private[=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'

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'

Commands
^^^^^^^^
*-f*, *--focus* ['MONITOR_SEL']::
	Focus the selected or 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.

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

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

Query
~~~~~

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

query 'COMMANDS' ['OPTIONS']

Commands
^^^^^^^^

*-N*, *--nodes*::
	List the IDs of the matching nodes.

*-D*, *--desktops*::
	List the IDs of the matching desktops.

*-M*, *--monitors*::
	List the IDs 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'.

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.

Pointer
~~~~~~~

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

pointer 'COMMANDS'

Commands
^^^^^^^^

*-g*, *--grab* focus|move|resize_side|resize_corner::
	Initiate the given pointer action.

*-t*, *--track* <x> <y>::
	Pass the pointer root coordinates for the current pointer action.

*-u*, *--ungrab*::
	Terminate the current pointer action.

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] [(locked|sticky|private|center|follow|manage|focus|border)=(on|off)]::
	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'] <key> [<value>]::
	Get or set the value of <key>.

Subscribe
~~~~~~~~~

General Syntax
^^^^^^^^^^^^^^
subscribe (all|report|monitor|desktop|node|...)*::
	Continuously print status information. See the *EVENTS* section for the detailed description of each event.

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 the ID of the window being processed as its first argument and the class and instance names as second and third arguments. 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*.

'history_aware_focus'::
	Give priority to the focus history when focusing nodes.

'focus_by_distance'::
	Base focusing on distances between windows.

'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.

'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'.

'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.


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> 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.

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>