Add example bindings for history navigation

[bspwm.git] / doc / bspwm.1.txt

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

*-c* 'CONFIG_PATH'::
    Use the given configuration file.

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

The default configuration file is '$XDG_CONFIG_HOME/bspwm/bspwmrc'.

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|older|newer)[.floating|.tiled][.like|.unlike][.manual][.urgent][.local]
----

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.

focused::
    Selects the currently focused window.

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

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

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.

manual::
    Only consider windows in manual splitting mode (see *--presel*).

local::
    Only consider windows of the current desktop.

urgent::
    Only consider urgent windows.

Desktop
~~~~~~~

Select a desktop.

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

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

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

^<n>::
    Selects the nth desktop.

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

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

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

Modifiers
^^^^^^^^^

occupied::
    Only consider occupied desktops.

free::
    Only consider free desktops.

urgent::
    Only consider urgent desktops.

local::
    Only consider desktops of the current monitor.

Monitor
~~~~~~~

Select a monitor.

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

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

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

^<n>::
    Selects the nth monitor.

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

primary::
    Selects the primary monitor.

last::
    Selects the previously focused monitor.

focused::
    Selects the currently 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.

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 (0 < 'RATIO' < 1).

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

*-R*, *--rotate* 'DIR' '90|270|180'::
    Rotate the tree holding the edge located in the given direction in relation to the selected window.

*-t*, *--toggle* floating|fullscreen|locked|sticky|visible[=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.

*-s*, *--swap* 'DESKTOP_SEL'::
    Swap the selected desktop with the given 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.

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

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

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

Tag
~~~

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

tag 'OPTIONS'

Options
^^^^^^^
*-l*, *--list*::
    List the tags.

*-a*, *--add* <name>...::
    Create tags with the given names.

*-r*, *--remove* <name>|^<n>...::
    Remove tags with the given names or indexes.

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

*-d*, *--desktop* 'DESKTOP_SEL'::
    Select the given desktop as target for the *-s* and *-t* options.

*-w*, *--window* 'WINDOW_SEL'::
    Select the given window as target for the *-s* and *-t* options.

*-s*, *--set-tags* (<name>|^<n>...)|all::
    Set the tags of the selected object.

*-t*, *--toggle-tags* (<name>|^<n>)[=on|off]...::
    Toggle the tags of the selected object.

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.

*-S*, *--stack*::
    Print the window stacking order.

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

*-S*, *--stack* <file_path>::
    Load the window stacking order 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 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* <class_name>|<instance_name> [-d 'DESKTOP_SEL' [--follow]] [--tags <name>|^<n>[,...]][--floating] [--fullscreen] [--locked] [--sticky] [--focus] [--unmanage] [--one-shot]::
    Create a new rule.

*-r*, *--remove* <name>|^<n>|tail|head...::
    Remove the rules with the given names or indexes.

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

Config
~~~~~~

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

config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'] <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.

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

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

'focused_sticky_border_color'::
    Color of the border of a focused sticky window of a focused monitor.

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

'normal_sticky_border_color'::
    Color of the border of an unfocused sticky window.

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

'split_ratio'::
    Default split ratio.

'growth_factor'::
    Intensity of the growth involved in pulling or pushing an edge.

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

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

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

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

'apply_floating_atom'::
    Set the value of the '_BSPWM_FLOATING_WINDOW' atom of each window according to its floating state.

'honor_ewmh_focus'::
    Honor EWMH requests to focus a window.

Monitor Settings
~~~~~~~~~~~~~~~~

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

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

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

'border_width'::
    Window border width.


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

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 <nihilhill at gmail.com>

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

bspwm at librelist.com

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