1BSPWM(1)                         Bspwm Manual                         BSPWM(1)
2
3
4

NAME

6       bspwm - Binary space partitioning window manager
7

SYNOPSIS

9       bspwm [-h|-v|-c CONFIG_PATH]
10
11       bspc DOMAIN [SELECTOR] COMMANDS
12
13       bspc COMMAND [OPTIONS] [ARGUMENTS]
14

DESCRIPTION

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

OPTIONS

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

COMMON DEFINITIONS

32           DIR         := north | west | south | east
33           CYCLE_DIR   := next | prev
34

SELECTORS

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

WINDOW STATES

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

NODE FLAGS

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

STACKING LAYERS

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

DOMAINS

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

EXIT CODES

529       If the server can’t handle a message, bspc will return with a non-zero
530       exit code.
531

SETTINGS

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

POINTER BINDINGS

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

EVENTS

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

REPORT FORMAT

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

ENVIRONMENT VARIABLES

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

CONTRIBUTORS

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

AUTHOR

803       Bastien Dejean <nihilhill at gmail.com>
804
805
806
807Bspwm 0.9.2                       10/30/2016                          BSPWM(1)