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* 'COMMAND' ['ARGUMENTS']
  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
  30 Options
  31 -------
  32
  33 *-h*::
  34     Print the synopsis and exit.
  35
  36 *-v*::
  37     Print the version and exit.
  38
  39 *-s* 'PANEL_FIFO'::
  40     Write the internal state to the given FIFO.
  41
  42 *-p* 'PANEL_PREFIX'::
  43     Start every line written to the 'PANEL_FIFO' with the given prefix.
  44
  45
  46 Configuration
  47 -------------
  48
  49 *bspwm* have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
  50
  51 Its configuration file is '$XDG_CONFIG_HOME/bspwm/autostart'.
  52
  53 Keyboard and pointer bindings are defined with https://github.com/baskerville/sxhkd[sxhkd].
  54
  55 Example configuration files can be found in the *examples* directory.
  56
  57 Splitting Modes
  58 ---------------
  59
  60 New windows are inserted in the tree as close as possible to the focused window.
  61
  62 There is only two splitting modes: 'automatic' and 'manual'.
  63
  64 The default mode is 'automatic'. The 'manual' mode is entered by sending a *preselection* message.
  65
  66 Example: insertion of a new node (number 4) into the given tree in 'automatic' mode:
  67
  68 ----
  69               b                                   c
  70              / \                                 / \
  71             3   a              -->              4   b
  72             ^  / \                              ^  / \
  73               2   1                               3   a
  74                                                      / \
  75                                                     2   1
  76  +-------------------------+         +-------------------------+
  77  |            |            |         |            |            |
  78  |            |     2      |         |            |     3      |
  79  |            |            |         |            |            |
  80  |     3      |------------|   -->   |     4      |------------|
  81  |     ^      |            |         |     ^      |     |      |
  82  |            |     1      |         |            |  1  |  2   |
  83  |            |            |         |            |     |      |
  84  +-------------------------+         +-------------------------+
  85 ----
  86
  87 Same departure, but the mode is 'manual', and a *window --presel up* message was sent beforehand:
  88
  89 ----
  90              b                                   b
  91             / \                                 / \
  92            3   a              -->              c   a
  93            ^  / \                             / \ / \
  94              2   1                           4  3 2  1
  95                                              ^
  96 +-------------------------+         +-------------------------+
  97 |            |            |         |            |            |
  98 |            |     2      |         |     4      |     2      |
  99 |            |            |         |     ^      |            |
 100 |     3      |------------|   -->   |------------|------------|
 101 |     ^      |            |         |            |            |
 102 |            |     1      |         |     3      |     1      |
 103 |            |            |         |            |            |
 104 +-------------------------+         +-------------------------+
 105 ----
 106
 107 Containers
 108 ----------
 109
 110 Each monitor contains at least one desktop.
 111
 112 Each desktop contains at most one tree.
 113
 114 Common Definitions
 115 ------------------
 116
 117 ----
 118 DIR         := left | right | up | down
 119 CYCLE_DIR   := next | prev
 120 ----
 121
 122 Selectors
 123 ---------
 124
 125 Selectors are used to select a target window, desktop, or monitor. A selector
 126 can either describe the target relatively or name it globally.
 127
 128 Descriptive (relative) selectors consist of a primary selector and any number
 129 of non-conflicting modifiers as follows:
 130
 131     PRIMARY_SELECTOR[.MODIFIER]*
 132
 133 For obvious reasons, neither desktops nor monitors names may be valid
 134 descriptive selectors.
 135
 136 Window
 137 ~~~~~~
 138
 139 Select a window.
 140
 141 ----
 142 WINDOW_SEL := <window_id>
 143             | (DIR|CYCLE_DIR|biggest|last|focused)[.floating|.tiled][.like|.unlike]
 144 ----
 145
 146 Primary Selectors
 147 ^^^^^^^^^^^^^^^^^
 148
 149 'DIR'::
 150     Selects the window in the given (spacial) direction relative to the active
 151     window.
 152
 153 'CYCLE_DIR'::
 154     Selects the window in the given (cyclic) direction.
 155
 156 biggest::
 157     Selects the biggest window on the current desktop.
 158
 159 last::
 160     Selects the previously focused window on the current desktop.
 161
 162 focused::
 163     Selects the currently focused window.
 164
 165 Modifiers
 166 ^^^^^^^^^
 167
 168 floating::
 169     Only consider floating windows.
 170
 171 tiled::
 172     Only consider tiled windows.
 173
 174 like::
 175     Only consider windows that have the same class as the current window.
 176
 177 unlike::
 178     Only consider windows that have a different class than the current window.
 179
 180 automatic::
 181     Only consider windows in automatic splitting mode.
 182
 183 manual::
 184     Only consider windows in manual splitting mode (see *--presel*).
 185
 186 Desktop
 187 ~~~~~~~
 188
 189 Select a desktop.
 190
 191 ----
 192 DESKTOP_SEL := <desktop_name>
 193              | (CYCLE_DIR|last|focused)[.occupied|.free]
 194 ----
 195
 196 Primary Selectors
 197 ^^^^^^^^^^^^^^^^^
 198
 199 'CYCLE_DIR'::
 200     Selects the desktop in the given direction relative to the active desktop.
 201
 202 last::
 203     Selects the previously focused desktop.
 204
 205 focused::
 206     Selects the currently focused desktop.
 207
 208 Modifiers
 209 ^^^^^^^^^
 210
 211 occupied::
 212     Only consider occupied desktops.
 213
 214 free::
 215     Only consider free desktops.
 216
 217 Monitor
 218 ~~~~~~~
 219
 220 Select a monitor.
 221
 222 ----
 223 MONITOR_SEL := <monitor_name>
 224              | (DIR|CYCLE_DIR|last|focused)[.occupied|.free]
 225 ----
 226
 227 Primary Selectors
 228 ^^^^^^^^^^^^^^^^^
 229
 230 'DIR'::
 231     Selects the monitor in the given (spacial) direction relative to the active monitor.
 232
 233 'CYCLE_DIR'::
 234     Selects the monitor in the given (cyclic) direction relative to the active monitor.
 235
 236 last::
 237     Selects the previously focused monitor.
 238
 239 focused::
 240     Selects the currently focused monitor.
 241
 242 Modifiers
 243 ^^^^^^^^^
 244
 245 occupied::
 246     Only consider monitors where the focused desktop is occupied.
 247
 248 free::
 249     Only consider monitors where the focused desktop is free.
 250
 251
 252 Commands
 253 --------
 254
 255 Window
 256 ~~~~~~
 257
 258 General Syntax
 259 ^^^^^^^^^^^^^^
 260
 261 window ['WINDOW_SEL'] 'OPTIONS'
 262
 263 Options
 264 ^^^^^^^
 265 *-f*, *--focus* ['WINDOW_SEL']::
 266     Focus the selected or given window.
 267
 268 *-d*, *--to-desktop* 'DESKTOP_SEL'::
 269     Send the selected window to the given desktop.
 270
 271 *-m*, *--to-monitor* 'MONITOR_SEL'::
 272     Send the selected window to the given monitor.
 273
 274 *-w*, *--to-window* 'WINDOW_SEL'::
 275     Transplant the selected window to the given window.
 276
 277 *-s*, *--swap* 'WINDOW_SEL'::
 278     Swap the selected window with the given window.
 279
 280 *-p*, *--presel* 'DIR'|cancel::
 281     Preselect the splitting area of the selected window (or cancel the preselection).
 282
 283 *-r*, *--ratio* 'RATIO'::
 284     Set the splitting ratio of the selected window.
 285
 286 *-e*, *--edge* 'DIR' 'RATIO'|pull|push::
 287     Set the splitting ratio (or pull, or push) the edge located in the given direction in relation to the selected window.
 288
 289 *-t*, *--toggle* floating|fullscreen|locked[=on|off]::
 290     Set or toggle the given state for the selected window.
 291
 292 *-c*, *--close*::
 293     Close the selected window.
 294
 295 *-k*, *--kill*::
 296     Kill the selected window.
 297
 298 Desktop
 299 ~~~~~~~
 300
 301 General Syntax
 302 ^^^^^^^^^^^^^^
 303
 304 desktop ['DESKTOP_SEL'] 'OPTIONS'
 305
 306 Options
 307 ^^^^^^^
 308 *-f*, *--focus* ['DESKTOP_SEL']::
 309     Focus the selected or given desktop.
 310
 311 *-m*, *--to-monitor* 'MONITOR_SEL'::
 312     Send the selected desktop to the given monitor.
 313
 314 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
 315     Set or cycle the layout of the selected desktop.
 316
 317 *-n*, *--rename* <new_name>::
 318     Rename the selected desktop.
 319
 320 *-r*, *--remove*::
 321     Remove the selected desktop.
 322
 323 *-c*, *--cancel-presel*::
 324     Cancel the preselection of all the windows of the selected desktop.
 325
 326 *-F*, *--flip* 'horizontal|vertical'::
 327     Flip the tree of the selected desktop.
 328
 329 *-R*, *--rotate* '90|270|180'::
 330     Rotate the tree of the selected desktop.
 331
 332 *-B*, *--balance*::
 333     Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
 334
 335 *-C*, *--circulate* forward|backward::
 336     Circulate the leaves of the tree of the selected desktop.
 337
 338 Monitor
 339 ~~~~~~~
 340
 341 General Syntax
 342 ^^^^^^^^^^^^^^
 343
 344 monitor ['MONITOR_SEL'] 'OPTIONS'
 345
 346 Options
 347 ^^^^^^^
 348 *-f*, *--focus* ['MONITOR_SEL']::
 349     Focus the selected or given monitor.
 350
 351 *-a*, *--add-desktops* <name>...::
 352     Create desktops with the given names in the selected monitor.
 353
 354 *-r*, *--remove-desktops* <name>...::
 355     Remove desktops with the given names.
 356
 357 *-p*, *--pad* [<top> <right> <bottom> <left>]::
 358     Set or get the padding of the selected monitor.
 359
 360 *-n*, *--rename* <new_name>::
 361     Rename the selected monitor.
 362
 363 Query
 364 ~~~~~
 365
 366 General Syntax
 367 ^^^^^^^^^^^^^^
 368
 369 query 'OPTIONS'
 370
 371 Options
 372 ^^^^^^^
 373 *-W*, *--windows*::
 374     List matching windows.
 375
 376 *-D*, *--desktops*::
 377     List matching desktops.
 378
 379 *-M*, *--monitors*::
 380     List matching monitors.
 381
 382 *-T*, *--tree*::
 383     Print tree rooted at query.
 384
 385 *-H*, *--history*::
 386     Print the history as it relates to the query.
 387
 388 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
 389     Constrain matches to the selected monitor, desktop or window.
 390
 391 Restore
 392 ~~~~~~~
 393
 394 General Syntax
 395 ^^^^^^^^^^^^^^
 396
 397 restore 'OPTIONS'
 398
 399 Options
 400 ^^^^^^^
 401
 402 *-T*, *--tree* <file_path>::
 403     Load the desktop trees from the given file.
 404
 405 *-H*, *--history* <file_path>::
 406     Load the focus history from the given file.
 407
 408 Control
 409 ~~~~~~~
 410
 411 General Syntax
 412 ^^^^^^^^^^^^^^
 413
 414 control 'OPTIONS'
 415
 416 Options
 417 ^^^^^^^
 418
 419 *--adopt-orphans*::
 420    Manage all the unmanaged windows remaining from a previous session.
 421
 422 *--put-status*::
 423     Write the current internal state to the panel FIFO.
 424
 425 *--toggle-visibility*::
 426     Toggle the visibility of all the managed windows.
 427
 428 Pointer
 429 ~~~~~~~
 430
 431 General Syntax
 432 ^^^^^^^^^^^^^^
 433
 434 pointer 'OPTIONS'
 435
 436 Options
 437 ^^^^^^^
 438
 439 *-t*, *--track* <x> <y>::
 440     Pass the pointer root coordinates for the current pointer action.
 441
 442 *-g*, *--grab* focus|move|resize_side|resize_corner::
 443     Perform the given pointer action.
 444
 445 Rule
 446 ~~~~
 447
 448 General Syntax
 449 ^^^^^^^^^^^^^^
 450
 451 rule 'OPTIONS'
 452
 453 Options
 454 ^^^^^^^
 455
 456 *-a*, *--add* <pattern> [-d 'DESKTOP_SEL'] [--floating] [--follow]::
 457     Create a new rule (<pattern> must match the class or instance name).
 458
 459 *-r*, *--rm* <rule_uid>...::
 460     Remove the rules with the given UIDs.
 461
 462 *-l*, *--list* [<pattern>]::
 463     List the rules.
 464
 465 Config
 466 ~~~~~~
 467
 468 General Syntax
 469 ^^^^^^^^^^^^^^
 470
 471 config <key> [<value>]::
 472     Get or set the value of <key>.
 473
 474 Quit
 475 ~~~~
 476
 477 General Syntax
 478 ^^^^^^^^^^^^^^
 479
 480 quit [<status>]::
 481     Quit with an optional exit status.
 482
 483 Settings
 484 --------
 485 Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'.
 486
 487 All the boolean settings are 'false' by default.
 488
 489
 490 'focused_border_color'::
 491     Color of the border of a focused window of a focused monitor.
 492
 493 'active_border_color'::
 494     Color of the border of a focused window of an unfocused monitor.
 495
 496 'normal_border_color'::
 497     Color of the border of an unfocused window.
 498
 499 'presel_border_color'::
 500     Color of the *presel* message feedback.
 501
 502 'focused_locked_border_color'::
 503     Color of the border of a focused locked window of a focused monitor.
 504
 505 'active_locked_border_color'::
 506     Color of the border of a focused locked window of an unfocused monitor.
 507
 508 'normal_locked_border_color'::
 509     Color of the border of an unfocused locked window.
 510
 511 'urgent_border_color'::
 512     Color of the border of an urgent window.
 513
 514 'border_width'::
 515     Window border width.
 516
 517 'window_gap'::
 518     Value of the gap that separates windows.
 519
 520 'split_ratio'::
 521     Default split ratio.
 522
 523 'wm_name'::
 524     The value that shall be used for the '_NET_WM_NAME' property of the root window.
 525
 526 'borderless_monocle'::
 527     Remove borders for tiled windows in monocle mode.
 528
 529 'gapless_monocle'::
 530     Remove gaps for tiled windows in monocle mode.
 531
 532 'focus_follows_pointer'::
 533     Focus the window under the pointer.
 534
 535 'pointer_follows_monitor'::
 536     When focusing a monitor, put the pointer at its center.
 537
 538 'adaptative_raise'::
 539     Prevent floating windows from being raised when they might cover other floating windows.
 540
 541 'apply_shadow_property'::
 542     Enable shadows for floating windows via the '_COMPTON_SHADOW' property.
 543
 544 'auto_alternate'::
 545     Interpret two consecutive identical *use* messages as an *alternate* message.
 546
 547 'auto_cancel'::
 548     Interpret two consecutive identical *presel* messages as a *cancel* message.
 549
 550 'history_aware_focus'::
 551     Give priority to the focus history when focusing nodes.
 552
 553 Environment Variables
 554 ---------------------
 555
 556 'BSPWM_SOCKET'::
 557   The path of the socket used for the communication between *bspc* and *bspwm*.
 558
 559 Panels
 560 ------
 561
 562 * Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.).
 563 * A custom panel if the '-s' flag is used (have a look at the files in 'examples/panel').
 564
 565 Key Features
 566 ------------
 567
 568 * Configured and controlled through messages.
 569 * Multiple monitors support (via 'RandR').
 570 * EWMH support (*tint2* works).
 571 * Hybrid tiling.
 572
 573 Contributors
 574 ------------
 575
 576 * Steven Allen <steven at stebalien.com>
 577 * Thomas Adam <thomas at xteddy.org>
 578 * Ivan Kanakarakis <ivan.kanak at gmail.com>
 579
 580 Author
 581 ------
 582
 583 Bastien Dejean <baskerville at lavabit.com>
 584
 585 Mailing List
 586 ------------
 587
 588 bspwm at librelist.com
 589
 590 ////
 591 vim: set ft=asciidoc:
 592 ////