1BSPWM(1) Bspwm Manual BSPWM(1)
2
3
4
6 bspwm - Binary space partitioning window manager
7
9 bspwm [-h|-v|-c CONFIG_PATH]
10
11 bspc DOMAIN [SELECTOR] COMMANDS
12
13 bspc COMMAND [OPTIONS] [ARGUMENTS]
14
16 bspwm is a tiling window manager that represents windows as the leaves
17 of a full binary tree.
18
19 It is controlled and configured via bspc.
20
22 -h
23 Print the synopsis and exit.
24
25 -v
26 Print the version and exit.
27
28 -c CONFIG_PATH
29 Use the given configuration file.
30
32 DIR := north | west | south | east
33 CYCLE_DIR := next | prev
34
36 Selectors are used to select a target node, desktop, or monitor. A
37 selector can either describe the target relatively or name it globally.
38
39 Selectors consist of an optional reference, a descriptor and any number
40 of non-conflicting modifiers as follows:
41
42 [REFERENCE#]DESCRIPTOR(.MODIFIER)*
43
44 The relative targets are computed in relation to the given reference
45 (the default reference value is focused).
46
47 An exclamation mark can be prepended to any modifier in order to
48 reverse its meaning.
49
50 Node
51 Select a node.
52
53 NODE_SEL := [NODE_SEL#](DIR|CYCLE_DIR|PATH|last|older|newer|focused|pointed|biggest|<node_id>)[.[!]focused][.[!]automatic][.[!]local][.[!]active][.[!]leaf][.[!]window][.[!]STATE][.[!]FLAG][.[!]LAYER][.[!]same_class][.[!]descendant_of][.[!]ancestor_of]
54
55 STATE := tiled|pseudo_tiled|floating|fullscreen
56
57 FLAG := hidden|sticky|private|locked|urgent
58
59 LAYER := below|normal|above
60
61 PATH := @[DESKTOP_SEL:][[/]JUMP](/JUMP)*
62
63 JUMP := first|1|second|2|brother|parent|DIR
64
65 Descriptors
66 DIR
67 Selects the window in the given (spacial) direction relative to
68 the reference node.
69
70 CYCLE_DIR
71 Selects the window in the given (cyclic) direction relative to
72 the reference node.
73
74 PATH
75 Selects the node at the given path.
76
77 last
78 Selects the previously focused node relative to the reference
79 node.
80
81 older
82 Selects the node older than the reference node in the history.
83
84 newer
85 Selects the node newer than the reference node in the history.
86
87 focused
88 Selects the currently focused node.
89
90 pointed
91 Selects the window under the pointer.
92
93 biggest
94 Selects the biggest window.
95
96 <node_id>
97 Selects the node with the given ID.
98
99 Path Jumps
100 The initial node is the focused node (or the root if the path
101 starts with /) of the reference desktop (or the selected desktop if
102 the path has a DESKTOP_SEL prefix).
103
104 1|first
105 Jumps to the first child.
106
107 2|second
108 Jumps to the second child.
109
110 brother
111 Jumps to the brother node.
112
113 parent
114 Jumps to the parent node.
115
116 DIR
117 Jumps to the node holding the edge in the given direction.
118
119 Modifiers
120 [!]focused
121 Only consider focused or unfocused nodes.
122
123 [!]automatic
124 Only consider nodes in automatic or manual insertion mode.
125
126 [!]local
127 Only consider nodes in or not in the reference desktop.
128
129 [!]active
130 Only consider nodes in or not in the active desktop of their
131 monitor.
132
133 [!]leaf
134 Only consider leaves or internal nodes.
135
136 [!]window
137 Only consider nodes that hold or don’t hold a window.
138
139 [!](tiled|pseudo_tiled|floating|fullscreen)
140 Only consider windows in or not in the given state.
141
142 [!]same_class
143 Only consider windows that have or don’t have the same class as
144 the reference window.
145
146 [!]descendant_of
147 Only consider nodes that are or aren’t descendants of the
148 reference node.
149
150 [!]ancestor_of
151 Only consider nodes that are or aren’t ancestors of the
152 reference node.
153
154 [!](hidden|sticky|private|locked|urgent)
155 Only consider windows that have or don’t have the given flag
156 set.
157
158 [!](below|normal|above)
159 Only consider windows in or not in the given layer.
160
161 Desktop
162 Select a desktop.
163
164 DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|last|older|newer|[MONITOR_SEL:](focused|^<n>)|<desktop_id>|<desktop_name>)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
165
166 Descriptors
167 CYCLE_DIR
168 Selects the desktop in the given direction relative to the
169 reference desktop.
170
171 last
172 Selects the previously focused desktop relative to the
173 reference desktop.
174
175 older
176 Selects the desktop older than the reference desktop in the
177 history.
178
179 newer
180 Selects the desktop newer than the reference desktop in the
181 history.
182
183 focused
184 Selects the currently focused desktop.
185
186 ^<n>
187 Selects the nth desktop.
188
189 <desktop_id>
190 Selects the desktop with the given ID.
191
192 <desktop_name>
193 Selects the desktop with the given name.
194
195 Modifiers
196 [!]occupied
197 Only consider occupied or free desktops.
198
199 [!]focused
200 Only consider focused or unfocused desktops.
201
202 [!]urgent
203 Only consider urgent or non urgent desktops.
204
205 [!]local
206 Only consider inside or outside of the reference monitor.
207
208 Monitor
209 Select a monitor.
210
211 MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|last|older|newer|focused|primary|^<n>|<monitor_id>|<monitor_name>)[.[!]occupied][.[!]focused]
212
213 Descriptors
214 DIR
215 Selects the monitor in the given (spacial) direction relative
216 to the reference monitor.
217
218 CYCLE_DIR
219 Selects the monitor in the given (cyclic) direction relative to
220 the reference monitor.
221
222 last
223 Selects the previously focused monitor relative to the
224 reference monitor.
225
226 older
227 Selects the monitor older than the reference monitor in the
228 history.
229
230 newer
231 Selects the monitor newer than the reference monitor in the
232 history.
233
234 focused
235 Selects the currently focused monitor.
236
237 primary
238 Selects the primary monitor.
239
240 ^<n>
241 Selects the nth monitor.
242
243 <monitor_id>
244 Selects the monitor with the given ID.
245
246 <monitor_name>
247 Selects the monitor with the given name.
248
249 Modifiers
250 [!]occupied
251 Only consider monitors where the focused desktop is occupied or
252 free.
253
254 [!]focused
255 Only consider focused or unfocused monitors.
256
258 tiled
259 Its size and position are determined by the splitting type and
260 ratio of each node of its path in the window tree.
261
262 pseudo_tiled
263 Has an unrestricted size while being centered in its tiling space.
264
265 floating
266 Can be moved/resized freely. Although it doesn’t occupy any tiling
267 space, it is still part of the window tree.
268
269 fullscreen
270 Fills its monitor rectangle and has no borders. It is send in the
271 ABOVE layer by default.
272
274 hidden
275 Is hidden and doesn’t occupy any tiling space.
276
277 sticky
278 Stays in the focused desktop of its monitor.
279
280 private
281 Tries to keep the same tiling position/size.
282
283 locked
284 Ignores the node --close message.
285
286 urgent
287 Has its urgency hint set. This flag is set externally.
288
290 There’s three stacking layers: BELOW, NORMAL and ABOVE.
291
292 In each layer, the window are orderered as follow: tiled & pseudo-tiled
293 < fullscreen < floating.
294
296 Node
297 General Syntax
298 node [NODE_SEL] COMMANDS
299
300 If NODE_SEL is omitted, focused is assumed.
301
302 Commands
303 -f, --focus [NODE_SEL]
304 Focus the selected or given node.
305
306 -a, --activate [NODE_SEL]
307 Activate the selected or given node.
308
309 -d, --to-desktop DESKTOP_SEL
310 Send the selected node to the given desktop.
311
312 -m, --to-monitor MONITOR_SEL
313 Send the selected node to the given monitor.
314
315 -n, --to-node NODE_SEL
316 Transplant the selected node to the given node.
317
318 -s, --swap NODE_SEL
319 Swap the selected node with the given node.
320
321 -p, --presel-dir [~]DIR|cancel
322 Preselect the splitting area of the selected node (or cancel
323 the preselection). If ~ is prepended to DIR and the current
324 preselection direction matches DIR, then the argument is
325 interpreted as cancel.
326
327 -o, --presel-ratio RATIO
328 Set the splitting ratio of the preselection area.
329
330 -v, --move dx dy
331 Move the selected window by dx pixels horizontally and dy
332 pixels vertically.
333
334 -z, --resize
335 top|left|bottom|right|top_left|top_right|bottom_right|bottom_left
336 dx dy
337 Resize the selected window by moving the given handle by dx
338 pixels horizontally and dy pixels vertically.
339
340 -r, --ratio RATIO|(+|-)PIXELS
341 Set the splitting ratio of the selected node (0 < RATIO < 1).
342
343 -R, --rotate 90|270|180
344 Rotate the tree rooted at the selected node.
345
346 -F, --flip horizontal|vertical
347 Flip the the tree rooted at selected node.
348
349 -E, --equalize
350 Reset the split ratios of the tree rooted at the selected node
351 to their default value.
352
353 -B, --balance
354 Adjust the split ratios of the tree rooted at the selected node
355 so that all windows occupy the same area.
356
357 -C, --circulate forward|backward
358 Circulate the windows of the tree rooted at the selected node.
359
360 -t, --state [~](tiled|pseudo_tiled|floating|fullscreen)
361 Set the state of the selected window. If ~ is present and the
362 current state matches the given state, then the argument is
363 interpreted as the last state.
364
365 -g, --flag hidden|sticky|private|locked[=on|off]
366 Set or toggle the given flag for the selected node.
367
368 -l, --layer below|normal|above
369 Set the stacking layer of the selected window.
370
371 -i, --insert-receptacle
372 Insert a receptacle node at the selected node.
373
374 -c, --close
375 Close the windows rooted at the selected node.
376
377 -k, --kill
378 Kill the windows rooted at the selected node.
379
380 Desktop
381 General Syntax
382 desktop [DESKTOP_SEL] COMMANDS
383
384 If DESKTOP_SEL is omitted, focused is assumed.
385
386 COMMANDS
387 -f, --focus [DESKTOP_SEL]
388 Focus the selected or given desktop.
389
390 -a, --activate [DESKTOP_SEL]
391 Activate the selected or given desktop.
392
393 -m, --to-monitor MONITOR_SEL
394 Send the selected desktop to the given monitor.
395
396 -l, --layout CYCLE_DIR|monocle|tiled
397 Set or cycle the layout of the selected desktop.
398
399 -n, --rename <new_name>
400 Rename the selected desktop.
401
402 -s, --swap DESKTOP_SEL
403 Swap the selected desktop with the given desktop.
404
405 -b, --bubble CYCLE_DIR
406 Bubble the selected desktop in the given direction.
407
408 -r, --remove
409 Remove the selected desktop.
410
411 Monitor
412 General Syntax
413 monitor [MONITOR_SEL] COMMANDS
414
415 If MONITOR_SEL is omitted, focused is assumed.
416
417 Commands
418 -f, --focus [MONITOR_SEL]
419 Focus the selected or given monitor.
420
421 -s, --swap MONITOR_SEL
422 Swap the selected monitor with the given monitor.
423
424 -a, --add-desktops <name>...
425 Create desktops with the given names in the selected monitor.
426
427 -o, --reorder-desktops <name>...
428 Reorder the desktops of the selected monitor to match the given
429 order.
430
431 -d, --reset-desktops <name>...
432 Rename, add or remove desktops depending on whether the number
433 of given names is equal, superior or inferior to the number of
434 existing desktops.
435
436 -g, --rectangle WxH+X+Y
437 Set the rectangle of the selected monitor.
438
439 -n, --rename <new_name>
440 Rename the selected monitor.
441
442 -r, --remove
443 Remove the selected monitor.
444
445 Query
446 General Syntax
447 query COMMANDS [OPTIONS]
448
449 Commands
450 The optional selectors are references.
451
452 -N, --nodes [NODE_SEL]
453 List the IDs of the matching nodes.
454
455 -D, --desktops [DESKTOP_SEL]
456 List the IDs of the matching desktops.
457
458 -M, --monitors [MONITOR_SEL]
459 List the IDs of the matching monitors.
460
461 -T, --tree
462 Print a JSON representation of the matching item.
463
464 Options
465 -m,--monitor [MONITOR_SEL], -d,--desktop [DESKTOP_SEL], -n, --node
466 [NODE_SEL]
467 Constrain matches to the selected monitor, desktop or node. The
468 descriptor can be omitted for -M, -D and -N.
469
470 Wm
471 General Syntax
472 wm COMMANDS
473
474 Commands
475 -d, --dump-state
476 Dump the current world state on standard output.
477
478 -l, --load-state <file_path>
479 Load a world state from the given file.
480
481 -a, --add-monitor <name> WxH+X+Y
482 Add a monitor for the given name and rectangle.
483
484 -o, --adopt-orphans
485 Manage all the unmanaged windows remaining from a previous
486 session.
487
488 -h, --record-history on|off
489 Enable or disable the recording of node focus history.
490
491 -g, --get-status
492 Print the current status information.
493
494 Rule
495 General Syntax
496 rule COMMANDS
497
498 Commands
499 -a, --add (<class_name>|*)[:(<instance_name>|*)] [-o|--one-shot]
500 [monitor=MONITOR_SEL|desktop=DESKTOP_SEL|node=NODE_SEL]
501 [state=STATE] [layer=LAYER] [split_dir=DIR] [split_ratio=RATIO]
502 [(hidden|sticky|private|locked|center|follow|manage|focus|border)=(on|off)]
503 Create a new rule.
504
505 -r, --remove
506 ^<n>|head|tail|(<class_name>|*)[:(<instance_name>|*)]...
507 Remove the given rules.
508
509 -l, --list
510 List the rules.
511
512 Config
513 General Syntax
514 config [-m MONITOR_SEL|-d DESKTOP_SEL|-n NODE_SEL] <key> [<value>]
515 Get or set the value of <key>.
516
517 Subscribe
518 General Syntax
519 subscribe (all|report|monitor|desktop|node|...)*
520 Continuously print status information. See the EVENTS section
521 for the detailed description of each event.
522
523 Quit
524 General Syntax
525 quit [<status>]
526 Quit with an optional exit status.
527
529 If the server can’t handle a message, bspc will return with a non-zero
530 exit code.
531
533 Colors are in the form #RRGGBB, booleans are true, on, false or off.
534
535 All the boolean settings are false by default unless stated otherwise.
536
537 Global Settings
538 normal_border_color
539 Color of the border of an unfocused window.
540
541 active_border_color
542 Color of the border of a focused window of an unfocused monitor.
543
544 focused_border_color
545 Color of the border of a focused window of a focused monitor.
546
547 presel_feedback_color
548 Color of the node --presel-{dir,ratio} message feedback area.
549
550 split_ratio
551 Default split ratio.
552
553 status_prefix
554 Prefix prepended to each of the status lines.
555
556 external_rules_command
557 External command used to retrieve rule consequences. The command
558 will receive the following arguments: window ID, class and instance
559 names, monitor, desktop and node selectors. The output of that
560 command must have the following format: key1=value1 key2=value2 ...
561 (the valid key/value pairs are given in the description of the rule
562 command).
563
564 initial_polarity
565 On which child should a new window be attached when adding a window
566 on a single window tree in automatic mode. Accept the following
567 values: first_child, second_child.
568
569 borderless_monocle
570 Remove borders of tiled windows for the monocle desktop layout.
571
572 gapless_monocle
573 Remove gaps of tiled windows for the monocle desktop layout.
574
575 paddingless_monocle
576 Remove padding space for the monocle desktop layout.
577
578 single_monocle
579 Set the desktop layout to monocle if there’s only one tiled window
580 in the tree.
581
582 pointer_motion_interval
583 The minimum interval, in milliseconds, between two motion notify
584 events.
585
586 pointer_modifier
587 Keyboard modifier used for moving or resizing windows. Accept the
588 following values: shift, control, lock, mod1, mod2, mod3, mod4,
589 mod5.
590
591 pointer_action1, pointer_action2, pointer_action3
592 Action performed when pressing pointer_modifier + button<n>. Accept
593 the following values: move, resize_side, resize_corner, focus,
594 none.
595
596 click_to_focus
597 Focus a window (or a monitor) by clicking it.
598
599 focus_follows_pointer
600 Focus the window under the pointer.
601
602 pointer_follows_focus
603 When focusing a window, put the pointer at its center.
604
605 pointer_follows_monitor
606 When focusing a monitor, put the pointer at its center.
607
608 ignore_ewmh_focus
609 Ignore EWMH focus requests coming from applications.
610
611 center_pseudo_tiled
612 Center pseudo tiled windows into their tiling rectangles. Defaults
613 to true.
614
615 honor_size_hints
616 Apply ICCCM window size hints.
617
618 remove_disabled_monitors
619 Consider disabled monitors as disconnected.
620
621 remove_unplugged_monitors
622 Remove unplugged monitors.
623
624 merge_overlapping_monitors
625 Merge overlapping monitors (the bigger remains).
626
627 Monitor and Desktop Settings
628 top_padding, right_padding, bottom_padding, left_padding
629 Padding space added at the sides of the monitor or desktop.
630
631 Desktop Settings
632 window_gap
633 Size of the gap that separates windows.
634
635 Node Settings
636 border_width
637 Window border width.
638
640 button1
641 Focus the window under the pointer if click_to_focus is set.
642
643 pointer_modifier + button1
644 Move the window under the pointer.
645
646 pointer_modifier + button2
647 Resize the window under the pointer by dragging the nearest side.
648
649 pointer_modifier + button3
650 Resize the window under the pointer by dragging the nearest corner.
651
652 The behavior of pointer_modifier + button<n> can be modified through
653 the pointer_action<n> setting.
654
656 report
657 See the next section for the description of the format.
658
659 monitor_add <monitor_id> <monitor_name> <monitor_geometry>
660 A monitor is added.
661
662 monitor_rename <monitor_id> <old_name> <new_name>
663 A monitor is renamed.
664
665 monitor_remove <monitor_id>
666 A monitor is removed.
667
668 monitor_swap <src_monitor_id> <dst_monitor_id>
669 A monitor is swapped.
670
671 monitor_focus <monitor_id>
672 A monitor is focused.
673
674 monitor_geometry <monitor_id> <monitor_geometry>
675 The geometry of a monitor changed.
676
677 desktop_add <monitor_id> <desktop_id> <desktop_name>
678 A desktop is added.
679
680 desktop_rename <monitor_id> <desktop_id> <old_name> <new_name>
681 A desktop is renamed.
682
683 desktop_remove <monitor_id> <desktop_id>
684 A desktop is removed.
685
686 desktop_swap <src_monitor_id> <src_desktop_id> <dst_monitor_id>
687 <dst_desktop_id>
688 A desktop is swapped.
689
690 desktop_transfer <src_monitor_id> <src_desktop_id> <dst_monitor_id>
691 A desktop is transferred.
692
693 desktop_focus <monitor_id> <desktop_id>
694 A desktop is focused.
695
696 desktop_activate <monitor_id> <desktop_id>
697 A desktop is activated.
698
699 desktop_layout <monitor_id> <desktop_id> tiled|monocle
700 The layout of a desktop changed.
701
702 node_manage <monitor_id> <desktop_id> <node_id> <ip_id>
703 A window is managed.
704
705 node_unmanage <monitor_id> <desktop_id> <node_id>
706 A window is unmanaged.
707
708 node_swap <src_monitor_id> <src_desktop_id> <src_node_id>
709 <dst_monitor_id> <dst_desktop_id> <dst_node_id>
710 A node is swapped.
711
712 node_transfer <src_monitor_id> <src_desktop_id> <src_node_id>
713 <dst_monitor_id> <dst_desktop_id> <dst_node_id>
714 A node is transferred.
715
716 node_focus <monitor_id> <desktop_id> <node_id>
717 A node is focused.
718
719 node_activate <monitor_id> <desktop_id> <node_id>
720 A node is activated.
721
722 node_presel <monitor_id> <desktop_id> <node_id> (dir DIR|ratio
723 RATIO|cancel)
724 A node is preselected.
725
726 node_stack <node_id_1> below|above <node_id_2>
727 A node is stacked below or above another node.
728
729 node_geometry <monitor_id> <desktop_id> <node_id> <node_geometry>
730 The geometry of a window changed.
731
732 node_state <monitor_id> <desktop_id> <node_id>
733 tiled|pseudo_tiled|floating|fullscreen on|off
734 The state of a window changed.
735
736 node_flag <monitor_id> <desktop_id> <node_id>
737 hidden|sticky|private|locked|urgent on|off
738 One of the flags of a node changed.
739
740 node_layer <monitor_id> <desktop_id> <node_id> below|normal|above
741 The layer of a window changed.
742
743 pointer_action <monitor_id> <desktop_id> <node_id>
744 move|resize_corner|resize_side begin|end
745 A pointer action occured.
746
747 Please note that bspwm initializes monitors before it reads messages on
748 its socket, therefore the initial monitor events can’t be received.
749
751 Each report event message is composed of items separated by colons.
752
753 Each item has the form <type><value> where <type> is the first
754 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 T(T|P|F|=|@)
784 State of the focused node of a focused desktop.
785
786 G(S?P?L?)
787 Active flags of the focused node of a focused desktop.
788
790 BSPWM_SOCKET
791 The path of the socket used for the communication between bspc and
792 bspwm. If it isn’t defined, then the following path is used:
793 /tmp/bspwm<host_name>_<display_number>_<screen_number>-socket.
794
796 · Steven Allen <steven at stebalien.com>
797
798 · Thomas Adam <thomas at xteddy.org>
799
800 · Ivan Kanakarakis <ivan.kanak at gmail.com>
801
803 Bastien Dejean <nihilhill at gmail.com>
804
805
806
807Bspwm 0.9.2 10/30/2016 BSPWM(1)