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