README.asciidoc

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