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
 113 Definitions
 114 -----------
 115
 116 ----
 117 WINDOW_SEL     :=  (CYCLE|DIR|biggest|focused|last)[.WINDOW_CLASS] | <window_id>
 118 DESKTOP_SEL    :=  (CYCLE|focused|last)[.DESKTOP_CLASS] | <desktop_name>
 119 MONITOR_SEL    :=  (CYCLE|DIR|focused|last)[.DESKTOP_CLASS] | <monitor_name>
 120
 121 DESKTOP_CLASS  :=  [occupied|free]
 122 WINDOW_CLASS   :=  [floating|tiled][.][like|unlike]
 123
 124 DIR            :=  left|right|up|down
 125 CYCLE          :=  next|prev
 126 ROTATE         :=  90|270|180
 127 FLIP           :=  horizontal|vertical
 128 ----
 129
 130 Commands
 131 --------
 132
 133 Window
 134 ~~~~~~
 135
 136 General Syntax
 137 ^^^^^^^^^^^^^^
 138
 139 window ['WINDOW_SEL'] 'OPTIONS'
 140
 141 Options
 142 ^^^^^^^
 143 *-f*, *--focus* ['WINDOW_SEL']::
 144     Focus the selected or given window.
 145
 146 *-d*, *--to-desktop* 'DESKTOP_SEL'::
 147     Send the selected window to the given desktop.
 148
 149 *-m*, *--to-monitor* 'MONITOR_SEL'::
 150     Send the selected window to the given monitor.
 151
 152 *-w*, *--to-window* 'WINDOW_SEL'::
 153     Transplant the selected window to the given window.
 154
 155 *-s*, *--swap* 'WINDOW_SEL'::
 156     Swap the selected window with the given window.
 157
 158 *-p*, *--presel* 'DIR'|cancel::
 159     Preselect the splitting area of the selected window (or cancel the preselection).
 160
 161 *-r*, *--ratio* 'RATIO'::
 162     Set the splitting ratio of the selected window.
 163
 164 *-e*, *--edge* 'DIR' 'RATIO'|pull|push::
 165     Set the splitting ratio (or pull, or push) the edge located in the given direction in relation to the selected window.
 166
 167 *-t*, *--toggle* floating|fullscreen|locked[=on|off]::
 168     Set or toggle the given state for the selected window.
 169
 170 *-c*, *--close*::
 171     Close the selected window.
 172
 173 *-k*, *--kill*::
 174     Kill the selected window.
 175
 176 Desktop
 177 ~~~~~~~
 178
 179 General Syntax
 180 ^^^^^^^^^^^^^^
 181
 182 desktop ['DESKTOP_SEL'] 'OPTIONS'
 183
 184 Options
 185 ^^^^^^^
 186 *-f*, *--focus* ['DESKTOP_SEL']::
 187     Focus the selected or given desktop.
 188
 189 *-m*, *--to-monitor* 'MONITOR_SEL'::
 190     Send the selected desktop to the given monitor.
 191
 192 *-l*, *--layout* 'CYCLE'|monocle|tiled::
 193     Set or cycle the layout of the selected desktop.
 194
 195 *-n*, *--rename* <new_name>::
 196     Rename the selected desktop.
 197
 198 *-r*, *--remove*::
 199     Remove the selected desktop.
 200
 201 *-c*, *--cancel-presel*::
 202     Cancel the preselection of all the windows of the selected desktop.
 203
 204 *-F*, *--flip* 'FLIP'::
 205     Flip the tree of the selected desktop.
 206
 207 *-R*, *--rotate* 'ROTATE'::
 208     Rotate the tree of the selected desktop.
 209
 210 *-B*, *--balance*::
 211     Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
 212
 213 *-C*, *--circulate* forward|backward::
 214     Circulate the leaves of the tree of the selected desktop.
 215
 216 Monitor
 217 ~~~~~~~
 218
 219 General Syntax
 220 ^^^^^^^^^^^^^^
 221
 222 monitor ['MONITOR_SEL'] 'OPTIONS'
 223
 224 Options
 225 ^^^^^^^
 226 *-f*, *--focus* ['MONITOR_SEL']::
 227     Focus the selected or given monitor.
 228
 229 *-a*, *--add-desktops* <name>...::
 230     Create desktops with the given names in the selected monitor.
 231
 232 *-r*, *--remove-desktops* <name>...::
 233     Remove desktops with the given names.
 234
 235 *-p*, *--pad* <top> <right> <bottom> <left>::
 236     Set the padding of the selected monitor.
 237
 238 *-n*, *--rename* <new_name>::
 239     Rename the selected monitor.
 240
 241 Query
 242 ~~~~~
 243
 244 General Syntax
 245 ^^^^^^^^^^^^^^
 246
 247 query 'OPTIONS'
 248
 249 Options
 250 ^^^^^^^
 251 *-W*, *--windows*::
 252     List matching windows.
 253
 254 *-D*, *--desktops*::
 255     List matching desktops.
 256
 257 *-M*, *--monitors*::
 258     List matching monitors.
 259
 260 *-T*, *--tree*::
 261     Print tree rooted at query.
 262
 263 *-H*, *--history*::
 264     Print the history as it relates to the query.
 265
 266 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
 267     Constrain matches to the selected monitor, desktop or window.
 268
 269 Restore
 270 ~~~~~~~
 271
 272 General Syntax
 273 ^^^^^^^^^^^^^^
 274
 275 restore 'OPTIONS'
 276
 277 Options
 278 ^^^^^^^
 279
 280 *-T*, *--tree* <file_path>::
 281     Load the desktop trees from the given file.
 282
 283 *-H*, *--history* <file_path>::
 284     Load the focus history from the given file.
 285
 286 Control
 287 ~~~~~~~
 288
 289 General Syntax
 290 ^^^^^^^^^^^^^^
 291
 292 control 'OPTIONS'
 293
 294 Options
 295 ^^^^^^^
 296
 297 *--adopt-orphans* <file_path>::
 298    Manage all the unmanaged windows remaining from a previous session.
 299
 300 *--put-status* <file_path>::
 301     Write the current internal state to the panel FIFO.
 302
 303 *--toggle-visibility*::
 304     Toggle the visibility of all the managed windows.
 305
 306 Pointer
 307 ~~~~~~~
 308
 309 General Syntax
 310 ^^^^^^^^^^^^^^
 311
 312 pointer 'OPTIONS'
 313
 314 Options
 315 ^^^^^^^
 316
 317 *-t*, *--track* <x> <y>::
 318     Pass the pointer root coordinates for the current pointer action.
 319
 320 *-g*, *--grab* focus|move|resize_side|resize_corner::
 321     Perform the given pointer action.
 322
 323 Rule
 324 ~~~~
 325
 326 General Syntax
 327 ^^^^^^^^^^^^^^
 328
 329 rule 'OPTIONS'
 330
 331 Options
 332 ^^^^^^^
 333
 334 *-a*, *--add* <pattern> [-d 'DESKTOP_SEL'] [--floating] [--follow]::
 335     Create a new rule (<pattern> must match the class or instance name).
 336
 337 *-r*, *--rm* <rule_uid>...::
 338     Remove the rules with the given UIDs.
 339
 340 *-l*, *--list* [<pattern>]::
 341     List the rules.
 342
 343 Config
 344 ~~~~~~
 345
 346 General Syntax
 347 ^^^^^^^^^^^^^^
 348
 349 config <key> [<value>]::
 350     Get or set the value of <key>.
 351
 352 Quit
 353 ~~~~
 354
 355 General Syntax
 356 ^^^^^^^^^^^^^^
 357
 358 quit [<status>]::
 359     Quit with an optional exit status.
 360
 361 Settings
 362 --------
 363 Colors are either http://en.wikipedia.org/wiki/X11_color_names[X color names] or '#RRGGBB', booleans are 'true' or 'false'.
 364
 365 All the boolean settings are 'false' by default.
 366
 367
 368 'focused_border_color'::
 369     Color of the border of a focused window of a focused monitor.
 370
 371 'active_border_color'::
 372     Color of the border of a focused window of an unfocused monitor.
 373
 374 'normal_border_color'::
 375     Color of the border of an unfocused window.
 376
 377 'presel_border_color'::
 378     Color of the *presel* message feedback.
 379
 380 'focused_locked_border_color'::
 381     Color of the border of a focused locked window of a focused monitor.
 382
 383 'active_locked_border_color'::
 384     Color of the border of a focused locked window of an unfocused monitor.
 385
 386 'normal_locked_border_color'::
 387     Color of the border of an unfocused locked window.
 388
 389 'urgent_border_color'::
 390     Color of the border of an urgent window.
 391
 392 'border_width'::
 393     Window border width.
 394
 395 'window_gap'::
 396     Value of the gap that separates windows.
 397
 398 'split_ratio'::
 399     Default split ratio.
 400
 401 'top_padding'::
 402 'right_padding'::
 403 'bottom_padding'::
 404 'left_padding'::
 405     Padding space added at the sides of the current monitor.
 406
 407 'wm_name'::
 408     The value that shall be used for the '_NET_WM_NAME' property of the root window.
 409
 410 'borderless_monocle'::
 411     Remove borders for tiled windows in monocle mode.
 412
 413 'gapless_monocle'::
 414     Remove gaps for tiled windows in monocle mode.
 415
 416 'focus_follows_pointer'::
 417     Focus the window under the pointer.
 418
 419 'pointer_follows_monitor'::
 420     When focusing a monitor, put the pointer at its center.
 421
 422 'monitor_focus_fallback'::
 423     If the focus message fails, try to focus the nearest monitor in the same direction.
 424
 425 'adaptative_raise'::
 426     Prevent floating windows from being raised when they might cover other floating windows.
 427
 428 'apply_shadow_property'::
 429     Enable shadows for floating windows via the '_COMPTON_SHADOW' property.
 430
 431 'auto_alternate'::
 432     Interpret two consecutive identical *use* messages as an *alternate* message.
 433
 434 'auto_cancel'::
 435     Interpret two consecutive identical *presel* messages as a *cancel* message.
 436
 437 'focus_by_distance'::
 438     Use window or leaf distance for focus movement.
 439
 440 'history_aware_focus'::
 441     Give priority to the focus history when focusing nodes.
 442
 443 Environment Variables
 444 ---------------------
 445
 446 'BSPWM_SOCKET'::
 447   The path of the socket used for the communication between *bspc* and *bspwm*.
 448
 449 Panels
 450 ------
 451
 452 * Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.).
 453 * A custom panel if the '-s' flag is used (have a look at the files in 'examples/panel').
 454
 455 Key Features
 456 ------------
 457
 458 * Configured and controlled through messages.
 459 * Multiple monitors support (via 'RandR').
 460 * EWMH support (*tint2* works).
 461 * Hybrid tiling.
 462
 463 Contributors
 464 ------------
 465
 466 * Steven Allen <steven at stebalien.com>
 467 * Thomas Adam <thomas at xteddy.org>
 468 * Ivan Kanakarakis <ivan.kanak at gmail.com>
 469
 470 Author
 471 ------
 472
 473 Bastien Dejean <baskerville at lavabit.com>
 474
 475 Mailing List
 476 ------------
 477
 478 bspwm at librelist.com
 479
 480 ////
 481 vim: set ft=asciidoc:
 482 ////