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