doc/bspwm.1.txt

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