README.asciidoc

   1 image:https://github.com/baskerville/bspwm/raw/master/logo/bspwm-logo.png[logo]
   2
   3 :man source:   Bspwm
   4 :man version:  {revnumber}
   5 :man manual:   Bspwm Manual
   6
   7 bspwm(1)
   8 ========
   9
  10 Name
  11 ----
  12
  13 bspwm - Tiling window manager based on binary space partitioning
  14
  15 Synopsis
  16 --------
  17
  18 *bspwm* [*-h*|*-v*|*-s* _PANEL_FIFO_|*-p* _PANEL_PREFIX_]
  19
  20 *bspc* _MESSAGE_ [_ARGUMENTS_] [_OPTIONS_]
  21
  22 Description
  23 -----------
  24
  25 *bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree.
  26
  27 It is controlled and configured via *bspc*.
  28
  29 Configuration
  30 -------------
  31
  32 *bspwm* have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
  33
  34 Its configuration file is _$XDG_CONFIG_HOME/bspwm/autostart_.
  35
  36 Keyboard and pointer bindings are defined with https://github.com/baskerville/sxhkd[sxhkd].
  37
  38 Example configuration files can be found in the *examples* directory.
  39
  40 Splitting Modes
  41 ---------------
  42
  43 There is only two splitting modes: _automatic_ and _manual_.
  44
  45 The default mode is _automatic_. The _manual_ mode is entered by sending a *presel* message.
  46
  47 Example: insertion of a new node (number 4) into the given tree in _automatic_ mode:
  48
  49 ----
  50               b                                   c
  51              / \                                 / \
  52             3   a              -->              4   b
  53             ^  / \                              ^  / \
  54               2   1                               3   a
  55                                                      / \
  56                                                     2   1
  57  +-------------------------+         +-------------------------+
  58  |            |            |         |            |            |
  59  |            |     2      |         |            |     3      |
  60  |            |            |         |            |            |
  61  |     3      |------------|   -->   |     4      |------------|
  62  |     ^      |            |         |     ^      |     |      |
  63  |            |     1      |         |            |  1  |  2   |
  64  |            |            |         |            |     |      |
  65  +-------------------------+         +-------------------------+
  66 ----
  67
  68 Same departure, but the mode is _manual_, and a *presel* _up_ message was sent beforehand:
  69
  70 ----
  71              b                                   b
  72             / \                                 / \
  73            3   a              -->              c   a
  74            ^  / \                             / \ / \
  75              2   1                           4  3 2  1
  76                                              ^
  77 +-------------------------+         +-------------------------+
  78 |            |            |         |            |            |
  79 |            |     2      |         |     4      |     2      |
  80 |            |            |         |     ^      |            |
  81 |     3      |------------|   -->   |------------|------------|
  82 |     ^      |            |         |            |            |
  83 |            |     1      |         |     3      |     1      |
  84 |            |            |         |            |            |
  85 +-------------------------+         +-------------------------+
  86 ----
  87
  88 Containers
  89 ----------
  90
  91 Each monitor contains at least one desktop.
  92
  93 Each desktop contains at most one tree.
  94
  95 Messages
  96 --------
  97
  98
  99 *get* _SETTING_::
 100     Return the value of the given setting.
 101
 102 *set* _SETTING_ _VALUE_::
 103     Set the value of the given setting.
 104
 105 *list* [_DESKTOP_NAME_]::
 106     Output the internal representation of the window tree.
 107
 108 *list_desktops* [*--quiet*]::
 109     Perform a dump of each desktop for the current monitor.
 110
 111 *list_monitors* [*--quiet*]::
 112     Perform a dump of each monitor.
 113
 114 *list_history*::
 115     Return the node focus history of each desktop.
 116
 117 *list_windows*::
 118     Return the list of managed windows (i.e. their identifiers).
 119
 120 *list_rules*::
 121     Return the list of rules.
 122
 123 *presel* _left_|_right_|_up_|_down_ [_SPLIT_RATIO_]::
 124     Switch to manual mode and select the splitting direction.
 125
 126 *cancel* [*--all*]::
 127     Switch to automatic mode.
 128
 129 *ratio* _VALUE_::
 130     Set the splitting ratio of the focused window.
 131
 132 *pad* _MONITOR_NAME_ [_TOP_PADDING_ [_RIGHT_PADDING_ [_BOTTOM_PADDING_ [_LEFT_PADDING_]]]]::
 133     Set the padding of the given monitor.
 134
 135 *focus* _left_|_right_|_up_|_down_::
 136     Focus the neighbor window situated in the given direction.
 137
 138 *shift* _left_|_right_|_up_|_down_::
 139     Exchange the current window with the given neighbor.
 140
 141 *swap* [*--keep-focus*]::
 142     Swap the focused window with the last focused window.
 143
 144 *push* _left_|_right_|_up_|_down_::
 145     Push the fence located in the given direction.
 146
 147 *pull* _left_|_right_|_up_|_down_::
 148     Pull the fence located in the given direction.
 149
 150 *fence_ratio* _left_|_right_|_up_|_down_ _RATIO_::
 151     Set the splitting ratio of the fence located in the given direction.
 152
 153 *cycle* _next_|_prev_ [*--skip-floating*|*--skip-tiled*|*--skip-class-equal*|*--skip-class-differ*]::
 154     Focus the next or previous window matching the given constraints.
 155
 156 *nearest* _older_|_newer_ [*--skip-floating*|*--skip-tiled*|*--skip-class-equal*|*--skip-class-differ*]::
 157     Focus the nearest window matching the given constraints.
 158
 159 *biggest*::
 160     Return the ID of the biggest tiled window.
 161
 162 *circulate* _forward_|_backward_::
 163     Circulate the leaves in the given direction.
 164
 165 *grab_pointer* _focus_|_move_|_resize_side_|_resize_corner_::
 166     Begin the specified pointer action.
 167
 168 *track_pointer* _ROOT_X_ _ROOT_Y_::
 169     Pass the pointer root coordinates for the current pointer action.
 170
 171 *ungrab_pointer*::
 172     End the current pointer action.
 173
 174 *toggle_fullscreen*::
 175     Toggle the fullscreen state of the current window.
 176
 177 *toggle_floating*::
 178     Toggle the floating state of the current window.
 179
 180 *toggle_locked*::
 181     Toggle the locked state of the current window (locked windows will not respond to the *close* message).
 182
 183 *toggle_visibility*::
 184     Toggle the visibility of all the managed windows.
 185
 186 *close*::
 187     Close the focused window.
 188
 189 *kill*::
 190     Kill the focused window.
 191
 192 *send_to* _DESKTOP_NAME_ [*--follow*]::
 193     Send the focused window to the given desktop.
 194
 195 *drop_to* _next_|_prev_ [*--follow*]::
 196     Send the focused window to the next or previous desktop.
 197
 198 *send_to_monitor* _MONITOR_NAME_ [*--follow*]::
 199     Send the focused window to the given monitor.
 200
 201 *drop_to_monitor* _next_|_prev_ [*--follow*]::
 202     Send the focused window to the next or previous monitor.
 203
 204 *use* _DESKTOP_NAME_::
 205     Select the given desktop.
 206
 207 *use_monitor* _MONITOR_NAME_::
 208     Select the given monitor.
 209
 210 *focus_monitor* _left_|_right_|_up_|_down_::
 211     Focus the nearest monitor in the given direction.
 212
 213 *alternate*::
 214     Alternate between the current and the last focused window.
 215
 216 *alternate_desktop*::
 217     Alternate between the current and the last focused desktop.
 218
 219 *alternate_monitor*::
 220     Alternate between the current and the last focused monitor.
 221
 222 *add* _DESKTOP_NAME_ ...::
 223     Make new desktops with the given names.
 224
 225 *add_in* _MONITOR_NAME_ _DESKTOP_NAME_ ...::
 226     Make new desktops with the given names in the given monitor.
 227
 228 *rename_monitor* _CURRENT_NAME_ _NEW_NAME_::
 229     Rename the monitor named _CURRENT_NAME_ to _NEW_NAME_.
 230
 231 *rename* _CURRENT_NAME_ _NEW_NAME_::
 232     Rename the desktop named _CURRENT_NAME_ to _NEW_NAME_.
 233
 234 *remove_desktop* _DESKTOP_NAME_ ...::
 235     Remove the given desktops.
 236
 237 *send_desktop_to* _MONITOR_NAME_ [*--follow*]::
 238     Send the current desktop to the given monitor.
 239
 240 *cycle_monitor* _next_|_prev_::
 241     Select the next or previous monitor.
 242
 243 *cycle_desktop* _next_|_prev_ [*--skip-free*|*--skip-occupied*]::
 244     Select the next or previous desktop.
 245
 246 *layout* _monocle_|_tiled_ [_DESKTOP_NAME_ ...]::
 247     Set the layout of the given desktops (current if none given).
 248
 249 *cycle_layout*::
 250     Cycle the layout of the current desktop.
 251
 252 *rotate* _clockwise_|_counter_clockwise_|_full_cycle_::
 253     Rotate the window tree.
 254
 255 *flip* _horizontal_|_vertical_::
 256     Flip the window tree.
 257
 258 *balance*::
 259     Adjust the split ratios so that all windows occupy the same area.
 260
 261 *rule* _PATTERN_ [_DESKTOP_NAME_] [_floating_] [_follow_]::
 262     Create a new rule (_PATTERN_ must match the class or instance name).
 263
 264 *remove_rule* _UID_ ...::
 265     Remove the rules with the given _UIDs_.
 266
 267 *put_status*::
 268     Output the current state to the panel fifo.
 269
 270 *adopt_orphans*::
 271     Manage all the unmanaged windows remaining from a previous session.
 272
 273 *restore_layout* _FILE_PATH_::
 274     Restore the layout of each desktop from the content of _FILE_PATH_.
 275
 276 *restore_history* _FILE_PATH_::
 277     Restore the history of each desktop from the content of _FILE_PATH_.
 278
 279 *quit* [_EXIT_STATUS_]::
 280     Quit.
 281
 282 Settings
 283 --------
 284 Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or _#RRGGBB_, booleans are _true_ or _false_.
 285
 286 All the boolean settings are _false_ by default.
 287
 288
 289 _focused_border_color_::
 290     Color of the border of a focused window of a focused monitor.
 291
 292 _active_border_color_::
 293     Color of the border of a focused window of an unfocused monitor.
 294
 295 _normal_border_color_::
 296     Color of the border of an unfocused window.
 297
 298 _presel_border_color_::
 299     Color of the *presel* message feedback.
 300
 301 _focused_locked_border_color_::
 302     Color of the border of a focused locked window of a focused monitor.
 303
 304 _active_locked_border_color_::
 305     Color of the border of a focused locked window of an unfocused monitor.
 306
 307 _normal_locked_border_color_::
 308     Color of the border of an unfocused locked window.
 309
 310 _urgent_border_color_::
 311     Color of the border of an urgent window.
 312
 313 _border_width_::
 314     Window border width.
 315
 316 _window_gap_::
 317     Value of the gap that separates windows.
 318
 319 _split_ratio_::
 320     Default split ratio.
 321
 322 _top_padding_, _right_padding_, _bottom_padding_, _left_padding_::
 323     Padding space added at the sides of the current monitor.
 324
 325 _wm_name_::
 326     The value that shall be used for the '_NET_WM_NAME' property of the root window.
 327
 328 _borderless_monocle_::
 329     Remove borders for tiled windows in monocle mode.
 330
 331 _gapless_monocle_::
 332     Remove gaps for tiled windows in monocle mode.
 333
 334 _focus_follows_pointer_::
 335     Focus the window under the pointer.
 336
 337 _pointer_follows_monitor_::
 338     When focusing a monitor, put the pointer at its center.
 339
 340 _monitor_focus_fallback_::
 341     If the focus message fails, try to focus the nearest monitor in the same direction.
 342
 343 _adaptative_raise_::
 344     Prevent floating windows from being raised when they might cover other floating windows.
 345
 346 _apply_shadow_property_::
 347     Enable shadows for floating windows via the '_COMPTON_SHADOW' property.
 348
 349 _auto_alternate_::
 350     Interpret two consecutive identical *use* messages as an *alternate* message.
 351
 352 _focus_by_distance_::
 353     Use window or leaf distance for focus movement.
 354
 355 _history_aware_focus_::
 356     Give priority to the focus history when focusing nodes.
 357
 358 Environment Variables
 359 ---------------------
 360
 361 _BSPWM_SOCKET_::
 362   The path of the socket used for the communication between *bspc* and *bspwm*.
 363
 364 Panels
 365 ------
 366
 367 * Any EWMH compliant panel (e.g.: _tint2_, _bmpanel2_, etc.).
 368 * A custom panel if the _-s_ flag is used (have a look at the files in _examples/panel_).
 369
 370 Key Features
 371 ------------
 372
 373 * Configured and controlled through messages.
 374 * Multiple monitors support (via _RandR_).
 375 * EWMH support (*tint2* works).
 376 * Automatic and manual modes.
 377
 378 Contributors
 379 ------------
 380
 381 * Ivan Kanakarakis <ivan.kanak at gmail.com>
 382 * Thomas Adam <thomas at xteddy.org>
 383
 384 Author
 385 ------
 386
 387 Bastien Dejean <baskerville at lavabit.com>
 388
 389 Mailing List
 390 ------------
 391
 392 bspwm at librelist.com
 393
 394 ////
 395 vim: set ft=asciidoc:
 396 ////