An exclamation mark can be prepended to any modifier in order to reverse its
meaning.
+The following characters cannot be used in monitor or desktop names: *#*, *:*, *.*.
+
+The special selector *%<name>* can be used to select a monitor or a desktop with an invalid name.
+
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]
+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
Only consider focused or unfocused nodes.
[!]automatic::
- Only consider nodes in automatic or manual insertion mode.
+ 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.
Select a desktop.
----
-DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|last|older|newer|[MONITOR_SEL:](focused|^<n>)|<desktop_id>|<desktop_name>)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
+DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|last|older|newer|
+ [MONITOR_SEL:](focused|^<n>)|
+ <desktop_id>|<desktop_name>)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
----
Descriptors
Selects the currently focused desktop.
^<n>::
- Selects the nth desktop.
+ Selects the nth desktop. If *MONITOR_SEL* is given, selects the nth desktop on the selected monitor.
<desktop_id>::
Selects the desktop with the given ID.
Only consider urgent or non urgent desktops.
[!]local::
- Only consider inside or outside of the reference monitor.
+ 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]
+MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|last|older|newer|
+ focused|pointed|primary|^<n>|
+ <monitor_id>|<monitor_name>)[.[!]occupied][.[!]focused]
----
Descriptors
focused::
Selects the currently focused monitor.
+pointed::
+ Selects the monitor under the pointer.
+
primary::
Selects the primary monitor.
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*.
+ 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.
*-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'::
+*-r*, *--ratio* 'RATIO'|(+|-)('PIXELS'|'FRACTION')::
Set the splitting ratio of the selected node (0 < 'RATIO' < 1).
*-R*, *--rotate* '90|270|180'::
List the IDs of the matching nodes.
*-D*, *--desktops* ['DESKTOP_SEL']::
- List the IDs of the matching desktops.
+ List the IDs (or names) of the matching desktops.
*-M*, *--monitors* ['MONITOR_SEL']::
- List the IDs of the matching monitors.
+ List the IDs (or names) of the matching monitors.
*-T*, *--tree*::
Print a JSON representation of the matching item.
*-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. Can only be used with '-M' and '-D'.
+
Wm
~~
*-a*, *--add-monitor* <name> WxH+X+Y::
Add a monitor for the given name and rectangle.
+*-O*, *--reorder-monitors* <name>...::
+ Reorder the list of monitors to match the given order.
+
*-o*, *--adopt-orphans*::
Manage all the unmanaged windows remaining from a previous session.
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)]::
+*-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>|*)]...::
General Syntax
^^^^^^^^^^^^^^
-config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-n 'NODE_SEL'] <key> [<value>]::
- Get or set the value of <key>.
+config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-n 'NODE_SEL'] <setting> [<value>]::
+ Get or set the value of <setting>.
Subscribe
~~~~~~~~~
General Syntax
^^^^^^^^^^^^^^
-subscribe (all|report|monitor|desktop|node|...)*::
- Continuously print status information. See the *EVENTS* section for the detailed description of each event.
+subscribe ['OPTIONS'] (all|report|monitor|desktop|node|...)*::
+ Continuously print events. See the *EVENTS* section for the description of each event.
+
+Options
+^^^^^^^
+
+*-f*, *--fifo*::
+ Print a path to a FIFO from which events can be read and return.
+
+*-c*, *--count* 'COUNT'::
+ Stop the corresponding *bspc* process after having received 'COUNT' events.
Quit
~~~~
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).
+ External command used to retrieve rule consequences. The command will receive the following arguments: window ID, class name, instance name, and intermediate consequences. 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.
Action performed when pressing 'pointer_modifier' + 'button<n>'. Accept the following values: *move*, *resize_side*, *resize_corner*, *focus*, *none*.
'click_to_focus'::
- Focus a window (or a monitor) by clicking it.
+ 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 Bindings
----------------
-'button1'::
- Focus the window under the pointer if 'click_to_focus' is set.
+'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.
'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_add <monitor_id> <desktop_id> <ip_id> <node_id>'::
+ A node is added.
-'node_unmanage <monitor_id> <desktop_id> <node_id>'::
- A window is unmanaged.
+'node_remove <monitor_id> <desktop_id> <node_id>'::
+ A node is removed.
'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_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