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 Window States
 291 -------------
 292
 293 floating::
 294     Is above any tiled window and can be moved/resized freely. Although it doesn't occupy any tiling space, it is still part of the window tree.
 295
 296 fullscreen::
 297     Fills its monitor rectangle, is above all the other windows and has no borders.
 298
 299 locked::
 300     Ignores the *close* message.
 301
 302 sticky::
 303     Stays in the focused desktop of its monitor.
 304
 305 private::
 306     Tries to keep the same tiling position/size.
 307
 308
 309 Commands
 310 --------
 311
 312 Window
 313 ~~~~~~
 314
 315 General Syntax
 316 ^^^^^^^^^^^^^^
 317
 318 window ['WINDOW_SEL'] 'OPTIONS'
 319
 320 Options
 321 ^^^^^^^
 322 *-f*, *--focus* ['WINDOW_SEL']::
 323     Focus the selected or given window.
 324
 325 *-d*, *--to-desktop* 'DESKTOP_SEL'::
 326     Send the selected window to the given desktop.
 327
 328 *-m*, *--to-monitor* 'MONITOR_SEL'::
 329     Send the selected window to the given monitor.
 330
 331 *-w*, *--to-window* 'WINDOW_SEL'::
 332     Transplant the selected window to the given window.
 333
 334 *-s*, *--swap* 'WINDOW_SEL'::
 335     Swap the selected window with the given window.
 336
 337 *-p*, *--presel* 'DIR'|cancel::
 338     Preselect the splitting area of the selected window (or cancel the preselection).
 339
 340 *-r*, *--ratio* 'RATIO'::
 341     Set the splitting ratio of the selected window (0 < 'RATIO' < 1).
 342
 343 *-e*, *--edge* 'DIR' 'RATIO'|±'PIXELS'|pull|push::
 344     Set and change the splitting ratio of (or pull, or push) the edge located in the given direction in relation to the selected window.
 345
 346 *-R*, *--rotate* 'DIR' '90|270|180'::
 347     Rotate the tree holding the edge located in the given direction in relation to the selected window.
 348
 349 *-t*, *--toggle* floating|fullscreen|locked|sticky|private[=on|off]::
 350     Set or toggle the given state for the selected window.
 351
 352 *-c*, *--close*::
 353     Close the selected window.
 354
 355 *-k*, *--kill*::
 356     Kill the selected window.
 357
 358 Desktop
 359 ~~~~~~~
 360
 361 General Syntax
 362 ^^^^^^^^^^^^^^
 363
 364 desktop ['DESKTOP_SEL'] 'OPTIONS'
 365
 366 Options
 367 ^^^^^^^
 368 *-f*, *--focus* ['DESKTOP_SEL']::
 369     Focus the selected or given desktop.
 370
 371 *-m*, *--to-monitor* 'MONITOR_SEL'::
 372     Send the selected desktop to the given monitor.
 373
 374 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
 375     Set or cycle the layout of the selected desktop.
 376
 377 *-n*, *--rename* <new_name>::
 378     Rename the selected desktop.
 379
 380 *-s*, *--swap* 'DESKTOP_SEL'::
 381     Swap the selected desktop with the given desktop.
 382
 383 *-r*, *--remove*::
 384     Remove the selected desktop.
 385
 386 *-c*, *--cancel-presel*::
 387     Cancel the preselection of all the windows of the selected desktop.
 388
 389 *-F*, *--flip* 'horizontal|vertical'::
 390     Flip the tree of the selected desktop.
 391
 392 *-R*, *--rotate* '90|270|180'::
 393     Rotate the tree of the selected desktop.
 394
 395 *-B*, *--balance*::
 396     Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
 397
 398 *-C*, *--circulate* forward|backward::
 399     Circulate the leaves of the tree of the selected desktop.
 400
 401 *-t*, *--toggle* floating[=on|off]::
 402     Set or toggle the given state for the selected desktop.
 403
 404
 405 Monitor
 406 ~~~~~~~
 407
 408 General Syntax
 409 ^^^^^^^^^^^^^^
 410
 411 monitor ['MONITOR_SEL'] 'OPTIONS'
 412
 413 Options
 414 ^^^^^^^
 415 *-f*, *--focus* ['MONITOR_SEL']::
 416     Focus the selected or given monitor.
 417
 418 *-a*, *--add-desktops* <name>...::
 419     Create desktops with the given names in the selected monitor.
 420
 421 *-r*, *--remove-desktops* <name>...::
 422     Remove desktops with the given names.
 423
 424 *-o*, *--reorder-desktops* <name>...::
 425     Reorder the desktops of the selected monitor to match the given order.
 426
 427 *-d*, *--reset-desktops* <name>...::
 428     Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops.
 429
 430 *-n*, *--rename* <new_name>::
 431     Rename the selected monitor.
 432
 433 *-s*, *--swap* 'MONITOR_SEL'::
 434     Swap the selected monitor with the given monitor.
 435
 436 Query
 437 ~~~~~
 438
 439 General Syntax
 440 ^^^^^^^^^^^^^^
 441
 442 query 'OPTIONS'
 443
 444 Options
 445 ^^^^^^^
 446 *-W*, *--windows*::
 447     List matching windows.
 448
 449 *-D*, *--desktops*::
 450     List matching desktops.
 451
 452 *-M*, *--monitors*::
 453     List matching monitors.
 454
 455 *-T*, *--tree*::
 456     Print tree rooted at query.
 457
 458 *-H*, *--history*::
 459     Print the history as it relates to the query.
 460
 461 *-S*, *--stack*::
 462     Print the window stacking order.
 463
 464 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
 465     Constrain matches to the selected monitor, desktop or window.
 466
 467 Restore
 468 ~~~~~~~
 469
 470 General Syntax
 471 ^^^^^^^^^^^^^^
 472
 473 restore 'OPTIONS'
 474
 475 Options
 476 ^^^^^^^
 477
 478 *-T*, *--tree* <file_path>::
 479     Load the desktop trees from the given file.
 480
 481 *-H*, *--history* <file_path>::
 482     Load the focus history from the given file.
 483
 484 *-S*, *--stack* <file_path>::
 485     Load the window stacking order from the given file.
 486
 487 Control
 488 ~~~~~~~
 489
 490 General Syntax
 491 ^^^^^^^^^^^^^^
 492
 493 control 'OPTIONS'
 494
 495 Options
 496 ^^^^^^^
 497
 498 *--adopt-orphans*::
 499     Manage all the unmanaged windows remaining from a previous session.
 500
 501 *--toggle-visibility*::
 502     Toggle the visibility of all the windows.
 503
 504 *--record-history* on|off::
 505     Enable or disable the recording of window focus history.
 506
 507 *--subscribe*::
 508     Continuously print status informations on standard output.
 509
 510 Pointer
 511 ~~~~~~~
 512
 513 General Syntax
 514 ^^^^^^^^^^^^^^
 515
 516 pointer 'OPTIONS'
 517
 518 Options
 519 ^^^^^^^
 520
 521 *-g*, *--grab* focus|move|resize_side|resize_corner::
 522     Initiate the given pointer action.
 523
 524 *-t*, *--track* <x> <y>::
 525     Pass the pointer root coordinates for the current pointer action.
 526
 527 *-u*, *--ungrab*::
 528     Terminate the current pointer action.
 529
 530 Rule
 531 ~~~~
 532
 533 General Syntax
 534 ^^^^^^^^^^^^^^
 535
 536 rule 'OPTIONS'
 537
 538 Options
 539 ^^^^^^^
 540
 541 *-a*, *--add* <class_name>|<instance_name>|* [*-o*|*--one-shot*] [desktop=DESKTOP_SEL|monitor=MONITOR_SEL] [(floating|fullscreen|locked|sticky|private|center|lower|follow|manage|focus)=(true|false)]::
 542     Create a new rule.
 543
 544 *-r*, *--remove* ^<n>|head|tail|<class_name>|<instance_name>|*...::
 545     Remove the given rules.
 546
 547 *-l*, *--list* [<class_name>|<instance_name>|*]::
 548     List the rules.
 549
 550 Config
 551 ~~~~~~
 552
 553 General Syntax
 554 ^^^^^^^^^^^^^^
 555
 556 config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'] <key> [<value>]::
 557     Get or set the value of <key>.
 558
 559 Quit
 560 ~~~~
 561
 562 General Syntax
 563 ^^^^^^^^^^^^^^
 564
 565 quit [<status>]::
 566     Quit with an optional exit status.
 567
 568 Settings
 569 --------
 570 Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'.
 571
 572 All the boolean settings are 'false' by default.
 573
 574 Global Settings
 575 ~~~~~~~~~~~~~~~
 576
 577 'focused_border_color'::
 578     Color of the border of a focused window of a focused monitor.
 579
 580 'active_border_color'::
 581     Color of the border of a focused window of an unfocused monitor.
 582
 583 'normal_border_color'::
 584     Color of the border of an unfocused window.
 585
 586 'presel_border_color'::
 587     Color of the *presel* message feedback.
 588
 589 'focused_locked_border_color'::
 590     Color of the border of a focused locked window of a focused monitor.
 591
 592 'active_locked_border_color'::
 593     Color of the border of a focused locked window of an unfocused monitor.
 594
 595 'normal_locked_border_color'::
 596     Color of the border of an unfocused locked window.
 597
 598 'focused_sticky_border_color'::
 599     Color of the border of a focused sticky window of a focused monitor.
 600
 601 'active_sticky_border_color'::
 602     Color of the border of a focused sticky window of an unfocused monitor.
 603
 604 'normal_sticky_border_color'::
 605     Color of the border of an unfocused sticky window.
 606
 607 'focused_private_border_color'::
 608     Color of the border of a focused private window of a focused monitor.
 609
 610 'active_private_border_color'::
 611     Color of the border of a focused private window of an unfocused monitor.
 612
 613 'normal_private_border_color'::
 614     Color of the border of an unfocused private window.
 615
 616 'urgent_border_color'::
 617     Color of the border of an urgent window.
 618
 619 'split_ratio'::
 620     Default split ratio.
 621
 622 'growth_factor'::
 623     Intensity of the growth involved in pulling or pushing an edge.
 624
 625 'status_prefix'::
 626     Prefix prepended to each of the status lines.
 627
 628 'external_rules_command'::
 629     External command used to retrieve rule consequences. The command will receive the the ID of the window being processed as its first argument and the class and instance names as second and third arguments. The output of that command must have the following format: *key1=value1 key2=value2 ...* (the valid key/value pairs are given in the description of the 'rule' command).
 630
 631 'history_aware_focus'::
 632     Give priority to the focus history when focusing nodes.
 633
 634 'borderless_monocle'::
 635     Remove borders for tiled windows in monocle mode.
 636
 637 'gapless_monocle'::
 638     Remove gaps for tiled windows in monocle mode.
 639
 640 'focus_follows_pointer'::
 641     Focus the window under the pointer.
 642
 643 'pointer_follows_monitor'::
 644     When focusing a monitor, put the pointer at its center.
 645
 646 'auto_alternate'::
 647     Interpret two consecutive identical *use* messages as an *alternate* message.
 648
 649 'auto_cancel'::
 650     Interpret two consecutive identical *presel* messages as a *cancel* message.
 651
 652 'apply_floating_atom'::
 653     Set the value of the '_BSPWM_FLOATING_WINDOW' atom of each window according to its floating state.
 654
 655 'ignore_ewmh_focus'::
 656     Ignore EWMH requests to focus a window.
 657
 658 'remove_disabled_monitor'::
 659     Consider disabled monitors as disconnected.
 660
 661 Desktop Settings
 662 ~~~~~~~~~~~~~~~~
 663
 664 'window_gap'::
 665     Size of the gap that separates windows.
 666
 667 'top_padding'::
 668 'right_padding'::
 669 'bottom_padding'::
 670 'left_padding'::
 671     Padding space added at the sides of the desktop.
 672
 673 'border_width'::
 674     Window border width.
 675
 676
 677 Status Format
 678 -------------
 679
 680 Status informations are composed of items separated by colons.
 681
 682 Each item has the form '<type><value>' where '<type>' is the first character of the item.
 683
 684 'M<monitor_name>'::
 685     Focused monitor.
 686
 687 'm<monitor_name>'::
 688     Unfocused monitor.
 689
 690 'O<desktop_name>'::
 691     Occupied focused desktop.
 692
 693 'o<desktop_name>'::
 694     Occupied unfocused desktop.
 695
 696 'F<desktop_name>'::
 697     Free focused desktop.
 698
 699 'f<desktop_name>'::
 700     Free unfocused desktop.
 701
 702 'U<desktop_name>'::
 703     Urgent focused desktop.
 704
 705 'u<desktop_name>'::
 706     Urgent unfocused desktop.
 707
 708 'L(tiled|monocle)'::
 709     Layout of the focused desktop of the focused monitor.
 710
 711 Environment Variables
 712 ---------------------
 713
 714 'BSPWM_SOCKET'::
 715   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<display_name>-socket'.
 716
 717 Panels
 718 ------
 719
 720 * Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.).
 721 * A custom panel if the '-s' flag is used (have a look at the files in 'examples/panel').
 722
 723 Key Features
 724 ------------
 725
 726 * Configured and controlled through messages.
 727 * Multiple monitors support (via 'RandR').
 728 * EWMH support (*tint2* works).
 729 * Hybrid tiling.
 730
 731 Contributors
 732 ------------
 733
 734 * Steven Allen <steven at stebalien.com>
 735 * Thomas Adam <thomas at xteddy.org>
 736 * Ivan Kanakarakis <ivan.kanak at gmail.com>
 737
 738 Author
 739 ------
 740
 741 Bastien Dejean <nihilhill at gmail.com>
 742
 743 Mailing List
 744 ------------
 745
 746 bspwm at librelist.com
 747
 748 ////
 749 vim: set ft=asciidoc:
 750 ////