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 - Tiling window manager based on binary space partitioning
  12
  13 Synopsis
  14 --------
  15
  16 *bspwm* [*-h*|*-v*|*-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 *-s* 'PANEL_FIFO'::
  38     Write the internal state to the given FIFO.
  39
  40 *-p* 'PANEL_PREFIX'::
  41     Start every line written to the 'PANEL_FIFO' with the given prefix.
  42
  43
  44 Configuration
  45 -------------
  46
  47 *bspwm* have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
  48
  49 Its configuration file is '$XDG_CONFIG_HOME/bspwm/autostart'.
  50
  51 Keyboard and pointer bindings are defined with https://github.com/baskerville/sxhkd[sxhkd].
  52
  53 Example configuration files can be found in the *examples* directory.
  54
  55 Splitting Modes
  56 ---------------
  57
  58 New windows are inserted in the tree as close as possible to the focused window.
  59
  60 There is only two splitting modes: 'automatic' and 'manual'.
  61
  62 The default mode is 'automatic'. The 'manual' mode is entered by sending a *preselection* message.
  63
  64 Example: insertion of a new node (number 4) into the given tree in 'automatic' mode:
  65
  66 ----
  67               b                                   c
  68              / \                                 / \
  69             3   a              -->              4   b
  70             ^  / \                              ^  / \
  71               2   1                               3   a
  72                                                      / \
  73                                                     2   1
  74  +-------------------------+         +-------------------------+
  75  |            |            |         |            |            |
  76  |            |     2      |         |            |     3      |
  77  |            |            |         |            |            |
  78  |     3      |------------|   -->   |     4      |------------|
  79  |     ^      |            |         |     ^      |     |      |
  80  |            |     1      |         |            |  1  |  2   |
  81  |            |            |         |            |     |      |
  82  +-------------------------+         +-------------------------+
  83 ----
  84
  85 Same departure, but the mode is 'manual', and a *window --presel up* message was sent beforehand:
  86
  87 ----
  88              b                                   b
  89             / \                                 / \
  90            3   a              -->              c   a
  91            ^  / \                             / \ / \
  92              2   1                           4  3 2  1
  93                                              ^
  94 +-------------------------+         +-------------------------+
  95 |            |            |         |            |            |
  96 |            |     2      |         |     4      |     2      |
  97 |            |            |         |     ^      |            |
  98 |     3      |------------|   -->   |------------|------------|
  99 |     ^      |            |         |            |            |
 100 |            |     1      |         |     3      |     1      |
 101 |            |            |         |            |            |
 102 +-------------------------+         +-------------------------+
 103 ----
 104
 105 Containers
 106 ----------
 107
 108 Each monitor contains at least one desktop.
 109
 110 Each desktop contains at most one tree.
 111
 112 Common Definitions
 113 ------------------
 114
 115 ----
 116 DIR         := left | right | up | down
 117 CYCLE_DIR   := next | prev
 118 ----
 119
 120 Selectors
 121 ---------
 122
 123 Selectors are used to select a target window, desktop, or monitor. A selector
 124 can either describe the target relatively or name it globally.
 125
 126 Descriptive (relative) selectors consist of a primary selector and any number
 127 of non-conflicting modifiers as follows:
 128
 129     PRIMARY_SELECTOR[.MODIFIER]*
 130
 131 For obvious reasons, neither desktops nor monitors names may be valid
 132 descriptive selectors.
 133
 134 Window
 135 ~~~~~~
 136
 137 Select a window.
 138
 139 ----
 140 WINDOW_SEL := <window_id>
 141             | (DIR|CYCLE_DIR|biggest|last|focused)[.floating|.tiled][.like|.unlike]
 142 ----
 143
 144 Primary Selectors
 145 ^^^^^^^^^^^^^^^^^
 146
 147 'DIR'::
 148     Selects the window in the given (spacial) direction relative to the active
 149     window.
 150
 151 'CYCLE_DIR'::
 152     Selects the window in the given (cyclic) direction.
 153
 154 biggest::
 155     Selects the biggest window on the current desktop.
 156
 157 last::
 158     Selects the previously focused window on the current desktop.
 159
 160 focused::
 161     Selects the currently focused window.
 162
 163 Modifiers
 164 ^^^^^^^^^
 165
 166 floating::
 167     Only consider floating windows.
 168
 169 tiled::
 170     Only consider tiled windows.
 171
 172 like::
 173     Only consider windows that have the same class as the current window.
 174
 175 unlike::
 176     Only consider windows that have a different class than the current window.
 177
 178 Desktop
 179 ~~~~~~~
 180
 181 Select a desktop.
 182
 183 ----
 184 DESKTOP_SEL := <desktop_name>
 185              | (CYCLE_DIR|last|focused)[.occupied|.free]
 186 ----
 187
 188 Primary Selectors
 189 ^^^^^^^^^^^^^^^^^
 190
 191 'CYCLE_DIR'::
 192     Selects the desktop in the given direction relative to the active desktop.
 193
 194 last::
 195     Selects the previously focused focused desktop.
 196
 197 focused::
 198     Selects the currently focused desktop.
 199
 200 Modifiers
 201 ^^^^^^^^^
 202
 203 occupied::
 204     Only consider occupied desktops.
 205
 206 free::
 207     Only consider free desktops.
 208
 209 Monitor
 210 ~~~~~~~
 211
 212 Select a monitor.
 213
 214 ----
 215 MONITOR_SEL := <monitor_name>
 216              | (DIR|CYCLE_DIR|last|focused)[.occupied|.free]
 217 ----
 218
 219 Primary Selectors
 220 ^^^^^^^^^^^^^^^^^
 221
 222 'DIR'::
 223     Selects the monitor in the given (spacial) direction relative to the active monitor.
 224
 225 'CYCLE_DIR'::
 226     Selects the monitor in the given (cyclic) direction relative to the active monitor.
 227
 228 last::
 229     Selects the previously focused focused monitor.
 230
 231 focused::
 232     Selects the currently focused monitor.
 233
 234 Modifiers
 235 ^^^^^^^^^
 236
 237 occupied::
 238     Only consider monitors where the focused desktop is occupied.
 239
 240 free::
 241     Only consider monitors where the focused desktop is free.
 242
 243
 244 Commands
 245 --------
 246
 247 Window
 248 ~~~~~~
 249
 250 General Syntax
 251 ^^^^^^^^^^^^^^
 252
 253 window ['WINDOW_SEL'] 'OPTIONS'
 254
 255 Options
 256 ^^^^^^^
 257 *-f*, *--focus* ['WINDOW_SEL']::
 258     Focus the selected or given window.
 259
 260 *-d*, *--to-desktop* 'DESKTOP_SEL'::
 261     Send the selected window to the given desktop.
 262
 263 *-m*, *--to-monitor* 'MONITOR_SEL'::
 264     Send the selected window to the given monitor.
 265
 266 *-w*, *--to-window* 'WINDOW_SEL'::
 267     Transplant the selected window to the given window.
 268
 269 *-s*, *--swap* 'WINDOW_SEL'::
 270     Swap the selected window with the given window.
 271
 272 *-p*, *--presel* 'DIR'|cancel::
 273     Preselect the splitting area of the selected window (or cancel the preselection).
 274
 275 *-r*, *--ratio* 'RATIO'::
 276     Set the splitting ratio of the selected window.
 277
 278 *-e*, *--edge* 'DIR' 'RATIO'|pull|push::
 279     Set the splitting ratio (or pull, or push) the edge located in the given direction in relation to the selected window.
 280
 281 *-t*, *--toggle* floating|fullscreen|locked[=on|off]::
 282     Set or toggle the given state for the selected window.
 283
 284 *-c*, *--close*::
 285     Close the selected window.
 286
 287 *-k*, *--kill*::
 288     Kill the selected window.
 289
 290 Desktop
 291 ~~~~~~~
 292
 293 General Syntax
 294 ^^^^^^^^^^^^^^
 295
 296 desktop ['DESKTOP_SEL'] 'OPTIONS'
 297
 298 Options
 299 ^^^^^^^
 300 *-f*, *--focus* ['DESKTOP_SEL']::
 301     Focus the selected or given desktop.
 302
 303 *-m*, *--to-monitor* 'MONITOR_SEL'::
 304     Send the selected desktop to the given monitor.
 305
 306 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
 307     Set or cycle the layout of the selected desktop.
 308
 309 *-n*, *--rename* <new_name>::
 310     Rename the selected desktop.
 311
 312 *-r*, *--remove*::
 313     Remove the selected desktop.
 314
 315 *-c*, *--cancel-presel*::
 316     Cancel the preselection of all the windows of the selected desktop.
 317
 318 *-F*, *--flip* 'horizontal|vertical'::
 319     Flip the tree of the selected desktop.
 320
 321 *-R*, *--rotate* '90|270|180'::
 322     Rotate the tree of the selected desktop.
 323
 324 *-B*, *--balance*::
 325     Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
 326
 327 *-C*, *--circulate* forward|backward::
 328     Circulate the leaves of the tree of the selected desktop.
 329
 330 Monitor
 331 ~~~~~~~
 332
 333 General Syntax
 334 ^^^^^^^^^^^^^^
 335
 336 monitor ['MONITOR_SEL'] 'OPTIONS'
 337
 338 Options
 339 ^^^^^^^
 340 *-f*, *--focus* ['MONITOR_SEL']::
 341     Focus the selected or given monitor.
 342
 343 *-a*, *--add-desktops* <name>...::
 344     Create desktops with the given names in the selected monitor.
 345
 346 *-r*, *--remove-desktops* <name>...::
 347     Remove desktops with the given names.
 348
 349 *-p*, *--pad* <top> <right> <bottom> <left>::
 350     Set the padding of the selected monitor.
 351
 352 *-n*, *--rename* <new_name>::
 353     Rename the selected monitor.
 354
 355 Query
 356 ~~~~~
 357
 358 General Syntax
 359 ^^^^^^^^^^^^^^
 360
 361 query 'OPTIONS'
 362
 363 Options
 364 ^^^^^^^
 365 *-W*, *--windows*::
 366     List matching windows.
 367
 368 *-D*, *--desktops*::
 369     List matching desktops.
 370
 371 *-M*, *--monitors*::
 372     List matching monitors.
 373
 374 *-T*, *--tree*::
 375     Print tree rooted at query.
 376
 377 *-H*, *--history*::
 378     Print the history as it relates to the query.
 379
 380 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
 381     Constrain matches to the selected monitor, desktop or window.
 382
 383 Restore
 384 ~~~~~~~
 385
 386 General Syntax
 387 ^^^^^^^^^^^^^^
 388
 389 restore 'OPTIONS'
 390
 391 Options
 392 ^^^^^^^
 393
 394 *-T*, *--tree* <file_path>::
 395     Load the desktop trees from the given file.
 396
 397 *-H*, *--history* <file_path>::
 398     Load the focus history from the given file.
 399
 400 Control
 401 ~~~~~~~
 402
 403 General Syntax
 404 ^^^^^^^^^^^^^^
 405
 406 control 'OPTIONS'
 407
 408 Options
 409 ^^^^^^^
 410
 411 *--adopt-orphans* <file_path>::
 412    Manage all the unmanaged windows remaining from a previous session.
 413
 414 *--put-status* <file_path>::
 415     Write the current internal state to the panel FIFO.
 416
 417 *--toggle-visibility*::
 418     Toggle the visibility of all the managed windows.
 419
 420 Pointer
 421 ~~~~~~~
 422
 423 General Syntax
 424 ^^^^^^^^^^^^^^
 425
 426 pointer 'OPTIONS'
 427
 428 Options
 429 ^^^^^^^
 430
 431 *-t*, *--track* <x> <y>::
 432     Pass the pointer root coordinates for the current pointer action.
 433
 434 *-g*, *--grab* focus|move|resize_side|resize_corner::
 435     Perform the given pointer action.
 436
 437 Rule
 438 ~~~~
 439
 440 General Syntax
 441 ^^^^^^^^^^^^^^
 442
 443 rule 'OPTIONS'
 444
 445 Options
 446 ^^^^^^^
 447
 448 *-a*, *--add* <pattern> [-d 'DESKTOP_SEL'] [--floating] [--follow]::
 449     Create a new rule (<pattern> must match the class or instance name).
 450
 451 *-r*, *--rm* <rule_uid>...::
 452     Remove the rules with the given UIDs.
 453
 454 *-l*, *--list* [<pattern>]::
 455     List the rules.
 456
 457 Config
 458 ~~~~~~
 459
 460 General Syntax
 461 ^^^^^^^^^^^^^^
 462
 463 config <key> [<value>]::
 464     Get or set the value of <key>.
 465
 466 Quit
 467 ~~~~
 468
 469 General Syntax
 470 ^^^^^^^^^^^^^^
 471
 472 quit [<status>]::
 473     Quit with an optional exit status.
 474
 475 Settings
 476 --------
 477 Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'.
 478
 479 All the boolean settings are 'false' by default.
 480
 481
 482 'focused_border_color'::
 483     Color of the border of a focused window of a focused monitor.
 484
 485 'active_border_color'::
 486     Color of the border of a focused window of an unfocused monitor.
 487
 488 'normal_border_color'::
 489     Color of the border of an unfocused window.
 490
 491 'presel_border_color'::
 492     Color of the *presel* message feedback.
 493
 494 'focused_locked_border_color'::
 495     Color of the border of a focused locked window of a focused monitor.
 496
 497 'active_locked_border_color'::
 498     Color of the border of a focused locked window of an unfocused monitor.
 499
 500 'normal_locked_border_color'::
 501     Color of the border of an unfocused locked window.
 502
 503 'urgent_border_color'::
 504     Color of the border of an urgent window.
 505
 506 'border_width'::
 507     Window border width.
 508
 509 'window_gap'::
 510     Value of the gap that separates windows.
 511
 512 'split_ratio'::
 513     Default split ratio.
 514
 515 'top_padding'::
 516 'right_padding'::
 517 'bottom_padding'::
 518 'left_padding'::
 519     Padding space added at the sides of the current monitor.
 520
 521 'wm_name'::
 522     The value that shall be used for the '_NET_WM_NAME' property of the root window.
 523
 524 'borderless_monocle'::
 525     Remove borders for tiled windows in monocle mode.
 526
 527 'gapless_monocle'::
 528     Remove gaps for tiled windows in monocle mode.
 529
 530 'focus_follows_pointer'::
 531     Focus the window under the pointer.
 532
 533 'pointer_follows_monitor'::
 534     When focusing a monitor, put the pointer at its center.
 535
 536 'monitor_focus_fallback'::
 537     If the focus message fails, try to focus the nearest monitor in the same direction.
 538
 539 'adaptative_raise'::
 540     Prevent floating windows from being raised when they might cover other floating windows.
 541
 542 'apply_shadow_property'::
 543     Enable shadows for floating windows via the '_COMPTON_SHADOW' property.
 544
 545 'auto_alternate'::
 546     Interpret two consecutive identical *use* messages as an *alternate* message.
 547
 548 'auto_cancel'::
 549     Interpret two consecutive identical *presel* messages as a *cancel* message.
 550
 551 'focus_by_distance'::
 552     Use window or leaf distance for focus movement.
 553
 554 'history_aware_focus'::
 555     Give priority to the focus history when focusing nodes.
 556
 557 Environment Variables
 558 ---------------------
 559
 560 'BSPWM_SOCKET'::
 561   The path of the socket used for the communication between *bspc* and *bspwm*.
 562
 563 Panels
 564 ------
 565
 566 * Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.).
 567 * A custom panel if the '-s' flag is used (have a look at the files in 'examples/panel').
 568
 569 Key Features
 570 ------------
 571
 572 * Configured and controlled through messages.
 573 * Multiple monitors support (via 'RandR').
 574 * EWMH support (*tint2* works).
 575 * Hybrid tiling.
 576
 577 Contributors
 578 ------------
 579
 580 * Steven Allen <steven at stebalien.com>
 581 * Thomas Adam <thomas at xteddy.org>
 582 * Ivan Kanakarakis <ivan.kanak at gmail.com>
 583
 584 Author
 585 ------
 586
 587 Bastien Dejean <baskerville at lavabit.com>
 588
 589 Mailing List
 590 ------------
 591
 592 bspwm at librelist.com
 593
 594 ////
 595 vim: set ft=asciidoc:
 596 ////