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 - Binary space partitioning window manager
  12
  13 Synopsis
  14 --------
  15
  16 *bspwm* [*-h*|*-v*|*-c* 'CONFIG_PATH']
  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 Configuration
  41 -------------
  42
  43 *bspwm* has only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
  44
  45 The default configuration file is '$XDG_CONFIG_HOME/bspwm/bspwmrc'.
  46
  47 Keyboard and pointer bindings are defined with https://github.com/baskerville/sxhkd[sxhkd].
  48
  49 Example configuration files can be found in the *examples* directory.
  50
  51 Splitting Modes
  52 ---------------
  53
  54 New windows are inserted in the tree as close as possible to the focused window.
  55
  56 There is only two splitting modes: 'automatic' and 'manual'.
  57
  58 The default mode is 'automatic'. The 'manual' mode is entered by sending a *preselection* message.
  59
  60 Example: insertion of a new node (number 4) into the given tree in 'automatic' mode:
  61
  62 ----
  63               b                                   c
  64              / \                                 / \
  65             3   a              -->              4   b
  66             ^  / \                              ^  / \
  67               2   1                               3   a
  68                                                      / \
  69                                                     2   1
  70  +-------------------------+         +-------------------------+
  71  |            |            |         |            |            |
  72  |            |     2      |         |            |     3      |
  73  |            |            |         |            |            |
  74  |     3      |------------|   -->   |     4      |------------|
  75  |     ^      |            |         |     ^      |     |      |
  76  |            |     1      |         |            |  1  |  2   |
  77  |            |            |         |            |     |      |
  78  +-------------------------+         +-------------------------+
  79 ----
  80
  81 Same departure, but the mode is 'manual', and a *window --presel up* message was sent beforehand:
  82
  83 ----
  84              b                                   b
  85             / \                                 / \
  86            3   a              -->              c   a
  87            ^  / \                             / \ / \
  88              2   1                           4  3 2  1
  89                                              ^
  90 +-------------------------+         +-------------------------+
  91 |            |            |         |            |            |
  92 |            |     2      |         |     4      |     2      |
  93 |            |            |         |     ^      |            |
  94 |     3      |------------|   -->   |------------|------------|
  95 |     ^      |            |         |            |            |
  96 |            |     1      |         |     3      |     1      |
  97 |            |            |         |            |            |
  98 +-------------------------+         +-------------------------+
  99 ----
 100
 101 Containers
 102 ----------
 103
 104 Each monitor contains at least one desktop.
 105
 106 Each desktop contains at most one tree.
 107
 108 Common Definitions
 109 ------------------
 110
 111 ----
 112 DIR         := left | right | up | down
 113 CYCLE_DIR   := next | prev
 114 ----
 115
 116 Selectors
 117 ---------
 118
 119 Selectors are used to select a target window, desktop, or monitor. A selector
 120 can either describe the target relatively or name it globally.
 121
 122 Descriptive (relative) selectors consist of a primary selector and any number
 123 of non-conflicting modifiers as follows:
 124
 125     PRIMARY_SELECTOR[.MODIFIER]*
 126
 127 For obvious reasons, neither desktops nor monitors names may be valid
 128 descriptive selectors.
 129
 130 Window
 131 ~~~~~~
 132
 133 Select a window.
 134
 135 ----
 136 WINDOW_SEL := <window_id>
 137             | (DIR|CYCLE_DIR|biggest|last|focused|older|newer)[.floating|.tiled][.like|.unlike][.manual][.urgent][.local]
 138 ----
 139
 140 Primary Selectors
 141 ^^^^^^^^^^^^^^^^^
 142
 143 'DIR'::
 144     Selects the window in the given (spacial) direction relative to the active
 145     window.
 146
 147 'CYCLE_DIR'::
 148     Selects the window in the given (cyclic) direction.
 149
 150 biggest::
 151     Selects the biggest window on the current desktop.
 152
 153 last::
 154     Selects the previously focused window.
 155
 156 focused::
 157     Selects the currently focused window.
 158
 159 older::
 160     Selects the window older than the focused window in the history.
 161
 162 newer::
 163     Selects the window newer than the focused window in the history.
 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 manual::
 181     Only consider windows in manual splitting mode (see *--presel*).
 182
 183 local::
 184     Only consider windows of the current desktop.
 185
 186 urgent::
 187     Only consider urgent windows.
 188
 189 Desktop
 190 ~~~~~~~
 191
 192 Select a desktop.
 193
 194 ----
 195 DESKTOP_SEL := <desktop_name>
 196              | ^<n>
 197              | (CYCLE_DIR|last|focused|older|newer)[.occupied|.free][.urgent][.local]
 198 ----
 199
 200 Primary Selectors
 201 ^^^^^^^^^^^^^^^^^
 202
 203 <desktop_name>::
 204     Selects the desktop with the given name.
 205
 206 ^<n>::
 207     Selects the nth desktop.
 208
 209 'CYCLE_DIR'::
 210     Selects the desktop in the given direction relative to the active desktop.
 211
 212 last::
 213     Selects the previously focused desktop.
 214
 215 focused::
 216     Selects the currently focused desktop.
 217
 218 older::
 219     Selects the desktop older than the focused desktop in the history.
 220
 221 newer::
 222     Selects the desktop newer than the focused desktop in the history.
 223
 224 Modifiers
 225 ^^^^^^^^^
 226
 227 occupied::
 228     Only consider occupied desktops.
 229
 230 free::
 231     Only consider free desktops.
 232
 233 urgent::
 234     Only consider urgent desktops.
 235
 236 local::
 237     Only consider desktops of the current monitor.
 238
 239 Monitor
 240 ~~~~~~~
 241
 242 Select a monitor.
 243
 244 ----
 245 MONITOR_SEL := <monitor_name>
 246              | ^<n>
 247              | (DIR|CYCLE_DIR|last|primary|focused|older|newer)[.occupied|.free]
 248 ----
 249
 250 Primary Selectors
 251 ^^^^^^^^^^^^^^^^^
 252
 253 <monitor_name>::
 254     Selects the monitor with the given name.
 255
 256 ^<n>::
 257     Selects the nth monitor.
 258
 259 'DIR'::
 260     Selects the monitor in the given (spacial) direction relative to the active monitor.
 261
 262 'CYCLE_DIR'::
 263     Selects the monitor in the given (cyclic) direction relative to the active monitor.
 264
 265 primary::
 266     Selects the primary monitor.
 267
 268 last::
 269     Selects the previously focused monitor.
 270
 271 focused::
 272     Selects the currently focused monitor.
 273
 274 older::
 275     Selects the monitor older than the focused monitor in the history.
 276
 277 newer::
 278     Selects the monitor newer than the focused monitor in the history.
 279
 280 Modifiers
 281 ^^^^^^^^^
 282
 283 occupied::
 284     Only consider monitors where the focused desktop is occupied.
 285
 286 free::
 287     Only consider monitors where the focused desktop is free.
 288
 289
 290 Commands
 291 --------
 292
 293 Window
 294 ~~~~~~
 295
 296 General Syntax
 297 ^^^^^^^^^^^^^^
 298
 299 window ['WINDOW_SEL'] 'OPTIONS'
 300
 301 Options
 302 ^^^^^^^
 303 *-f*, *--focus* ['WINDOW_SEL']::
 304     Focus the selected or given window.
 305
 306 *-d*, *--to-desktop* 'DESKTOP_SEL'::
 307     Send the selected window to the given desktop.
 308
 309 *-m*, *--to-monitor* 'MONITOR_SEL'::
 310     Send the selected window to the given monitor.
 311
 312 *-w*, *--to-window* 'WINDOW_SEL'::
 313     Transplant the selected window to the given window.
 314
 315 *-s*, *--swap* 'WINDOW_SEL'::
 316     Swap the selected window with the given window.
 317
 318 *-p*, *--presel* 'DIR'|cancel::
 319     Preselect the splitting area of the selected window (or cancel the preselection).
 320
 321 *-r*, *--ratio* 'RATIO'::
 322     Set the splitting ratio of the selected window (0 < 'RATIO' < 1).
 323
 324 *-e*, *--edge* 'DIR' 'RATIO'|pull|push::
 325     Set the splitting ratio (or pull, or push) the edge located in the given direction in relation to the selected window.
 326
 327 *-R*, *--rotate* 'DIR' '90|270|180'::
 328     Rotate the tree holding the edge located in the given direction in relation to the selected window.
 329
 330 *-t*, *--toggle* floating|fullscreen|locked|sticky|private[=on|off]::
 331     Set or toggle the given state for the selected window.
 332
 333 *-c*, *--close*::
 334     Close the selected window.
 335
 336 *-k*, *--kill*::
 337     Kill the selected window.
 338
 339 Desktop
 340 ~~~~~~~
 341
 342 General Syntax
 343 ^^^^^^^^^^^^^^
 344
 345 desktop ['DESKTOP_SEL'] 'OPTIONS'
 346
 347 Options
 348 ^^^^^^^
 349 *-f*, *--focus* ['DESKTOP_SEL']::
 350     Focus the selected or given desktop.
 351
 352 *-m*, *--to-monitor* 'MONITOR_SEL'::
 353     Send the selected desktop to the given monitor.
 354
 355 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
 356     Set or cycle the layout of the selected desktop.
 357
 358 *-n*, *--rename* <new_name>::
 359     Rename the selected desktop.
 360
 361 *-s*, *--swap* 'DESKTOP_SEL'::
 362     Swap the selected desktop with the given desktop.
 363
 364 *-r*, *--remove*::
 365     Remove the selected desktop.
 366
 367 *-c*, *--cancel-presel*::
 368     Cancel the preselection of all the windows of the selected desktop.
 369
 370 *-F*, *--flip* 'horizontal|vertical'::
 371     Flip the tree of the selected desktop.
 372
 373 *-R*, *--rotate* '90|270|180'::
 374     Rotate the tree of the selected desktop.
 375
 376 *-B*, *--balance*::
 377     Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
 378
 379 *-C*, *--circulate* forward|backward::
 380     Circulate the leaves of the tree of the selected desktop.
 381
 382 *-t*, *--toggle* floating[=on|off]::
 383     Set or toggle the given state for the selected desktop.
 384
 385
 386 Monitor
 387 ~~~~~~~
 388
 389 General Syntax
 390 ^^^^^^^^^^^^^^
 391
 392 monitor ['MONITOR_SEL'] 'OPTIONS'
 393
 394 Options
 395 ^^^^^^^
 396 *-f*, *--focus* ['MONITOR_SEL']::
 397     Focus the selected or given monitor.
 398
 399 *-a*, *--add-desktops* <name>...::
 400     Create desktops with the given names in the selected monitor.
 401
 402 *-r*, *--remove-desktops* <name>...::
 403     Remove desktops with the given names.
 404
 405 *-n*, *--rename* <new_name>::
 406     Rename the selected monitor.
 407
 408 *-d*, *--reset-desktops* <name>...::
 409     Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops.
 410
 411 *-s*, *--swap* 'MONITOR_SEL'::
 412     Swap the selected monitor with the given monitor.
 413
 414 Query
 415 ~~~~~
 416
 417 General Syntax
 418 ^^^^^^^^^^^^^^
 419
 420 query 'OPTIONS'
 421
 422 Options
 423 ^^^^^^^
 424 *-W*, *--windows*::
 425     List matching windows.
 426
 427 *-D*, *--desktops*::
 428     List matching desktops.
 429
 430 *-M*, *--monitors*::
 431     List matching monitors.
 432
 433 *-T*, *--tree*::
 434     Print tree rooted at query.
 435
 436 *-H*, *--history*::
 437     Print the history as it relates to the query.
 438
 439 *-S*, *--stack*::
 440     Print the window stacking order.
 441
 442 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
 443     Constrain matches to the selected monitor, desktop or window.
 444
 445 Restore
 446 ~~~~~~~
 447
 448 General Syntax
 449 ^^^^^^^^^^^^^^
 450
 451 restore 'OPTIONS'
 452
 453 Options
 454 ^^^^^^^
 455
 456 *-T*, *--tree* <file_path>::
 457     Load the desktop trees from the given file.
 458
 459 *-H*, *--history* <file_path>::
 460     Load the focus history from the given file.
 461
 462 *-S*, *--stack* <file_path>::
 463     Load the window stacking order from the given file.
 464
 465 Control
 466 ~~~~~~~
 467
 468 General Syntax
 469 ^^^^^^^^^^^^^^
 470
 471 control 'OPTIONS'
 472
 473 Options
 474 ^^^^^^^
 475
 476 *--adopt-orphans*::
 477     Manage all the unmanaged windows remaining from a previous session.
 478
 479 *--toggle-visibility*::
 480     Toggle the visibility of all the windows.
 481
 482 *--record-history* on|off::
 483     Enable or disable the recording of window focus history.
 484
 485 *--subscribe*::
 486     Continuously print status informations on standard output.
 487
 488 Pointer
 489 ~~~~~~~
 490
 491 General Syntax
 492 ^^^^^^^^^^^^^^
 493
 494 pointer 'OPTIONS'
 495
 496 Options
 497 ^^^^^^^
 498
 499 *-g*, *--grab* focus|move|resize_side|resize_corner::
 500     Initiate the given pointer action.
 501
 502 *-t*, *--track* <x> <y>::
 503     Pass the pointer root coordinates for the current pointer action.
 504
 505 *-u*, *--ungrab*::
 506     Terminate the current pointer action.
 507
 508 Config
 509 ~~~~~~
 510
 511 General Syntax
 512 ^^^^^^^^^^^^^^
 513
 514 config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'] <key> [<value>]::
 515     Get or set the value of <key>.
 516
 517 Quit
 518 ~~~~
 519
 520 General Syntax
 521 ^^^^^^^^^^^^^^
 522
 523 quit [<status>]::
 524     Quit with an optional exit status.
 525
 526 Settings
 527 --------
 528 Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'.
 529
 530 All the boolean settings are 'false' by default.
 531
 532 Global Settings
 533 ~~~~~~~~~~~~~~~
 534
 535 'rule_command'::
 536     External command used to retrieve rule consequences. The command will receive the the ID of the window being processed as its first argument. The output of that command must have the following format: *key1=value1 key2=value2 ...*, where *keyN* is one of 'floating', 'fullscreen', 'locked', 'sticky', 'private', 'frame', 'center', 'lower', 'follow', 'manage', 'focus', 'desktop' or 'monitor'.
 537
 538 'status_prefix'::
 539     Prefix prepended to each of the status lines.
 540
 541 'focused_border_color'::
 542     Color of the border of a focused window of a focused monitor.
 543
 544 'active_border_color'::
 545     Color of the border of a focused window of an unfocused monitor.
 546
 547 'normal_border_color'::
 548     Color of the border of an unfocused window.
 549
 550 'presel_border_color'::
 551     Color of the *presel* message feedback.
 552
 553 'focused_locked_border_color'::
 554     Color of the border of a focused locked window of a focused monitor.
 555
 556 'active_locked_border_color'::
 557     Color of the border of a focused locked window of an unfocused monitor.
 558
 559 'normal_locked_border_color'::
 560     Color of the border of an unfocused locked window.
 561
 562 'focused_sticky_border_color'::
 563     Color of the border of a focused sticky window of a focused monitor.
 564
 565 'active_sticky_border_color'::
 566     Color of the border of a focused sticky window of an unfocused monitor.
 567
 568 'normal_sticky_border_color'::
 569     Color of the border of an unfocused sticky window.
 570
 571 'focused_private_border_color'::
 572     Color of the border of a focused private window of a focused monitor.
 573
 574 'active_private_border_color'::
 575     Color of the border of a focused private window of an unfocused monitor.
 576
 577 'normal_private_border_color'::
 578     Color of the border of an unfocused private window.
 579
 580 'urgent_border_color'::
 581     Color of the border of an urgent window.
 582
 583 'focused_frame_opacity'::
 584     Opacity of a focused frame of a focused monitor.
 585
 586 'active_frame_opacity'::
 587     Opacity of a focused frame of an unfocused monitor.
 588
 589 'normal_frame_opacity'::
 590     Opacity of an unfocused frame.
 591
 592 'split_ratio'::
 593     Default split ratio.
 594
 595 'growth_factor'::
 596     Intensity of the growth involved in pulling or pushing an edge.
 597
 598 'history_aware_focus'::
 599     Give priority to the focus history when focusing nodes.
 600
 601 'borderless_monocle'::
 602     Remove borders for tiled windows in monocle mode.
 603
 604 'gapless_monocle'::
 605     Remove gaps for tiled windows in monocle mode.
 606
 607 'focus_follows_pointer'::
 608     Focus the window under the pointer.
 609
 610 'pointer_follows_monitor'::
 611     When focusing a monitor, put the pointer at its center.
 612
 613 'auto_alternate'::
 614     Interpret two consecutive identical *use* messages as an *alternate* message.
 615
 616 'auto_cancel'::
 617     Interpret two consecutive identical *presel* messages as a *cancel* message.
 618
 619 'apply_floating_atom'::
 620     Set the value of the '_BSPWM_FLOATING_WINDOW' atom of each window according to its floating state.
 621
 622 'ignore_ewmh_focus'::
 623     Ignore EWMH requests to focus a window.
 624
 625 Monitor Settings
 626 ~~~~~~~~~~~~~~~~
 627
 628 'top_padding'::
 629 'right_padding'::
 630 'bottom_padding'::
 631 'left_padding'::
 632     Padding space added at the sides of the monitor.
 633
 634 Desktop Settings
 635 ~~~~~~~~~~~~~~~~
 636
 637 'window_gap'::
 638     Size of the gap that separates windows.
 639
 640 'border_width'::
 641     Window border width.
 642
 643
 644 Status Format
 645 -------------
 646
 647 Status informations are composed of items separated by colons.
 648
 649 Each item as the form '<type><value>' where '<type>' is the first character of the item.
 650
 651 'M<monitor_name>'::
 652     Focused monitor.
 653
 654 'm<monitor_name>'::
 655     Unfocused monitor.
 656
 657 'O<desktop_name>'::
 658     Occupied focused desktop.
 659
 660 'o<desktop_name>'::
 661     Occupied unfocused desktop.
 662
 663 'F<desktop_name>'::
 664     Free focused desktop.
 665
 666 'f<desktop_name>'::
 667     Free unfocused desktop.
 668
 669 'U<desktop_name>'::
 670     Urgent focused desktop.
 671
 672 'u<desktop_name>'::
 673     Urgent unfocused desktop.
 674
 675 'L(tiled|monocle)'::
 676     Layout of the focused desktop of the focused monitor.
 677
 678 Environment Variables
 679 ---------------------
 680
 681 'BSPWM_SOCKET'::
 682   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'.
 683
 684 Panels
 685 ------
 686
 687 * Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.).
 688 * A custom panel if the '-s' flag is used (have a look at the files in 'examples/panel').
 689
 690 Key Features
 691 ------------
 692
 693 * Configured and controlled through messages.
 694 * Multiple monitors support (via 'RandR').
 695 * EWMH support (*tint2* works).
 696 * Hybrid tiling.
 697
 698 Contributors
 699 ------------
 700
 701 * Steven Allen <steven at stebalien.com>
 702 * Thomas Adam <thomas at xteddy.org>
 703 * Ivan Kanakarakis <ivan.kanak at gmail.com>
 704
 705 Author
 706 ------
 707
 708 Bastien Dejean <nihilhill at gmail.com>
 709
 710 Mailing List
 711 ------------
 712
 713 bspwm at librelist.com
 714
 715 ////
 716 vim: set ft=asciidoc:
 717 ////