bspwm/doc/bspwm.1.txt

:man source:   Bspwm
:man version:  {revnumber}
:man manual:   Bspwm Manual

bspwm(1)
========

Name
----

bspwm - Tiling window manager based on binary space partitioning

Synopsis
--------

*bspwm* [*-h*|*-v*|*-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.

*-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* have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.

Its configuration file is '$XDG_CONFIG_HOME/bspwm/autostart'.

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 := <window_id> 
            | (DIR|CYCLE_DIR|biggest|last|focused)[.floating|.tiled][.like|.unlike][.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 on the current desktop.

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 := <desktop_name>
             | (CYCLE_DIR|last|focused)[.occupied|.free][.urgent|.nonurgent]
----

Primary Selectors
^^^^^^^^^^^^^^^^^

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

last::
    Selects the previously focused desktop.

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 := <monitor_name>
             | (DIR|CYCLE_DIR|last|focused)[.occupied|.free]
----

Primary Selectors
^^^^^^^^^^^^^^^^^

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

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.

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

*-t*, *--toggle* floating|fullscreen|locked[=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* <new_name>::
    Rename the selected 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* <name>...::
    Create desktops with the given names in the selected monitor.

*-r*, *--remove-desktops* <name>...::
    Remove desktops with the given names.

*-p*, *--pad* <top> <right> <bottom> <left>::
    Set the padding of the selected monitor.

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

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.

[*-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* <file_path>::
    Load the desktop trees from the given file.

*-H*, *--history* <file_path>::
    Load the focus history 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 managed windows.

Pointer
~~~~~~~

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

pointer 'OPTIONS'

Options
^^^^^^^

*-t*, *--track* <x> <y>::
    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* <pattern> [-d 'DESKTOP_SEL' [--follow]] [--floating]::
    Create a new rule (<pattern> must match the class or instance name).

*-r*, *--rm* <rule_uid>...::
    Remove the rules with the given UIDs.

*-l*, *--list* [<pattern>]::
    List the rules.

Config
~~~~~~

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

config <key> [<value>]::
    Get or set the value of <key>.

Quit
~~~~

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

quit [<status>]::
    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.


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

'urgent_border_color'::
    Color of the border of an urgent window.

'border_width'::
    Window border width.

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

'split_ratio'::
    Default split ratio.

'wm_name'::
    The value that shall be used for the '_NET_WM_NAME' property of the root window.

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

'adaptative_raise'::
    Prevent floating windows from being raised when they might cover other floating windows.

'apply_shadow_property'::
    Enable shadows for floating windows via the '_COMPTON_SHADOW' property.

'auto_alternate'::
    Interpret two consecutive identical *use* messages as an *alternate* message.

'auto_cancel'::
    Interpret two consecutive identical *presel* messages as a *cancel* message.

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

Environment Variables
---------------------

'BSPWM_SOCKET'::
  The path of the socket used for the communication between *bspc* and *bspwm*.

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 <steven at stebalien.com>
* Thomas Adam <thomas at xteddy.org>
* Ivan Kanakarakis <ivan.kanak at gmail.com>

Author
------

Bastien Dejean <baskerville at lavabit.com>

Mailing List
------------

bspwm at librelist.com

////
vim: set ft=asciidoc:
////