Synopsis
--------
-*bspwm* [*-h*|*-v*|*-s* _PANEL_FIFO_|*-p* _PANEL_PREFIX_]
+*bspwm* [*-h*|*-v*|*-s* 'PANEL_FIFO'|*-p* 'PANEL_PREFIX']
-*bspc* _MESSAGE_ [_ARGUMENTS_] [_OPTIONS_]
+*bspc* 'COMMAND' ['ARGUMENTS']
Description
-----------
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_.
+Its configuration file is '$XDG_CONFIG_HOME/bspwm/autostart'.
Keyboard and pointer bindings are defined with https://github.com/baskerville/sxhkd[sxhkd].
Splitting Modes
---------------
-There is only two splitting modes: _automatic_ and _manual_.
+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 *presel* message.
+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:
+Example: insertion of a new node (number 4) into the given tree in 'automatic' mode:
----
b c
+-------------------------+ +-------------------------+
----
-Same departure, but the mode is _manual_, and a *presel* _up_ message was sent beforehand:
+Same departure, but the mode is 'manual', and a *window --presel up* message was sent beforehand:
----
b b
Each desktop contains at most one tree.
-Messages
+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
+~~~~~~
-*get* _SETTING_::
- Return the value of the given setting.
+General Syntax
+^^^^^^^^^^^^^^
-*set* _SETTING_ _VALUE_::
- Set the value of the given setting.
+window ['WINDOW_SEL'] 'OPTIONS'
-*list* [_DESKTOP_NAME_]::
- Output the internal representation of the window tree.
+Options
+^^^^^^^
+*-f*, *--focus* ['WINDOW_SEL']::
+ Focus the selected or given window.
-*list_desktops* [*--quiet*]::
- Perform a dump of each desktop for the current monitor.
+*-d*, *--to-desktop* 'DESKTOP_SEL'::
+ Send the selected window to the given desktop.
-*list_monitors* [*--quiet*]::
- Perform a dump of each monitor.
+*-m*, *--to-monitor* 'MONITOR_SEL'::
+ Send the selected window to the given monitor.
-*list_history*::
- Return the node focus history of each desktop.
+*-w*, *--to-window* 'WINDOW_SEL'::
+ Transplant the selected window to the given window.
-*list_windows*::
- Return the list of managed windows (i.e. their identifiers).
+*-s*, *--swap* 'WINDOW_SEL'::
+ Swap the selected window with the given window.
-*list_rules*::
- Return the list of rules.
+*-p*, *--presel* 'DIR'|cancel::
+ Preselect the splitting area of the selected window (or cancel the preselection).
-*presel* _left_|_right_|_up_|_down_ [_SPLIT_RATIO_]::
- Switch to manual mode and select the splitting direction.
+*-r*, *--ratio* 'RATIO'::
+ Set the splitting ratio of the selected window (0 < 'RATIO' < 1).
-*cancel* [*--all*]::
- Switch to automatic mode.
+*-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.
-*ratio* _VALUE_::
- Set the splitting ratio of the focused window.
+*-t*, *--toggle* floating|fullscreen|locked[=on|off]::
+ Set or toggle the given state for the selected window.
-*pad* _MONITOR_NAME_ [_TOP_PADDING_ [_RIGHT_PADDING_ [_BOTTOM_PADDING_ [_LEFT_PADDING_]]]]::
- Set the padding of the given monitor.
+*-c*, *--close*::
+ Close the selected window.
-*focus* _left_|_right_|_up_|_down_::
- Focus the neighbor window situated in the given direction.
+*-k*, *--kill*::
+ Kill the selected window.
-*shift* _left_|_right_|_up_|_down_::
- Exchange the current window with the given neighbor.
+Desktop
+~~~~~~~
-*swap* [*--keep-focus*]::
- Swap the focused window with the last focused window.
+General Syntax
+^^^^^^^^^^^^^^
-*push* _left_|_right_|_up_|_down_::
- Push the fence located in the given direction.
+desktop ['DESKTOP_SEL'] 'OPTIONS'
-*pull* _left_|_right_|_up_|_down_::
- Pull the fence located in the given direction.
+Options
+^^^^^^^
+*-f*, *--focus* ['DESKTOP_SEL']::
+ Focus the selected or given desktop.
-*fence_ratio* _left_|_right_|_up_|_down_ _RATIO_::
- Set the splitting ratio of the fence located in the given direction.
+*-m*, *--to-monitor* 'MONITOR_SEL'::
+ Send the selected desktop to the given monitor.
-*cycle* _next_|_prev_ [*--skip-floating*|*--skip-tiled*|*--skip-class-equal*|*--skip-class-differ*]::
- Focus the next or previous window matching the given constraints.
+*-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
+ Set or cycle the layout of the selected desktop.
-*nearest* _older_|_newer_ [*--skip-floating*|*--skip-tiled*|*--skip-class-equal*|*--skip-class-differ*]::
- Focus the nearest window matching the given constraints.
+*-n*, *--rename* <new_name>::
+ Rename the selected desktop.
-*biggest*::
- Return the ID of the biggest tiled window.
+*-r*, *--remove*::
+ Remove the selected desktop.
-*circulate* _forward_|_backward_::
- Circulate the leaves in the given direction.
+*-c*, *--cancel-presel*::
+ Cancel the preselection of all the windows of the selected desktop.
-*grab_pointer* _focus_|_move_|_resize_side_|_resize_corner_::
- Begin the specified pointer action.
+*-F*, *--flip* 'horizontal|vertical'::
+ Flip the tree of the selected desktop.
-*track_pointer* _ROOT_X_ _ROOT_Y_::
- Pass the pointer root coordinates for the current pointer action.
+*-R*, *--rotate* '90|270|180'::
+ Rotate the tree of the selected desktop.
-*ungrab_pointer*::
- End the current pointer action.
+*-B*, *--balance*::
+ Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
-*toggle_fullscreen*::
- Toggle the fullscreen state of the current window.
+*-C*, *--circulate* forward|backward::
+ Circulate the leaves of the tree of the selected desktop.
-*toggle_floating*::
- Toggle the floating state of the current window.
+Monitor
+~~~~~~~
-*toggle_locked*::
- Toggle the locked state of the current window (locked windows will not respond to the *close* message).
+General Syntax
+^^^^^^^^^^^^^^
-*toggle_visibility*::
- Toggle the visibility of all the managed windows.
+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.
-*close*::
- Close the focused window.
+*-r*, *--remove-desktops* <name>...::
+ Remove desktops with the given names.
-*kill*::
- Kill the focused window.
+*-p*, *--pad* <top> <right> <bottom> <left>::
+ Set the padding of the selected monitor.
-*send_to* _DESKTOP_NAME_ [*--follow*]::
- Send the focused window to the given desktop.
+*-n*, *--rename* <new_name>::
+ Rename the selected monitor.
-*drop_to* _next_|_prev_ [*--follow*]::
- Send the focused window to the next or previous desktop.
+Query
+~~~~~
-*send_to_monitor* _MONITOR_NAME_ [*--follow*]::
- Send the focused window to the given monitor.
+General Syntax
+^^^^^^^^^^^^^^
-*drop_to_monitor* _next_|_prev_ [*--follow*]::
- Send the focused window to the next or previous monitor.
+query 'OPTIONS'
-*use* _DESKTOP_NAME_::
- Select the given desktop.
+Options
+^^^^^^^
+*-W*, *--windows*::
+ List matching windows.
-*use_monitor* _MONITOR_NAME_::
- Select the given monitor.
+*-D*, *--desktops*::
+ List matching desktops.
-*focus_monitor* _left_|_right_|_up_|_down_::
- Focus the nearest monitor in the given direction.
+*-M*, *--monitors*::
+ List matching monitors.
-*alternate*::
- Alternate between the current and the last focused window.
+*-T*, *--tree*::
+ Print tree rooted at query.
-*alternate_desktop*::
- Alternate between the current and the last focused desktop.
+*-H*, *--history*::
+ Print the history as it relates to the query.
-*alternate_monitor*::
- Alternate between the current and the last focused monitor.
+[*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
+ Constrain matches to the selected monitor, desktop or window.
-*add* _DESKTOP_NAME_ ...::
- Make new desktops with the given names.
+Restore
+~~~~~~~
-*add_in* _MONITOR_NAME_ _DESKTOP_NAME_ ...::
- Make new desktops with the given names in the given monitor.
+General Syntax
+^^^^^^^^^^^^^^
-*rename_monitor* _CURRENT_NAME_ _NEW_NAME_::
- Rename the monitor named _CURRENT_NAME_ to _NEW_NAME_.
+restore 'OPTIONS'
-*rename* _CURRENT_NAME_ _NEW_NAME_::
- Rename the desktop named _CURRENT_NAME_ to _NEW_NAME_.
+Options
+^^^^^^^
-*remove_desktop* _DESKTOP_NAME_ ...::
- Remove the given desktops.
+*-T*, *--tree* <file_path>::
+ Load the desktop trees from the given file.
-*send_desktop_to* _MONITOR_NAME_ [*--follow*]::
- Send the current desktop to the given monitor.
+*-H*, *--history* <file_path>::
+ Load the focus history from the given file.
-*cycle_monitor* _next_|_prev_::
- Select the next or previous monitor.
+Control
+~~~~~~~
-*cycle_desktop* _next_|_prev_ [*--skip-free*|*--skip-occupied*]::
- Select the next or previous desktop.
+General Syntax
+^^^^^^^^^^^^^^
-*layout* _monocle_|_tiled_ [_DESKTOP_NAME_ ...]::
- Set the layout of the given desktops (current if none given).
+control 'OPTIONS'
-*cycle_layout*::
- Cycle the layout of the current desktop.
+Options
+^^^^^^^
-*rotate* _clockwise_|_counter_clockwise_|_full_cycle_::
- Rotate the window tree.
+*--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.
-*flip* _horizontal_|_vertical_::
- Flip the window tree.
+Pointer
+~~~~~~~
+
+General Syntax
+^^^^^^^^^^^^^^
+
+pointer 'OPTIONS'
+
+Options
+^^^^^^^
+
+*-t*, *--track* <x> <y>::
+ Pass the pointer root coordinates for the current pointer action.
-*balance*::
- Adjust the split ratios so that all windows occupy the same area.
+*-g*, *--grab* focus|move|resize_side|resize_corner::
+ Perform the given pointer action.
-*rule* _PATTERN_ [_DESKTOP_NAME_] [_floating_] [_follow_]::
- Create a new rule (_PATTERN_ must match the class or instance name).
+Rule
+~~~~
-*remove_rule* _UID_ ...::
- Remove the rules with the given _UIDs_.
+General Syntax
+^^^^^^^^^^^^^^
-*put_status*::
- Output the current state to the panel fifo.
+rule 'OPTIONS'
-*adopt_orphans*::
- Manage all the unmanaged windows remaining from a previous session.
+Options
+^^^^^^^
-*restore_layout* _FILE_PATH_::
- Restore the layout of each desktop from the content of _FILE_PATH_.
+*-a*, *--add* <pattern> [-d 'DESKTOP_SEL' [--follow]] [--floating]::
+ Create a new rule (<pattern> must match the class or instance name).
-*restore_history* _FILE_PATH_::
- Restore the history of each desktop from the content of _FILE_PATH_.
+*-r*, *--rm* <rule_uid>...::
+ Remove the rules with the given UIDs.
-*quit* [_EXIT_STATUS_]::
- Quit.
+*-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_.
+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.
+All the boolean settings are 'false' by default.
-_focused_border_color_::
+'focused_border_color'::
Color of the border of a focused window of a focused monitor.
-_active_border_color_::
+'active_border_color'::
Color of the border of a focused window of an unfocused monitor.
-_normal_border_color_::
+'normal_border_color'::
Color of the border of an unfocused window.
-_presel_border_color_::
+'presel_border_color'::
Color of the *presel* message feedback.
-_focused_locked_border_color_::
+'focused_locked_border_color'::
Color of the border of a focused locked window of a focused monitor.
-_active_locked_border_color_::
+'active_locked_border_color'::
Color of the border of a focused locked window of an unfocused monitor.
-_normal_locked_border_color_::
+'normal_locked_border_color'::
Color of the border of an unfocused locked window.
-_urgent_border_color_::
+'urgent_border_color'::
Color of the border of an urgent window.
-_border_width_::
+'border_width'::
Window border width.
-_window_gap_::
+'window_gap'::
Value of the gap that separates windows.
-_split_ratio_::
+'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_::
+'wm_name'::
The value that shall be used for the '_NET_WM_NAME' property of the root window.
-_borderless_monocle_::
+'borderless_monocle'::
Remove borders for tiled windows in monocle mode.
-_gapless_monocle_::
+'gapless_monocle'::
Remove gaps for tiled windows in monocle mode.
-_focus_follows_pointer_::
+'focus_follows_pointer'::
Focus the window under the pointer.
-_pointer_follows_monitor_::
+'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_::
+'adaptative_raise'::
Prevent floating windows from being raised when they might cover other floating windows.
-_apply_shadow_property_::
+'apply_shadow_property'::
Enable shadows for floating windows via the '_COMPTON_SHADOW' property.
-_auto_alternate_::
+'auto_alternate'::
Interpret two consecutive identical *use* messages as an *alternate* message.
-_focus_by_distance_::
- Use window or leaf distance for focus movement.
+'auto_cancel'::
+ Interpret two consecutive identical *presel* messages as a *cancel* message.
-_history_aware_focus_::
+'history_aware_focus'::
Give priority to the focus history when focusing nodes.
Environment Variables
---------------------
-_BSPWM_SOCKET_::
+'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_).
+* 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_).
+* Multiple monitors support (via 'RandR').
* EWMH support (*tint2* works).
-* Automatic and manual modes.
+* Hybrid tiling.
Contributors
------------
-* Ivan Kanakarakis <ivan.kanak at gmail.com>
+* Steven Allen <steven at stebalien.com>
* Thomas Adam <thomas at xteddy.org>
+* Ivan Kanakarakis <ivan.kanak at gmail.com>
Author
------
projects / bspwm.git / blobdiff