]> git.lizzy.rs Git - bspwm.git/blob - doc/bspwm.1.asciidoc
1b1bba03f61586affc71ec49581b2938305224cb
[bspwm.git] / doc / bspwm.1.asciidoc
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 Common Definitions
41 ------------------
42
43 ----
44 DIR         := left | right | up | down
45 CYCLE_DIR   := next | prev
46 ----
47
48 Selectors
49 ---------
50
51 Selectors are used to select a target window, desktop, or monitor. A selector
52 can either describe the target relatively or name it globally.
53
54 Descriptive (relative) selectors consist of a primary selector and any number
55 of non-conflicting modifiers as follows:
56
57         PRIMARY_SELECTOR[.MODIFIER]*
58
59 For obvious reasons, neither desktop nor monitor names may be valid descriptive
60 selectors.
61
62 An exclamation mark can be prepended to certain modifiers in order to reverse their meaning.
63
64 Window
65 ~~~~~~
66
67 Select a window.
68
69 ----
70 WINDOW_SEL := (<window_id>|DIR|CYCLE_DIR|biggest|last|focused|older|newer)[.[!]automatic][.[!](tiled|pseudo_tiled|floating|fullscreen)][.[!](below|normal|above)][.[!]local][.[!]same_class][.[!]focused][.[!](urgent|sticky|private|locked)]
71 ----
72
73 Primary Selectors
74 ^^^^^^^^^^^^^^^^^
75
76 'DIR'::
77         Selects the window in the given (spacial) direction relative to the active window.
78
79 'CYCLE_DIR'::
80         Selects the window in the given (cyclic) direction.
81
82 biggest::
83         Selects the biggest window on the current desktop.
84
85 last::
86         Selects the previously focused window.
87
88 focused::
89         Selects the currently focused window.
90
91 older::
92         Selects the window older than the focused window in the history.
93
94 newer::
95         Selects the window newer than the focused window in the history.
96
97 Modifiers
98 ^^^^^^^^^
99
100 [!](tiled|pseudo_tiled|floating|fullscreen)::
101         Only consider windows having or not having the given state.
102
103 [!]automatic::
104         Only consider windows in automatic or manual insertion mode.
105
106 [!]focused::
107         Only consider focused or unfocused windows.
108
109 [!]same_class::
110         Only consider windows that have or don't have the same class as the current window.
111
112 [!]local::
113         Only consider windows in or not in the current desktop.
114
115 [!](private|urgent|sticky|locked)::
116         Only consider windows that have or don't have the given flag set.
117
118 [!](below|normal|above)::
119         Only consider windows in or not in the given layer.
120
121 Desktop
122 ~~~~~~~
123
124 Select a desktop.
125
126 ----
127 DESKTOP_SEL := (<desktop_name>|[MONITOR_SEL:](focused|^<n>)CYCLE_DIR|last|older|newer)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
128 ----
129
130 Primary Selectors
131 ^^^^^^^^^^^^^^^^^
132
133 <desktop_name>::
134         Selects the desktop with the given name.
135
136 ^<n>::
137         Selects the nth desktop.
138
139 'CYCLE_DIR'::
140         Selects the desktop in the given direction relative to the active desktop.
141
142 last::
143         Selects the previously focused desktop.
144
145 focused::
146         Selects the currently focused desktop.
147
148 older::
149         Selects the desktop older than the focused desktop in the history.
150
151 newer::
152         Selects the desktop newer than the focused desktop in the history.
153
154 Modifiers
155 ^^^^^^^^^
156
157 [!]occupied::
158         Only consider occupied or free desktops.
159
160 [!]focused::
161         Only consider focused or unfocused desktops.
162
163 [!]urgent::
164         Only consider urgent or non urgent desktops.
165
166 [!]local::
167         Only consider inside or outside of the current monitor.
168
169 Monitor
170 ~~~~~~~
171
172 Select a monitor.
173
174 ----
175 MONITOR_SEL := (<monitor_name>|^<n>|DIR|CYCLE_DIR|last|primary|focused|older|newer)[.[!]occupied][.[!]focused]
176 ----
177
178 Primary Selectors
179 ^^^^^^^^^^^^^^^^^
180
181 <monitor_name>::
182         Selects the monitor with the given name.
183
184 ^<n>::
185         Selects the nth monitor.
186
187 'DIR'::
188         Selects the monitor in the given (spacial) direction relative to the active monitor.
189
190 'CYCLE_DIR'::
191         Selects the monitor in the given (cyclic) direction relative to the active monitor.
192
193 primary::
194         Selects the primary monitor.
195
196 last::
197         Selects the previously focused monitor.
198
199 focused::
200         Selects the currently focused monitor.
201
202 older::
203         Selects the monitor older than the focused monitor in the history.
204
205 newer::
206         Selects the monitor newer than the focused monitor in the history.
207
208 Modifiers
209 ^^^^^^^^^
210
211 [!]occupied::
212         Only consider monitors where the focused desktop is occupied or free.
213
214 [!]focused::
215         Only consider focused or unfocused monitors.
216
217
218 Window States
219 -------------
220
221 tiled::
222         Its size and position are determined by the splitting type and ratio of each node of its path in the window tree.
223
224 pseudo_tiled::
225         Has an unrestricted size while being centered in its tiling space.
226
227 floating::
228         Can be moved/resized freely. Although it doesn't occupy any tiling space, it is still part of the window tree.
229
230 fullscreen::
231         Fills its monitor rectangle and has no borders. It is send in the ABOVE layer by default.
232
233
234 Window Flags
235 -------------
236
237 locked::
238         Ignores the *window --close* message.
239
240 sticky::
241         Stays in the focused desktop of its monitor.
242
243 private::
244         Tries to keep the same tiling position/size.
245
246 urgent::
247         Has its urgency hint set. This flag is set externally.
248
249
250 Stacking Layers
251 --------------
252
253 There's three stacking layers: BELOW, NORMAL and ABOVE.
254
255 In each layer, the window are orderered as follow: tiled & pseudo-tiled < fullscreen < floating.
256
257
258 Commands
259 --------
260
261 Window
262 ~~~~~~
263
264 General Syntax
265 ^^^^^^^^^^^^^^
266
267 window ['WINDOW_SEL'] 'OPTIONS'
268
269 Options
270 ^^^^^^^
271 *-f*, *--focus* ['WINDOW_SEL']::
272         Focus the selected or given window.
273
274 *-a*, *--activate* ['WINDOW_SEL']::
275         Activate the selected or given window.
276
277 *-d*, *--to-desktop* 'DESKTOP_SEL'::
278         Send the selected window to the given desktop.
279
280 *-m*, *--to-monitor* 'MONITOR_SEL'::
281         Send the selected window to the given monitor.
282
283 *-w*, *--to-window* 'WINDOW_SEL'::
284         Transplant the selected window to the given window.
285
286 *-s*, *--swap* 'WINDOW_SEL'::
287         Swap the selected window with the given window.
288
289 *-p*, *--presel* 'DIR'|cancel::
290         Preselect the splitting area of the selected window (or cancel the preselection).
291
292 *-r*, *--ratio* 'RATIO'::
293         Set the splitting ratio of the selected window (0 < 'RATIO' < 1).
294
295 *-e*, *--edge* 'DIR' 'RATIO'|±'PIXELS'::
296         Set or change the splitting ratio of the edge located in the given direction in relation to the selected window.
297
298 *-R*, *--rotate* 'DIR' '90|270|180'::
299         Rotate the tree holding the edge located in the given direction in relation to the selected window.
300
301 *-t*, *--state* tiled|pseudo_tiled|floating|fullscreen::
302         Set the state of the selected window.
303
304 *-g*, *--flag* locked|sticky|private[=on|off]::
305         Set or toggle the given flag for the selected window.
306
307 *-l*, *--layer* below|normal|above::
308         Set the stacking layer of the selected window.
309
310 *-c*, *--close*::
311         Close the selected window.
312
313 *-k*, *--kill*::
314         Kill the selected window.
315
316 Desktop
317 ~~~~~~~
318
319 General Syntax
320 ^^^^^^^^^^^^^^
321
322 desktop ['DESKTOP_SEL'] 'OPTIONS'
323
324 Options
325 ^^^^^^^
326 *-f*, *--focus* ['DESKTOP_SEL']::
327         Focus the selected or given desktop.
328
329 *-m*, *--to-monitor* 'MONITOR_SEL'::
330         Send the selected desktop to the given monitor.
331
332 *-l*, *--layout* 'CYCLE_DIR'|monocle|tiled::
333         Set or cycle the layout of the selected desktop.
334
335 *-n*, *--rename* <new_name>::
336         Rename the selected desktop.
337
338 *-s*, *--swap* 'DESKTOP_SEL'::
339         Swap the selected desktop with the given desktop.
340
341 *-b*, *--bubble* 'CYCLE_DIR'::
342         Bubble the selected desktop in the given direction.
343
344 *-r*, *--remove*::
345         Remove the selected desktop.
346
347 *-c*, *--cancel-presel*::
348         Cancel the preselection of all the windows of the selected desktop.
349
350 *-F*, *--flip* 'horizontal|vertical'::
351         Flip the tree of the selected desktop.
352
353 *-R*, *--rotate* '90|270|180'::
354         Rotate the tree of the selected desktop.
355
356 *-E*, *--equalize*::
357         Reset the split ratios of the tree of the selected desktop.
358
359 *-B*, *--balance*::
360         Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
361
362 *-C*, *--circulate* forward|backward::
363         Circulate the leaves of the tree of the selected desktop.
364
365
366 Monitor
367 ~~~~~~~
368
369 General Syntax
370 ^^^^^^^^^^^^^^
371
372 monitor ['MONITOR_SEL'] 'OPTIONS'
373
374 Options
375 ^^^^^^^
376 *-f*, *--focus* ['MONITOR_SEL']::
377         Focus the selected or given monitor.
378
379 *-a*, *--add-desktops* <name>...::
380         Create desktops with the given names in the selected monitor.
381
382 *-r*, *--remove-desktops* <name>...::
383         Remove desktops with the given names.
384
385 *-o*, *--reorder-desktops* <name>...::
386         Reorder the desktops of the selected monitor to match the given order.
387
388 *-d*, *--reset-desktops* <name>...::
389         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.
390
391 *-n*, *--rename* <new_name>::
392         Rename the selected monitor.
393
394 *-s*, *--swap* 'MONITOR_SEL'::
395         Swap the selected monitor with the given monitor.
396
397 Query
398 ~~~~~
399
400 General Syntax
401 ^^^^^^^^^^^^^^
402
403 query 'OPTIONS'
404
405 Options
406 ^^^^^^^
407 *-W*, *--windows*::
408         List the IDs of the matching windows.
409
410 *-D*, *--desktops*::
411         List the names of the matching desktops.
412
413 *-M*, *--monitors*::
414         List the names of the matching monitors.
415
416 *-T*, *--tree*::
417         Print a JSON representation of the matching item.
418
419 *-H*, *--history*::
420         Print the focus history as it relates to the query.
421
422 *-S*, *--stack*::
423         Print the window stacking order.
424
425 [*-m*,*--monitor* ['MONITOR_SEL']] | [*-d*,*--desktop* ['DESKTOP_SEL']] | [*-w*, *--window* ['WINDOW_SEL']]::
426         Constrain matches to the selected monitor, desktop or window.
427
428 Restore
429 ~~~~~~~
430
431 General Syntax
432 ^^^^^^^^^^^^^^
433
434 restore 'OPTIONS'
435
436 Options
437 ^^^^^^^
438
439 *-T*, *--tree* <file_path>::
440         Load the desktop trees from the given file.
441
442 *-H*, *--history* <file_path>::
443         Load the focus history from the given file.
444
445 *-S*, *--stack* <file_path>::
446         Load the window stacking order from the given file.
447
448 Control
449 ~~~~~~~
450
451 General Syntax
452 ^^^^^^^^^^^^^^
453
454 control 'OPTIONS'
455
456 Options
457 ^^^^^^^
458
459 *--adopt-orphans*::
460         Manage all the unmanaged windows remaining from a previous session.
461
462 *--toggle-visibility*::
463         Toggle the visibility of all the windows.
464
465 *--record-history* on|off::
466         Enable or disable the recording of window focus history.
467
468 *--subscribe* (all|report|monitor|desktop|window|...)*::
469         Continuously print status information. See the *EVENTS* section for the detailed description of each event.
470
471 *--get-status*::
472         Print the current status information.
473
474 Pointer
475 ~~~~~~~
476
477 General Syntax
478 ^^^^^^^^^^^^^^
479
480 pointer 'OPTIONS'
481
482 Options
483 ^^^^^^^
484
485 *-g*, *--grab* focus|move|resize_side|resize_corner::
486         Initiate the given pointer action.
487
488 *-t*, *--track* <x> <y>::
489         Pass the pointer root coordinates for the current pointer action.
490
491 *-u*, *--ungrab*::
492         Terminate the current pointer action.
493
494 Rule
495 ~~~~
496
497 General Syntax
498 ^^^^^^^^^^^^^^
499
500 rule 'OPTIONS'
501
502 Options
503 ^^^^^^^
504
505 *-a*, *--add* <class_name>|<instance_name>|* [*-o*|*--one-shot*] [monitor=MONITOR_SEL|desktop=DESKTOP_SEL|window=WINDOW_SEL] [state=STATE] [layer=LAYER] [split_dir=DIR] [split_ratio=RATIO] [(locked|sticky|private|center|follow|manage|focus|border)=(on|off)]::
506         Create a new rule.
507
508 *-r*, *--remove* ^<n>|head|tail|<class_name>|<instance_name>|*...::
509         Remove the given rules.
510
511 *-l*, *--list* [<class_name>|<instance_name>|*]::
512         List the rules.
513
514 Config
515 ~~~~~~
516
517 General Syntax
518 ^^^^^^^^^^^^^^
519
520 config [-m 'MONITOR_SEL'|-d 'DESKTOP_SEL'|-w 'WINDOW_SEL'] <key> [<value>]::
521         Get or set the value of <key>.
522
523 Quit
524 ~~~~
525
526 General Syntax
527 ^^^^^^^^^^^^^^
528
529 quit [<status>]::
530         Quit with an optional exit status.
531
532 Exit Codes
533 ----------
534
535 If the server can't handle a message, *bspc* will return with one of the following exit codes:
536
537 1::
538         Failure.
539 2::
540         Syntax error.
541 3::
542         Unknown command.
543
544
545 Settings
546 --------
547 Colors are either '#RRGGBB' or http://en.wikipedia.org/wiki/X11_color_names[X color names], booleans are 'true', 'on', 'false' or 'off'.
548
549 All the boolean settings are 'false' by default unless stated otherwise.
550
551 Global Settings
552 ~~~~~~~~~~~~~~~
553
554 'focused_border_color'::
555         Color of the border of a focused window of a focused monitor.
556
557 'active_border_color'::
558         Color of the border of a focused window of an unfocused monitor.
559
560 'normal_border_color'::
561         Color of the border of an unfocused window.
562
563 'presel_border_color'::
564         Color of the *window --presel* message feedback.
565
566 'focused_locked_border_color'::
567         Color of the border of a focused locked window of a focused monitor.
568
569 'active_locked_border_color'::
570         Color of the border of a focused locked window of an unfocused monitor.
571
572 'normal_locked_border_color'::
573         Color of the border of an unfocused locked window.
574
575 'focused_sticky_border_color'::
576         Color of the border of a focused sticky window of a focused monitor.
577
578 'active_sticky_border_color'::
579         Color of the border of a focused sticky window of an unfocused monitor.
580
581 'normal_sticky_border_color'::
582         Color of the border of an unfocused sticky window.
583
584 'focused_private_border_color'::
585         Color of the border of a focused private window of a focused monitor.
586
587 'active_private_border_color'::
588         Color of the border of a focused private window of an unfocused monitor.
589
590 'normal_private_border_color'::
591         Color of the border of an unfocused private window.
592
593 'urgent_border_color'::
594         Color of the border of an urgent window.
595
596 'split_ratio'::
597         Default split ratio.
598
599 'status_prefix'::
600         Prefix prepended to each of the status lines.
601
602 'external_rules_command'::
603         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).
604
605 'initial_polarity'::
606         On which child should a new window be attached when adding a window on a single window tree in automatic mode. Accept the following values: *first_child*, *second_child*.
607
608 'history_aware_focus'::
609         Give priority to the focus history when focusing nodes.
610
611 'focus_by_distance'::
612         Base focusing on distances between windows.
613
614 'borderless_monocle'::
615         Remove borders of tiled windows for the *monocle* desktop layout.
616
617 'gapless_monocle'::
618         Remove gaps of tiled windows for the *monocle* desktop layout.
619
620 'leaf_monocle'::
621         Set the desktop layout to *monocle* if there's only one tiled window in the tree.
622
623 'focus_follows_pointer'::
624         Focus the window under the pointer.
625
626 'pointer_follows_focus'::
627         When focusing a window, put the pointer at its center.
628
629 'pointer_follows_monitor'::
630         When focusing a monitor, put the pointer at its center.
631
632 'auto_alternate'::
633         Interpret consecutive identical *--focus* arguments as the *last* selector for the *monitor* and *desktop* commands.
634
635 'auto_cancel'::
636         Interpret consecutive identical *--presel* arguments as *--cancel-presel* option.
637
638 'ignore_ewmh_focus'::
639         Ignore EWMH focus requests coming from applications.
640
641 'center_pseudo_tiled'::
642         Center pseudo tiled windows into their tiling rectangles. Defaults to 'true'.
643
644 'remove_disabled_monitors'::
645         Consider disabled monitors as disconnected.
646
647 'remove_unplugged_monitors'::
648         Remove unplugged monitors.
649
650 'merge_overlapping_monitors'::
651         Merge overlapping monitors (the bigger remains).
652
653 Monitor and Desktop Settings
654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
655
656 'top_padding'::
657 'right_padding'::
658 'bottom_padding'::
659 'left_padding'::
660         Padding space added at the sides of the monitor or desktop.
661
662 Default, Desktop Default and Window Settings
663 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
664
665 'border_width'::
666         Window border width.
667
668 Default and Desktop Settings
669 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
670
671 'window_gap'::
672         Size of the gap that separates windows.
673
674
675 Events
676 ------
677
678 'report'::
679         See the next section for the description of the format.
680
681 'monitor_add <monitor_name> <monitor_id> <monitor_geometry>'::
682         A monitor is added.
683
684 'monitor_rename <old_name> <new_name>'::
685         A monitor is renamed.
686
687 'monitor_remove <monitor_name>'::
688         A monitor is removed.
689
690 'monitor_focus <monitor_name>'::
691         A monitor is focused.
692
693 'monitor_geometry <monitor_name> <monitor_geometry>'::
694         The geometry of a monitor changed.
695
696 'desktop_add <monitor_name> <desktop_name>'::
697         A desktop is added.
698
699 'desktop_rename <monitor_name> <old_name> <new_name>'::
700         A desktop is renamed.
701
702 'desktop_remove <monitor_name> <desktop_name>'::
703         A desktop is removed.
704
705 'desktop_swap <src_monitor_name> <src_desktop_name> <dst_monitor_name> <dst_desktop_name>'::
706         A desktop is swapped.
707
708 'desktop_transfer <src_monitor_name> <src_desktop_name> <dst_monitor_name>'::
709         A desktop is transferred.
710
711 'desktop_focus <monitor_name> <desktop_name>'::
712         A desktop is focused.
713
714 'desktop_layout <monitor_name> <desktop_name> tiled|monocle'::
715         The layout of a desktop changed.
716
717 'window_manage <monitor_name> <desktop_name> <window_id> <ip_id>'::
718         A window is managed.
719
720 'window_unmanage <monitor_name> <desktop_name> <window_id>'::
721         A window is unmanaged.
722
723 'window_swap <src_monitor_name> <src_desktop_name> <src_window_id> <dst_monitor_name> <dst_desktop_name> <dst_window_id>'::
724         A window is swapped.
725
726 'window_transfer <src_monitor_name> <src_desktop_name> <src_window_id> <dst_monitor_name> <dst_desktop_name> <dst_window_id>'::
727         A window is transferred.
728
729 'window_focus <monitor_name> <desktop_name> <window_id>'::
730         A window is focused.
731
732 'window_activate <monitor_name> <desktop_name> <window_id>'::
733         A window is activated.
734
735 'window_geometry <monitor_name> <desktop_name> <window_id> <window_geometry>'::
736         The geometry of a window changed.
737
738 'window_state <monitor_name> <desktop_name> <window_id> tiled|pseudo_tiled|floating|fullscreen on|off'::
739         The state of a window changed.
740
741 'window_flag <monitor_name> <desktop_name> <window_id> sticky|private|locked|urgent on|off'::
742         One of the flags of a window changed.
743
744 'window_layer <monitor_name> <desktop_name> <window_id> below|normal|above'::
745         The layer of a window changed.
746
747 Please note that *bspwm* initializes monitors before it reads messages on its socket, therefore the initial monitor events can't be received.
748
749 Report Format
750 -------------
751
752 Each report event message is composed of items separated by colons.
753
754 Each item has the form '<type><value>' where '<type>' is the first character of the item.
755
756 'M<monitor_name>'::
757         Focused monitor.
758
759 'm<monitor_name>'::
760         Unfocused monitor.
761
762 'O<desktop_name>'::
763         Occupied focused desktop.
764
765 'o<desktop_name>'::
766         Occupied unfocused desktop.
767
768 'F<desktop_name>'::
769         Free focused desktop.
770
771 'f<desktop_name>'::
772         Free unfocused desktop.
773
774 'U<desktop_name>'::
775         Urgent focused desktop.
776
777 'u<desktop_name>'::
778         Urgent unfocused desktop.
779
780 'L(T|M)'::
781         Layout of the focused desktop of a monitor.
782
783 Environment Variables
784 ---------------------
785
786 'BSPWM_SOCKET'::
787         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<host_name>_<display_number>_<screen_number>-socket'.
788
789 Contributors
790 ------------
791
792 * Steven Allen <steven at stebalien.com>
793 * Thomas Adam <thomas at xteddy.org>
794 * Ivan Kanakarakis <ivan.kanak at gmail.com>
795
796 Author
797 ------
798
799 Bastien Dejean <nihilhill at gmail.com>