image:https://github.com/baskerville/bspwm/raw/master/logo/bspwm-logo.png[logo]

: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* 'MESSAGE' ['ARGUMENTS'] ['OPTIONS']

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

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

There is only two splitting modes: 'automatic' and 'manual'.

The default mode is 'automatic'. The 'manual' mode is entered by sending a *presel* 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 *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.

Messages
--------


*get* 'SETTING'::
    Return the value of the given setting.

*set* 'SETTING' 'VALUE'::
    Set the value of the given setting.

*list* ['DESKTOP_NAME']::
    Output the internal representation of the window tree.

*list_desktops* [*--quiet*]::
    Perform a dump of each desktop for the current monitor.

*list_monitors* [*--quiet*]::
    Perform a dump of each monitor.

*list_history*::
    Return the node focus history of each desktop.

*list_windows*::
    Return the list of managed windows (i.e. their identifiers).

*list_rules*::
    Return the list of rules.

*presel* 'left'|'right'|'up'|'down' ['SPLIT_RATIO']::
    Switch to manual mode and select the splitting direction.

*cancel* [*--all*]::
    Switch to automatic mode.

*ratio* 'VALUE'::
    Set the splitting ratio of the focused window.

*pad* 'MONITOR_NAME' ['TOP_PADDING' ['RIGHT_PADDING' ['BOTTOM_PADDING' ['LEFT_PADDING']]]]::
    Set the padding of the given monitor.

*focus* 'left'|'right'|'up'|'down'::
    Focus the neighbor window situated in the given direction.

*shift* 'left'|'right'|'up'|'down'::
    Exchange the current window with the given neighbor.

*swap* [*--keep-focus*]::
    Swap the focused window with the last focused window.

*push* 'left'|'right'|'up'|'down'::
    Push the fence located in the given direction.

*pull* 'left'|'right'|'up'|'down'::
    Pull the fence located in the given direction.

*fence_ratio* 'left'|'right'|'up'|'down' 'RATIO'::
    Set the splitting ratio of the fence located in the given direction.

*cycle* 'next'|'prev' [*--skip-floating*|*--skip-tiled*|*--skip-class-equal*|*--skip-class-differ*]::
    Focus the next or previous window matching the given constraints.

*nearest* 'older'|'newer' [*--skip-floating*|*--skip-tiled*|*--skip-class-equal*|*--skip-class-differ*]::
    Focus the nearest window matching the given constraints.

*biggest*::
    Return the ID of the biggest tiled window.

*circulate* 'forward'|'backward'::
    Circulate the leaves in the given direction.

*grab_pointer* 'focus'|'move'|'resize_side'|'resize_corner'::
    Begin the specified pointer action.

*track_pointer* 'ROOT_X' 'ROOT_Y'::
    Pass the pointer root coordinates for the current pointer action.

*toggle_fullscreen*::
    Toggle the fullscreen state of the current window.

*toggle_floating*::
    Toggle the floating state of the current window.

*toggle_locked*::
    Toggle the locked state of the current window (locked windows will not respond to the *close* message).

*toggle_visibility*::
    Toggle the visibility of all the managed windows.

*close*::
    Close the focused window.

*kill*::
    Kill the focused window.

*send_to* 'DESKTOP_NAME' [*--follow*]::
    Send the focused window to the given desktop.

*drop_to* 'next'|'prev' [*--follow*]::
    Send the focused window to the next or previous desktop.

*send_to_monitor* 'MONITOR_NAME' [*--follow*]::
    Send the focused window to the given monitor.

*drop_to_monitor* 'next'|'prev' [*--follow*]::
    Send the focused window to the next or previous monitor.

*use* 'DESKTOP_NAME'::
    Select the given desktop.

*use_monitor* 'MONITOR_NAME'::
    Select the given monitor.

*focus_monitor* 'left'|'right'|'up'|'down'::
    Focus the nearest monitor in the given direction.

*alternate*::
    Alternate between the current and the last focused window.

*alternate_desktop*::
    Alternate between the current and the last focused desktop.

*alternate_monitor*::
    Alternate between the current and the last focused monitor.

*add* 'DESKTOP_NAME' ...::
    Make new desktops with the given names.

*add_in* 'MONITOR_NAME' 'DESKTOP_NAME' ...::
    Make new desktops with the given names in the given monitor.

*rename_monitor* 'CURRENT_NAME' 'NEW_NAME'::
    Rename the monitor named 'CURRENT_NAME' to 'NEW_NAME'.

*rename* 'CURRENT_NAME' 'NEW_NAME'::
    Rename the desktop named 'CURRENT_NAME' to 'NEW_NAME'.

*remove_desktop* 'DESKTOP_NAME' ...::
    Remove the given desktops.

*send_desktop_to* 'MONITOR_NAME' [*--follow*]::
    Send the current desktop to the given monitor.

*cycle_monitor* 'next'|'prev'::
    Select the next or previous monitor.

*cycle_desktop* 'next'|'prev' [*--skip-free*|*--skip-occupied*]::
    Select the next or previous desktop.

*layout* 'monocle'|'tiled' ['DESKTOP_NAME' ...]::
    Set the layout of the given desktops (current if none given).

*cycle_layout*::
    Cycle the layout of the current desktop.

*rotate* 'clockwise'|'counter_clockwise'|'full_cycle'::
    Rotate the window tree.

*flip* 'horizontal'|'vertical'::
    Flip the window tree.

*balance*::
    Adjust the split ratios so that all windows occupy the same area.

*rule* 'PATTERN' ['DESKTOP_NAME'] ['floating'] ['follow']::
    Create a new rule ('PATTERN' must match the class or instance name).

*remove_rule* 'UID' ...::
    Remove the rules with the given 'UIDs'.

*put_status*::
    Output the current state to the panel fifo.

*adopt_orphans*::
    Manage all the unmanaged windows remaining from a previous session.

*restore_layout* 'FILE_PATH'::
    Restore the layout of each desktop from the content of 'FILE_PATH'.

*restore_history* 'FILE_PATH'::
    Restore the history of each desktop from the content of 'FILE_PATH'.

*quit* ['EXIT_STATUS']::
    Quit.

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.

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

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

'monitor_focus_fallback'::
    If the focus message fails, try to focus the nearest monitor in the same direction.

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

'focus_by_distance'::
    Use window or leaf distance for focus movement.

'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).
* Automatic and manual modes.

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:
////
