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 Desktop
 181 ~~~~~~~
 182
 183 Select a desktop.
 184
 185 ----
 186 DESKTOP_SEL := <desktop_name>
 187              | (CYCLE_DIR|last|focused)[.occupied|.free]
 188 ----
 189
 190 Primary Selectors
 191 ^^^^^^^^^^^^^^^^^
 192
 193 'CYCLE_DIR'::
 194     Selects the desktop in the given direction relative to the active desktop.
 195
 196 last::
 197     Selects the previously focused desktop.
 198
 199 focused::
 200     Selects the currently focused desktop.
 201
 202 Modifiers
 203 ^^^^^^^^^
 204
 205 occupied::
 206     Only consider occupied desktops.
 207
 208 free::
 209     Only consider free desktops.
 210
 211 Monitor
 212 ~~~~~~~
 213
 214 Select a monitor.
 215
 216 ----
 217 MONITOR_SEL := <monitor_name>
 218              | (DIR|CYCLE_DIR|last|focused)[.occupied|.free]
 219 ----
 220
 221 Primary Selectors
 222 ^^^^^^^^^^^^^^^^^
 223
 224 'DIR'::
 225     Selects the monitor in the given (spacial) direction relative to the active monitor.
 226
 227 'CYCLE_DIR'::
 228     Selects the monitor in the given (cyclic) direction relative to the active monitor.
 229
 230 last::
 231     Selects the previously focused monitor.
 232
 233 focused::
 234     Selects the currently focused monitor.
 235
 236 Modifiers
 237 ^^^^^^^^^
 238
 239 occupied::
 240     Only consider monitors where the focused desktop is occupied.
 241
 242 free::
 243     Only consider monitors where the focused desktop is free.
 244
 245
 246 Commands
 247 --------
 248
 249 Window
 250 ~~~~~~
 251
 252 General Syntax
 253 ^^^^^^^^^^^^^^
 254
 255 window ['WINDOW_SEL'] 'OPTIONS'
 256
 257 Options
 258 ^^^^^^^
 259 *-f*, *--focus* ['WINDOW_SEL']::
 260     Focus the selected or given window.
 261
 262 *-d*, *--to-desktop* 'DESKTOP_SEL'::
 263     Send the selected window to the given desktop.
 264
 265 *-m*, *--to-monitor* 'MONITOR_SEL'::
 266     Send the selected window to the given monitor.
 267
 268 *-w*, *--to-window* 'WINDOW_SEL'::
 269     Transplant the selected window to the given window.
 270
 271 *-s*, *--swap* 'WINDOW_SEL'::
 272     Swap the selected window with the given window.
 273
 274 *-p*, *--presel* 'DIR'|cancel::
 275     Preselect the splitting area of the selected window (or cancel the preselection).
 276
 277 *-r*, *--ratio* 'RATIO'::
 278     Set the splitting ratio of the selected window.
 279
 280 *-e*, *--edge* 'DIR' 'RATIO'|pull|push::
 281     Set the splitting ratio (or pull, or push) the edge located in the given direction in relation to the selected window.
 282
 283 *-t*, *--toggle* floating|fullscreen|locked[=on|off]::
 284     Set or toggle the given state for the selected window.
 285
 286 *-c*, *--close*::
 287     Close the selected window.
 288
 289 *-k*, *--kill*::
 290     Kill the selected window.
 291
 292 Desktop
 293 ~~~~~~~
 294
 295 General Syntax
 296 ^^^^^^^^^^^^^^
 297
 298 desktop ['DESKTOP_SEL'] 'OPTIONS'
 299
 300 Options
 301 ^^^^^^^
 302 *-f*, *--focus* ['DESKTOP_SEL']::
 303     Focus the selected or given desktop.
 304
 305 *-m*, *--to-monitor* 'MONITOR_SEL'::
 306     Send the selected desktop to the given monitor.
 307
 308 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
 309     Set or cycle the layout of the selected desktop.
 310
 311 *-n*, *--rename* <new_name>::
 312     Rename the selected desktop.
 313
 314 *-r*, *--remove*::
 315     Remove the selected desktop.
 316
 317 *-c*, *--cancel-presel*::
 318     Cancel the preselection of all the windows of the selected desktop.
 319
 320 *-F*, *--flip* 'horizontal|vertical'::
 321     Flip the tree of the selected desktop.
 322
 323 *-R*, *--rotate* '90|270|180'::
 324     Rotate the tree of the selected desktop.
 325
 326 *-B*, *--balance*::
 327     Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
 328
 329 *-C*, *--circulate* forward|backward::
 330     Circulate the leaves of the tree of the selected desktop.
 331
 332 Monitor
 333 ~~~~~~~
 334
 335 General Syntax
 336 ^^^^^^^^^^^^^^
 337
 338 monitor ['MONITOR_SEL'] 'OPTIONS'
 339
 340 Options
 341 ^^^^^^^
 342 *-f*, *--focus* ['MONITOR_SEL']::
 343     Focus the selected or given monitor.
 344
 345 *-a*, *--add-desktops* <name>...::
 346     Create desktops with the given names in the selected monitor.
 347
 348 *-r*, *--remove-desktops* <name>...::
 349     Remove desktops with the given names.
 350
 351 *-p*, *--pad* [<top> <right> <bottom> <left>]::
 352     Set or get the padding of the selected monitor.
 353
 354 *-n*, *--rename* <new_name>::
 355     Rename the selected monitor.
 356
 357 Query
 358 ~~~~~
 359
 360 General Syntax
 361 ^^^^^^^^^^^^^^
 362
 363 query 'OPTIONS'
 364
 365 Options
 366 ^^^^^^^
 367 *-W*, *--windows*::
 368     List matching windows.
 369
 370 *-D*, *--desktops*::
 371     List matching desktops.
 372
 373 *-M*, *--monitors*::
 374     List matching monitors.
 375
 376 *-T*, *--tree*::
 377     Print tree rooted at query.
 378
 379 *-H*, *--history*::
 380     Print the history as it relates to the query.
 381
 382 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
 383     Constrain matches to the selected monitor, desktop or window.
 384
 385 Restore
 386 ~~~~~~~
 387
 388 General Syntax
 389 ^^^^^^^^^^^^^^
 390
 391 restore 'OPTIONS'
 392
 393 Options
 394 ^^^^^^^
 395
 396 *-T*, *--tree* <file_path>::
 397     Load the desktop trees from the given file.
 398
 399 *-H*, *--history* <file_path>::
 400     Load the focus history from the given file.
 401
 402 Control
 403 ~~~~~~~
 404
 405 General Syntax
 406 ^^^^^^^^^^^^^^
 407
 408 control 'OPTIONS'
 409
 410 Options
 411 ^^^^^^^
 412
 413 *--adopt-orphans*::
 414    Manage all the unmanaged windows remaining from a previous session.
 415
 416 *--put-status*::
 417     Write the current internal state to the panel FIFO.
 418
 419 *--toggle-visibility*::
 420     Toggle the visibility of all the managed windows.
 421
 422 Pointer
 423 ~~~~~~~
 424
 425 General Syntax
 426 ^^^^^^^^^^^^^^
 427
 428 pointer 'OPTIONS'
 429
 430 Options
 431 ^^^^^^^
 432
 433 *-t*, *--track* <x> <y>::
 434     Pass the pointer root coordinates for the current pointer action.
 435
 436 *-g*, *--grab* focus|move|resize_side|resize_corner::
 437     Perform the given pointer action.
 438
 439 Rule
 440 ~~~~
 441
 442 General Syntax
 443 ^^^^^^^^^^^^^^
 444
 445 rule 'OPTIONS'
 446
 447 Options
 448 ^^^^^^^
 449
 450 *-a*, *--add* <pattern> [-d 'DESKTOP_SEL'] [--floating] [--follow]::
 451     Create a new rule (<pattern> must match the class or instance name).
 452
 453 *-r*, *--rm* <rule_uid>...::
 454     Remove the rules with the given UIDs.
 455
 456 *-l*, *--list* [<pattern>]::
 457     List the rules.
 458
 459 Config
 460 ~~~~~~
 461
 462 General Syntax
 463 ^^^^^^^^^^^^^^
 464
 465 config <key> [<value>]::
 466     Get or set the value of <key>.
 467
 468 Quit
 469 ~~~~
 470
 471 General Syntax
 472 ^^^^^^^^^^^^^^
 473
 474 quit [<status>]::
 475     Quit with an optional exit status.
 476
 477 Settings
 478 --------
 479 Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'.
 480
 481 All the boolean settings are 'false' by default.
 482
 483
 484 'focused_border_color'::
 485     Color of the border of a focused window of a focused monitor.
 486
 487 'active_border_color'::
 488     Color of the border of a focused window of an unfocused monitor.
 489
 490 'normal_border_color'::
 491     Color of the border of an unfocused window.
 492
 493 'presel_border_color'::
 494     Color of the *presel* message feedback.
 495
 496 'focused_locked_border_color'::
 497     Color of the border of a focused locked window of a focused monitor.
 498
 499 'active_locked_border_color'::
 500     Color of the border of a focused locked window of an unfocused monitor.
 501
 502 'normal_locked_border_color'::
 503     Color of the border of an unfocused locked window.
 504
 505 'urgent_border_color'::
 506     Color of the border of an urgent window.
 507
 508 'border_width'::
 509     Window border width.
 510
 511 'window_gap'::
 512     Value of the gap that separates windows.
 513
 514 'split_ratio'::
 515     Default split ratio.
 516
 517 'wm_name'::
 518     The value that shall be used for the '_NET_WM_NAME' property of the root window.
 519
 520 'borderless_monocle'::
 521     Remove borders for tiled windows in monocle mode.
 522
 523 'gapless_monocle'::
 524     Remove gaps for tiled windows in monocle mode.
 525
 526 'focus_follows_pointer'::
 527     Focus the window under the pointer.
 528
 529 'pointer_follows_monitor'::
 530     When focusing a monitor, put the pointer at its center.
 531
 532 'adaptative_raise'::
 533     Prevent floating windows from being raised when they might cover other floating windows.
 534
 535 'apply_shadow_property'::
 536     Enable shadows for floating windows via the '_COMPTON_SHADOW' property.
 537
 538 'auto_alternate'::
 539     Interpret two consecutive identical *use* messages as an *alternate* message.
 540
 541 'auto_cancel'::
 542     Interpret two consecutive identical *presel* messages as a *cancel* message.
 543
 544 'history_aware_focus'::
 545     Give priority to the focus history when focusing nodes.
 546
 547 Environment Variables
 548 ---------------------
 549
 550 'BSPWM_SOCKET'::
 551   The path of the socket used for the communication between *bspc* and *bspwm*.
 552
 553 Panels
 554 ------
 555
 556 * Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.).
 557 * A custom panel if the '-s' flag is used (have a look at the files in 'examples/panel').
 558
 559 Key Features
 560 ------------
 561
 562 * Configured and controlled through messages.
 563 * Multiple monitors support (via 'RandR').
 564 * EWMH support (*tint2* works).
 565 * Hybrid tiling.
 566
 567 Contributors
 568 ------------
 569
 570 * Steven Allen <steven at stebalien.com>
 571 * Thomas Adam <thomas at xteddy.org>
 572 * Ivan Kanakarakis <ivan.kanak at gmail.com>
 573
 574 Author
 575 ------
 576
 577 Bastien Dejean <baskerville at lavabit.com>
 578
 579 Mailing List
 580 ------------
 581
 582 bspwm at librelist.com
 583
 584 ////
 585 vim: set ft=asciidoc:
 586 ////