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 are 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 action, 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 desktop nor monitor names may be valid descriptive
 128 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|.automatic][.urgent][.local][.unfocused]
 138 ----
 139
 140 Primary Selectors
 141 ^^^^^^^^^^^^^^^^^
 142
 143 'DIR'::
 144         Selects the window in the given (spacial) direction relative to the active window.
 145
 146 'CYCLE_DIR'::
 147         Selects the window in the given (cyclic) direction.
 148
 149 biggest::
 150         Selects the biggest window on the current desktop.
 151
 152 last::
 153         Selects the previously focused window.
 154
 155 focused::
 156         Selects the currently focused window.
 157
 158 older::
 159         Selects the window older than the focused window in the history.
 160
 161 newer::
 162         Selects the window newer than the focused window in the history.
 163
 164 Modifiers
 165 ^^^^^^^^^
 166
 167 floating::
 168         Only consider floating windows.
 169
 170 tiled::
 171         Only consider tiled windows.
 172
 173 like::
 174         Only consider windows that have the same class as the current window.
 175
 176 unlike::
 177         Only consider windows that have a different class than the current window.
 178
 179 manual::
 180         Only consider windows in manual splitting mode.
 181
 182 automatic::
 183         Only consider windows in automatic splitting mode.
 184
 185 local::
 186         Only consider windows of the current desktop.
 187
 188 urgent::
 189         Only consider urgent windows.
 190
 191 unfocused::
 192         Only consider windows other than the focused window.
 193
 194 Desktop
 195 ~~~~~~~
 196
 197 Select a desktop.
 198
 199 ----
 200 DESKTOP_SEL := <desktop_name>
 201              | [MONITOR_SEL:]^<n>
 202              | (CYCLE_DIR|last|[MONITOR_SEL:]focused|older|newer)[.occupied|.free][.urgent][.local]
 203 ----
 204
 205 Primary Selectors
 206 ^^^^^^^^^^^^^^^^^
 207
 208 <desktop_name>::
 209         Selects the desktop with the given name.
 210
 211 ^<n>::
 212         Selects the nth desktop.
 213
 214 'CYCLE_DIR'::
 215         Selects the desktop in the given direction relative to the active desktop.
 216
 217 last::
 218         Selects the previously focused desktop.
 219
 220 focused::
 221         Selects the currently focused desktop.
 222
 223 older::
 224         Selects the desktop older than the focused desktop in the history.
 225
 226 newer::
 227         Selects the desktop newer than the focused desktop in the history.
 228
 229 Modifiers
 230 ^^^^^^^^^
 231
 232 occupied::
 233         Only consider occupied desktops.
 234
 235 free::
 236         Only consider free desktops.
 237
 238 urgent::
 239         Only consider urgent desktops.
 240
 241 local::
 242         Only consider desktops of the current monitor.
 243
 244 Monitor
 245 ~~~~~~~
 246
 247 Select a monitor.
 248
 249 ----
 250 MONITOR_SEL := <monitor_name>
 251              | ^<n>
 252              | (DIR|CYCLE_DIR|last|primary|focused|older|newer)[.occupied|.free]
 253 ----
 254
 255 Primary Selectors
 256 ^^^^^^^^^^^^^^^^^
 257
 258 <monitor_name>::
 259         Selects the monitor with the given name.
 260
 261 ^<n>::
 262         Selects the nth monitor.
 263
 264 'DIR'::
 265         Selects the monitor in the given (spacial) direction relative to the active monitor.
 266
 267 'CYCLE_DIR'::
 268         Selects the monitor in the given (cyclic) direction relative to the active monitor.
 269
 270 primary::
 271         Selects the primary monitor.
 272
 273 last::
 274         Selects the previously focused monitor.
 275
 276 focused::
 277         Selects the currently focused monitor.
 278
 279 older::
 280         Selects the monitor older than the focused monitor in the history.
 281
 282 newer::
 283         Selects the monitor newer than the focused monitor in the history.
 284
 285 Modifiers
 286 ^^^^^^^^^
 287
 288 occupied::
 289         Only consider monitors where the focused desktop is occupied.
 290
 291 free::
 292         Only consider monitors where the focused desktop is free.
 293
 294
 295 Window States
 296 -------------
 297
 298 floating::
 299         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.
 300
 301 pseudo_tiled::
 302         Has an unrestricted size while being centered in its tiling space.
 303
 304 fullscreen::
 305         Fills its monitor rectangle, is above all the other windows and has no borders.
 306
 307 locked::
 308         Ignores the *close* message.
 309
 310 sticky::
 311         Stays in the focused desktop of its monitor.
 312
 313 private::
 314         Tries to keep the same tiling position/size.
 315
 316
 317 Commands
 318 --------
 319
 320 Window
 321 ~~~~~~
 322
 323 General Syntax
 324 ^^^^^^^^^^^^^^
 325
 326 window ['WINDOW_SEL'] 'OPTIONS'
 327
 328 Options
 329 ^^^^^^^
 330 *-f*, *--focus* ['WINDOW_SEL']::
 331         Focus the selected or given window.
 332
 333 *-d*, *--to-desktop* 'DESKTOP_SEL'::
 334         Send the selected window to the given desktop.
 335
 336 *-m*, *--to-monitor* 'MONITOR_SEL'::
 337         Send the selected window to the given monitor.
 338
 339 *-w*, *--to-window* 'WINDOW_SEL'::
 340         Transplant the selected window to the given window.
 341
 342 *-s*, *--swap* 'WINDOW_SEL'::
 343         Swap the selected window with the given window.
 344
 345 *-p*, *--presel* 'DIR'|cancel::
 346         Preselect the splitting area of the selected window (or cancel the preselection).
 347
 348 *-r*, *--ratio* 'RATIO'::
 349         Set the splitting ratio of the selected window (0 < 'RATIO' < 1).
 350
 351 *-e*, *--edge* 'DIR' 'RATIO'|±'PIXELS'::
 352         Set or change the splitting ratio of the edge located in the given direction in relation to the selected window.
 353
 354 *-R*, *--rotate* 'DIR' '90|270|180'::
 355         Rotate the tree holding the edge located in the given direction in relation to the selected window.
 356
 357 *-t*, *--toggle* floating|fullscreen|pseudo_tiled|locked|sticky|private[=on|off]::
 358         Set or toggle the given state for the selected window.
 359
 360 *-c*, *--close*::
 361         Close the selected window.
 362
 363 *-k*, *--kill*::
 364         Kill the selected window.
 365
 366 Desktop
 367 ~~~~~~~
 368
 369 General Syntax
 370 ^^^^^^^^^^^^^^
 371
 372 desktop ['DESKTOP_SEL'] 'OPTIONS'
 373
 374 Options
 375 ^^^^^^^
 376 *-f*, *--focus* ['DESKTOP_SEL']::
 377         Focus the selected or given desktop.
 378
 379 *-m*, *--to-monitor* 'MONITOR_SEL'::
 380         Send the selected desktop to the given monitor.
 381
 382 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
 383         Set or cycle the layout of the selected desktop.
 384
 385 *-n*, *--rename* <new_name>::
 386         Rename the selected desktop.
 387
 388 *-s*, *--swap* 'DESKTOP_SEL'::
 389         Swap the selected desktop with the given desktop.
 390
 391 *-b*, *--bubble* 'CYCLE_DIR'::
 392         Bubble the selected desktop in the given direction.
 393
 394 *-r*, *--remove*::
 395         Remove the selected desktop.
 396
 397 *-c*, *--cancel-presel*::
 398         Cancel the preselection of all the windows of the selected desktop.
 399
 400 *-F*, *--flip* 'horizontal|vertical'::
 401         Flip the tree of the selected desktop.
 402
 403 *-R*, *--rotate* '90|270|180'::
 404         Rotate the tree of the selected desktop.
 405
 406 *-E*, *--equalize*::
 407         Reset the split ratios of the tree of the selected desktop.
 408
 409 *-B*, *--balance*::
 410         Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
 411
 412 *-C*, *--circulate* forward|backward::
 413         Circulate the leaves of the tree of the selected desktop.
 414
 415 *-t*, *--toggle* floating[=on|off]::
 416         Set or toggle the given state for the selected desktop.
 417
 418
 419 Monitor
 420 ~~~~~~~
 421
 422 General Syntax
 423 ^^^^^^^^^^^^^^
 424
 425 monitor ['MONITOR_SEL'] 'OPTIONS'
 426
 427 Options
 428 ^^^^^^^
 429 *-f*, *--focus* ['MONITOR_SEL']::
 430         Focus the selected or given monitor.
 431
 432 *-a*, *--add-desktops* <name>...::
 433         Create desktops with the given names in the selected monitor.
 434
 435 *-r*, *--remove-desktops* <name>...::
 436         Remove desktops with the given names.
 437
 438 *-o*, *--reorder-desktops* <name>...::
 439         Reorder the desktops of the selected monitor to match the given order.
 440
 441 *-d*, *--reset-desktops* <name>...::
 442         Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops. Incidentally reset the settings of the existing desktops.
 443
 444 *-n*, *--rename* <new_name>::
 445         Rename the selected monitor.
 446
 447 *-s*, *--swap* 'MONITOR_SEL'::
 448         Swap the selected monitor with the given monitor.
 449
 450 Query
 451 ~~~~~
 452
 453 General Syntax
 454 ^^^^^^^^^^^^^^
 455
 456 query 'OPTIONS'
 457
 458 Options
 459 ^^^^^^^
 460 *-W*, *--windows*::
 461         List matching windows.
 462
 463 *-D*, *--desktops*::
 464         List matching desktops.
 465
 466 *-M*, *--monitors*::
 467         List matching monitors.
 468
 469 *-T*, *--tree*::
 470         Print tree rooted at query.
 471
 472 *-H*, *--history*::
 473         Print the history as it relates to the query.
 474
 475 *-S*, *--stack*::
 476         Print the window stacking order.
 477
 478 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
 479         Constrain matches to the selected monitor, desktop or window.
 480
 481 Restore
 482 ~~~~~~~
 483
 484 General Syntax
 485 ^^^^^^^^^^^^^^
 486
 487 restore 'OPTIONS'
 488
 489 Options
 490 ^^^^^^^
 491
 492 *-T*, *--tree* <file_path>::
 493         Load the desktop trees from the given file.
 494
 495 *-H*, *--history* <file_path>::
 496         Load the focus history from the given file.
 497
 498 *-S*, *--stack* <file_path>::
 499         Load the window stacking order from the given file.
 500
 501 Control
 502 ~~~~~~~
 503
 504 General Syntax
 505 ^^^^^^^^^^^^^^
 506
 507 control 'OPTIONS'
 508
 509 Options
 510 ^^^^^^^
 511
 512 *--adopt-orphans*::
 513         Manage all the unmanaged windows remaining from a previous session.
 514
 515 *--toggle-visibility*::
 516         Toggle the visibility of all the windows.
 517
 518 *--record-history* on|off::
 519         Enable or disable the recording of window focus history.
 520
 521 *--subscribe* (all|report|monitor|desktop|window|...)*::
 522         Continuously print status information.
 523
 524 *--get-status*::
 525         Print the current status information.
 526
 527 Pointer
 528 ~~~~~~~
 529
 530 General Syntax
 531 ^^^^^^^^^^^^^^
 532
 533 pointer 'OPTIONS'
 534
 535 Options
 536 ^^^^^^^
 537
 538 *-g*, *--grab* focus|move|resize_side|resize_corner::
 539         Initiate the given pointer action.
 540
 541 *-t*, *--track* <x> <y>::
 542         Pass the pointer root coordinates for the current pointer action.
 543
 544 *-u*, *--ungrab*::
 545         Terminate the current pointer action.
 546
 547 Rule
 548 ~~~~
 549
 550 General Syntax
 551 ^^^^^^^^^^^^^^
 552
 553 rule 'OPTIONS'
 554
 555 Options
 556 ^^^^^^^
 557
 558 *-a*, *--add* <class_name>|<instance_name>|* [*-o*|*--one-shot*] [monitor=MONITOR_SEL|desktop=DESKTOP_SEL|window=WINDOW_SEL] [(floating|fullscreen|pseudo_tiled|locked|sticky|private|center|follow|manage|focus|border)=(on|off)] [split_dir=DIR] [split_ratio=RATIO]::
 559         Create a new rule.
 560
 561 *-r*, *--remove* ^<n>|head|tail|<class_name>|<instance_name>|*...::
 562         Remove the given rules.
 563
 564 *-l*, *--list* [<class_name>|<instance_name>|*]::
 565         List the rules.
 566
 567 Config
 568 ~~~~~~
 569
 570 General Syntax
 571 ^^^^^^^^^^^^^^
 572
 573 config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-w 'WINDOW_SEL'] <key> [<value>]::
 574         Get or set the value of <key>.
 575
 576 Quit
 577 ~~~~
 578
 579 General Syntax
 580 ^^^^^^^^^^^^^^
 581
 582 quit [<status>]::
 583         Quit with an optional exit status.
 584
 585 Exit Codes
 586 ----------
 587
 588 If the server can't handle a message, *bspc* will return with one of the following exit codes:
 589
 590 1::
 591         Failure.
 592 2::
 593         Syntax error.
 594 3::
 595         Unknown command.
 596
 597
 598 Settings
 599 --------
 600 Colors are either '#RRGGBB' or http://en.wikipedia.org/wiki/X11_color_names[X color names], booleans are 'true', 'on', 'false' or 'off'.
 601
 602 All the boolean settings are 'false' by default unless stated otherwise.
 603
 604 Global Settings
 605 ~~~~~~~~~~~~~~~
 606
 607 'focused_border_color'::
 608         Color of the border of a focused window of a focused monitor.
 609
 610 'active_border_color'::
 611         Color of the border of a focused window of an unfocused monitor.
 612
 613 'normal_border_color'::
 614         Color of the border of an unfocused window.
 615
 616 'presel_border_color'::
 617         Color of the *presel* message feedback.
 618
 619 'focused_locked_border_color'::
 620         Color of the border of a focused locked window of a focused monitor.
 621
 622 'active_locked_border_color'::
 623         Color of the border of a focused locked window of an unfocused monitor.
 624
 625 'normal_locked_border_color'::
 626         Color of the border of an unfocused locked window.
 627
 628 'focused_sticky_border_color'::
 629         Color of the border of a focused sticky window of a focused monitor.
 630
 631 'active_sticky_border_color'::
 632         Color of the border of a focused sticky window of an unfocused monitor.
 633
 634 'normal_sticky_border_color'::
 635         Color of the border of an unfocused sticky window.
 636
 637 'focused_private_border_color'::
 638         Color of the border of a focused private window of a focused monitor.
 639
 640 'active_private_border_color'::
 641         Color of the border of a focused private window of an unfocused monitor.
 642
 643 'normal_private_border_color'::
 644         Color of the border of an unfocused private window.
 645
 646 'urgent_border_color'::
 647         Color of the border of an urgent window.
 648
 649 'split_ratio'::
 650         Default split ratio.
 651
 652 'status_prefix'::
 653         Prefix prepended to each of the status lines.
 654
 655 'external_rules_command'::
 656         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).
 657
 658 'initial_polarity'::
 659         On which child should a new window be attached when adding a window on a single window tree in automatic mode. Accept the following values: *first_child*, *second_child*.
 660
 661 'history_aware_focus'::
 662         Give priority to the focus history when focusing nodes.
 663
 664 'focus_by_distance'::
 665         Base focusing on distances between windows.
 666
 667 'borderless_monocle'::
 668         Remove borders for tiled windows in monocle mode.
 669
 670 'gapless_monocle'::
 671         Remove gaps for tiled windows in monocle mode.
 672
 673 'focus_follows_pointer'::
 674         Focus the window under the pointer.
 675
 676 'pointer_follows_focus'::
 677         When focusing a window, put the pointer at its center.
 678
 679 'pointer_follows_monitor'::
 680         When focusing a monitor, put the pointer at its center.
 681
 682 'auto_alternate'::
 683         Interpret two consecutive identical *use* messages as an *alternate* message.
 684
 685 'auto_cancel'::
 686         Interpret two consecutive identical *presel* messages as a *cancel* message.
 687
 688 'apply_floating_atom'::
 689         Set the value of the '_BSPWM_FLOATING_WINDOW' atom of each window according to its floating state.
 690
 691 'ignore_ewmh_focus'::
 692         Ignore EWMH focus requests coming from applications.
 693
 694 'center_pseudo_tiled'::
 695         Center pseudo tiled windows into their tiling rectangles. Defaults to 'true'.
 696
 697 'remove_disabled_monitors'::
 698         Consider disabled monitors as disconnected.
 699
 700 'remove_unplugged_monitors'::
 701         Remove unplugged monitors.
 702
 703 'merge_overlapping_monitors'::
 704         Merge overlapping monitors (the bigger remains).
 705
 706 Monitor and Desktop Settings
 707 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 708
 709 'top_padding'::
 710 'right_padding'::
 711 'bottom_padding'::
 712 'left_padding'::
 713         Padding space added at the sides of the monitor or desktop.
 714
 715 Default, Desktop Default and Window Settings
 716 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 717
 718 'border_width'::
 719         Window border width.
 720
 721 Default and Desktop Settings
 722 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 723
 724 'window_gap'::
 725         Size of the gap that separates windows.
 726
 727
 728 Status Format
 729 -------------
 730
 731 Status information is composed of items separated by colons.
 732
 733 Each item has the form '<type><value>' where '<type>' is the first character of the item.
 734
 735 'M<monitor_name>'::
 736         Focused monitor.
 737
 738 'm<monitor_name>'::
 739         Unfocused monitor.
 740
 741 'O<desktop_name>'::
 742         Occupied focused desktop.
 743
 744 'o<desktop_name>'::
 745         Occupied unfocused desktop.
 746
 747 'F<desktop_name>'::
 748         Free focused desktop.
 749
 750 'f<desktop_name>'::
 751         Free unfocused desktop.
 752
 753 'U<desktop_name>'::
 754         Urgent focused desktop.
 755
 756 'u<desktop_name>'::
 757         Urgent unfocused desktop.
 758
 759 'L(T|M)'::
 760         Layout of the focused desktop of a monitor.
 761
 762 Environment Variables
 763 ---------------------
 764
 765 'BSPWM_SOCKET'::
 766         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<host_name>_<display_number>_<screen_number>-socket'.
 767
 768 Panels
 769 ------
 770
 771 * Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.).
 772 * A custom panel (have a look at the files in 'examples/panel').
 773
 774 Key Features
 775 ------------
 776
 777 * Configured and controlled through messages.
 778 * Multiple monitors support.
 779 * EWMH support.
 780 * Hybrid tiling.
 781
 782 Contributors
 783 ------------
 784
 785 * Steven Allen <steven at stebalien.com>
 786 * Thomas Adam <thomas at xteddy.org>
 787 * Ivan Kanakarakis <ivan.kanak at gmail.com>
 788
 789 Author
 790 ------
 791
 792 Bastien Dejean <nihilhill at gmail.com>
 793
 794 Mailing List
 795 ------------
 796
 797 bspwm at librelist.com
 798
 799 ////
 800 vim: set ft=asciidoc:
 801 ////