1HERBSTLUFTWM(1) HERBSTLUFTWM(1)
2
6 herbstluftwm - a manual tiling window manager for X
7
9 herbstluftwm [OPTION ...]
10
12 Starts the herbstluftwm window manager on DISPLAY. It also listens for
13 calls from herbstclient(1) and executes them. The list of available
14 COMMANDS is listed below.
15 OPTION can be:
17 -v, --version
19 print version and exit
20 -h, --help
22 print a short help and exit
23 -c, --autostart PATH
25 use PATH as autostart file instead of the one in $XDG_CONFIG_HOME
26 -l, --locked
28 Initially set the monitors_locked setting to 1
29 --exit-on-xerror
31 Make herbstluftwm exit whenever xlib reports an error. This may
32 only be activated for automated testing and never for actual
33 sessions.
34 --no-tag-import
36 Do not preserve the tags (virtual desktops) from a previous running
37 window manager.
38 --verbose
40 print verbose information to stderr. This can be switched at
41 run-time by the verbose setting.
42 This manual documents the scripting and configuration interface. For a
44 more verbose introduction see herbstluftwm-tutorial(7).
45
47 The basic tiling concept is that the layout is represented by a binary
48 tree. On startup you see one big frame across the entire screen. A
49 frame fulfills exactly one of the following conditions:
50 1. Frame contains windows:
52 It shows some clients and arranges them. The current layout
54 algorithms are:
55 • 0: vertical - clients are placed below each other
57 • 1: horizontal - clients are placed next to each other
59 • 2: max - all clients are maximized in this frame
61 • 3: grid - clients are arranged in an almost quadratic grid
63 2. Frame is split into subframes:
65 It is split into exactly two subframes in a configurable fraction
67 either in a vertical or horizontal way. So it produces two frames
68 which fulfill the same conditions (new frames always are about to
69 contain windows). If you split a frame that already contains
70 windows, the windows are inherited by the first new child frame.
71 If a new window appears, it is put in the currently focused frame. Only
73 the leaves of the frame tree can be focused.
74 A frame can be removed, it is then merged with its neighbour frame. Due
76 to the layout structure of a binary tree, each frame (i.e. node in
77 binary tree) has exactly one neighbour.
78 The analogy to a binary tree is explained the best way with a small
80 example: On startup you have a simple binary tree, with one frame that
81 can contain clients:
82 C
84 When splitting it (e.g. with the command split vertical 0.5) you will
86 get this:
87 V
89 / \
90 C C
91 You also can split the left frame horizontally and you will get:
93 V
95 / \
96 H C
97 / \
98 C C
99 If you change the focus to the client on the right and remove this
101 frame, it will be merged with the left subtree and you will get:
102 H
104 / \
105 C C
106 The layout command prints the current layout of all tags as a tree.
108
110 The exact position of a frame in the layout tree may be described by
111 its index which is just a string of characters. The lookup algorithm
112 starts at the root frame and interprets the index string character by
113 character as follows:
114 • 0: select the first subtree
116 • 1: select the second subtree
118 • .: select the subtree having the focus
120 • /: select the subtree not having the focus
122 • @: select the frame having the focus. In contrast to ., this passes
124 multiple layers all down to the focused leaf of the frame tree.
125 • p: select the parent tree
127 • e: finds a suitable empty frame: if the focused frame is not empty,
129 this selects the closest frame that is empty (in any subtree)
130 For example:
132 • An empty string refers to the root frame
134 • 00 refers to the first subtree of the first subtree of the root
136 frame.
137 • 1e refers to the first empty frame in the second subtree.
139 • /@ refers to the focused frame within the unfocused "half" of the
141 frame tree
142 • @p/ refers to the sibling of the focused frame
144
146 Tags are very similar to workspaces, virtual desktops or window groups.
147 Each tag has one layout. There is a list of tags. You can add or remove
148 tags dynamically.
149
151 Monitors in herbstluftwm are totally independent of the actual physical
152 screens. This means you can for example split your screen in two
153 virtual monitors to view two tags at once on a big screen.
154 Each monitor displays exactly one tag on a specified rectangle on the
156 screen.
157 Each monitor may have a name, which can be set via add_monitor and
159 rename_monitor. It can be unset with the rename_monitor command. A
160 monitor name is an arbitrary non-empty string which must not start with
161 +, - or any digit.
162 A monitor can be referenced in different ways:
164 • by its absolute index as listed in the list_monitors command.
166 • by its relative index: a + or - followed by a delta, e.g.: +3
168 • by its relative position to the focused monitor. -l denotes the
170 monitor left of the focused monitor, -r right of, -u above of, and
171 -d below of, respectively.
172 • by "" (an empty string) which represents the current monitor.
174 • by its name.
176
178 herbstluftwm is controlled by internal commands, which can be executed
179 via herbstclient(1) or via keybindings.
180 quit
182 Quits herbstluftwm.
183 reload
185 Executes the autostart file.
186 version
188 Prints the version of the running herbstluftwm instance.
189 echo [ARGS ...]
191 Prints all given ARGS separated by a single space and a newline
192 afterwards.
193 true
195 Ignores all arguments and always returns success, i.e. 0.
196 false
198 Ignores all arguments and always returns failure, i.e. 1.
199 list_commands
201 Lists all available commands.
202 list_monitors
204 List currently configured monitors with their index, area (as
205 rectangle), name (if named) and currently viewed tag.
206 list_rules
208 Lists all active rules. Each line consists of all the parameters
209 the rule was called with, plus its label, separated by tabs.
210 list_keybinds
212 Lists all bound keys with their associated command. Each line
213 consists of one key combination and the command with its parameters
214 separated by tabs.
215 Warning
217 Tabs within command parameters are not escaped!
218 lock
220 Increases the monitors_locked setting. Use this if you want to do
221 multiple window actions at once (i.e. without repainting between
222 the single steps). See also: unlock
223 unlock
225 Decreases the monitors_locked setting. If monitors_locked is
226 changed to 0, then all monitors are repainted again. See also: lock
227 keybind KEY COMMAND [ARGS ...]
229 Adds a key binding. When KEY is pressed, the internal COMMAND (with
230 its ARGS) is executed. A key binding is a (possibly empty) list of
231 modifiers (Mod1, Mod2, Mod3, Mod4, Mod5, Alt, Super, Control/Ctrl,
232 Shift) and one key (see keysymdef.h for a list of keys). Modifiers
233 and the key are concatenated with - or + as separator. If there is
234 already a binding for this KEY, it will be overwritten. Examples:
235 • keybind Mod4+Ctrl+q quit
237 • keybind Mod1-i toggle always_show_frame
239 • keybind Mod1-Shift-space cycle_layout -1
241 keyunbind KEY|-F|--all
243 Removes the key binding for KEY. The syntax for KEY is defined in
244 keybind. If -F or --all is given, then all key bindings will be
245 removed.
246 mousebind BUTTON ACTION [COMMAND ...]
248 Adds a mouse binding for the floating mode. When BUTTON is pressed,
249 the specified ACTION will be performed. BUTTON has a similar
250 syntax to the KEY argument of keybind: It consists of a list of
251 modifiers (separated by - or +, valid modifiers are listed in the
252 description of keybind) and exactly one button name:
253 • B1 or Button1
255 • B2 or Button2
257 • B3 or Button3
259 • B4 or Button4
261 • B5 or Button5
263 ACTION must be one of the following actions:
265 • move: Moves the window by dragging the cursor.
267 • resize: Resizes the window by dragging a corner.
269 • zoom: Resizes the window into all four directions while keeping
271 the center of the window constant.
272 • call: Only calls the specified COMMAND while client.dragged
274 links to the client on which the BUTTON has been performed.
275 While an ACTION is performed, client.dragged is the client which is
277 dragged. E.g.:
278 • mousebind Mod1-Button3 zoom
280 • mousebind Mod1-B4 call substitute WID clients.dragged.winid
282 spawn transset-df --inc -i WID 0.05
283 • mousebind Mod1-B5 call substitute WID clients.dragged.winid
285 spawn transset-df --dec -i WID -m 0.2 0.05
286 drag WINID ACTION
288 Starts dragging the specified client window WINID with the
289 specified ACTION (see mousebind). E.g. drag '' resize starts
290 resizing the focused window.
291 mouseunbind
293 Removes all mouse bindings.
294 spawn EXECUTABLE [ARGS ...]
296 Spawns an EXECUTABLE with its ARGS. For details see man 3 execvp.
297 Example:
298 • spawn xterm -e man 3 execvp
300 wmexec [WINDOWMANAGER [ARGS ...]]
302 Executes the WINDOWMANAGER with its ARGS. This is useful to switch
303 the window manager in the running session without restarting the
304 session. If no or an invalid WINDOWMANAGER is given, then
305 herbstluftwm is restarted. For details see man 3 execvp. Example:
306 • wmexec openbox
308 chain SEPARATOR [COMMANDS ...]
310 chain expects a SEPARATOR and a list of COMMANDS with arguments.
311 The commands have to be separated by the specified SEPARATOR. The
312 SEPARATOR can by any word and only is recognized as the separator
313 between commands if it exactly matches SEPARATOR. "chain" outputs
314 the appended outputs of all commands and returns the exit code of
315 the last executed command. Examples are:
316 • Create a tag called "foo" and directly use it:
318 chain , add foo , use foo
320 • Rotate the layout clockwise:
322 chain .-. lock .-. rotate .-. rotate .-. rotate .-. unlock
324 Counterexamples are:
326 • This will only create a tag called "foo,":
328 chain , add foo, use foo
330 • Separator "." defined, but "," is used:
332 chain . add foo , use foo
334 and SEPARATOR [COMMANDS ...]
336 "and" behaves like the chain command but only executes the
337 specified COMMANDS while the commands return the exit code 0.
338 or SEPARATOR [COMMANDS ...]
340 "or" behaves like the chain command but only executes the specified
341 COMMANDS until one command returns the exit code 0.
342 ! COMMAND
344 "!" executes the provided command, but inverts its return value. If
345 the provided command returns a nonzero, "!" returns a 0, if the
346 command returns a zero, "!" returns a 1.
347 try COMMAND
349 "try" executes the provided command, prints its output, but always
350 returns success, i.e. 0.
351 silent COMMAND
353 "silent" executes the provided command, but discards its output and
354 only returns its exit code.
355 focus_nth INDEX
357 Focuses the nth window in a frame. The first window has INDEX 0. If
358 INDEX is negative or greater than the last window index, then the
359 last window is focused.
360 cycle [DELTA]
362 Cycles the selection within the current frame by DELTA. If DELTA is
363 omitted, DELTA = 1 will be used. DELTA can be negative; DELTA = -1
364 means: cycle in the opposite direction by 1.
365 cycle_all [--skip-invisible] [DIRECTION]
367 Cycles through all non-minimized windows and frames on the current
368 tag. DIRECTION = 1 means forward (default value), DIRECTION = -1
369 means backward, DIRECTION = 0 has no effect. If there are multiple
370 windows within one frame, then it acts similar to the cycle
371 command. If --skip-invisible is given, then this only cycles
372 through all visible windows and skips invisible windows in the max
373 layout (the flag only affects invisible windows in the max layout;
374 minimized windows are always skipped). After each focus change, the
375 focused window is raised.
376 cycle_frame [DIRECTION]
378 Cycles through all frames on the current tag. DIRECTION = 1 means
379 forward, DIRECTION = -1 means backward, DIRECTION = 0 has no
380 effect. DIRECTION defaults to 1.
381 cycle_layout [DELTA [LAYOUTS ...]]
383 Cycles the layout algorithm in the current frame by DELTA. DELTA
384 defaults to 1. You can find a list of layout algorithms above. If a
385 list of LAYOUTS is given, cycle_layout will cycle through those
386 instead of the default layout algorithm list. This is done by
387 finding the first occurrence of the current layout in LAYOUTS and
388 picking the next layout according to DELTA. If the current layout
389 doesn’t occur in LAYOUTS, the first entry is picked. Example:
390 • cycle_layout -1
392 • cycle_layout 1 vertical grid
394 set_layout LAYOUT
396 Sets the layout algorithm in the current frame to LAYOUT. For the
397 list of layouts, check the list of layout algorithms above.
398 close WINID
400 Closes the specified window gracefully or the focused window if
401 none is given explicitly. See the section on WINDOW IDS how to
402 reference a certain window.
403 close_or_remove
405 Closes the focused window or removes the current frame if no window
406 is focused. In floating mode, this acts as the close command.
407 close_and_remove
409 Closes the focused window and removes the current frame if no other
410 window is present in that frame. In floating mode, this acts as the
411 close command.
412 split ALIGN [FRACTION [FRAMEINDEX]
414 Splits the focused frame (or the frame specified by FRAMEINDEX, see
415 the section frame index) into two subframes with a specified
416 FRACTION between 0 and 1 which defaults to 0.5. ALIGN is one of
417 • top
420 • bottom (= vertical)
422 • left,
424 • right (= horizontal)
426 • explode
428 • auto (split along longest side)
430 It specifies which of the two halves will be empty after the
432 split. The other half will be occupied by the currently focused
433 frame. After splitting, the originally focused frame will stay
434 focused. One special ALIGN mode is explode, which splits the
435 frame in such a way that the window sizes and positions are
436 kept as much as possible. If no FRACTION is given to explode
437 mode an optimal fraction is picked automatically. Example:
438 • split explode
440 • split bottom 0.5
442 • split horiz 0.3
444 • split vertical 0.5
446 • split h
448 • split top 0.2 '' (splits the root frame)
450 focus [-i|-e] DIRECTION
452 Moves the focus from current frame to the next frame or client in
453 DIRECTION which is in:
454 • l[eft]
457 • r[ight]
459 • u[p]
461 • d[own]
463 If -i (internal) is given or default_direction_external_only is
465 unset, then the next client in DIRECTION can also be within the
466 same frame. If there is no client within this frame or -e
467 (external) is given, then the next frame in specified DIRECTION
468 will be focused.
469 The direction between frames is defined as follows: The focus is in
472 a leaf of the binary tree. Each inner node in the tree remembers
473 the last focus direction (child 0 or child 1). The algorithm uses
474 the shortest possible way from the leaf (the currently focused
475 frame) to the root until it is possible to change focus in the
476 specified DIRECTION. From there the focus goes back to the leaf.
477 Example: The focus is at frame A. After executing focus right focus
480 will be at frame C.
481 Tree: H,0 Screen: ┌─────┐┌─────┐ (before)
483 ╱ ╲ │ B ││ C │
484 ╱ ╲ └─────┘└─────┘
485 V,1 V,0 ┌─────┐┌─────┐
486 ╱ ╲ ╱ ╲ │ A* ││ D │
487 B A* C D └─────┘└─────┘
488 Tree: H,1 Screen: ┌─────┐┌─────┐ (after focus right)
490 ╱ ╲ │ B ││ C* │
491 ╱ ╲ └─────┘└─────┘
492 V,1 V,0 ┌─────┐┌─────┐
493 ╱ ╲ ╱ ╲ │ A ││ D │
494 B A C* D └─────┘└─────┘
495 If the currently focused client is floated, then the next floating
497 window in the specified direction is focused and raised.
498 If focus_crosses_monitor_boundaries is set and no client or frame
500 is found in the specified DIRECTION, then the next monitor in that
501 DIRECTION is focused.
502 focus_edge [-i|-e] DIRECTION
504 Focuses the window on the edge of the tag in the specified
505 DIRECTION. The DIRECTIONS and -e behave as specified at the focus
506 command.
507 If -i (internal) is given or default_direction_external_only is
510 unset, then the window on the edge of the tag will be focused.
511 Else, only the frame on the edge of the tag will be focused, and
512 the window that was last focused in that frame will be focused.
513 raise WINID
515 Raises the specified window. See the section on WINDOW IDS on how
516 to reference a certain window. Its result is only visible in
517 floating mode.
518 Tip
520 The WINID also can specify an unmanaged window, although the
521 completion for the raise command does not list the IDs of unmanaged
522 windows.
523 jumpto WINID
525 Puts the focus to the specified window. See the section on WINDOW
526 IDS on how to reference a certain window.
527 bring WINID
529 Moves the specified window to the current frame and focuses it.
530 Floating windows are brought to the current tag, but keep their
531 floating state. See the section on WINDOW IDS on how to reference a
532 certain window.
533 resize DIRECTION [FRACTIONDELTA]
535 Changes the size of the focused frame in the specified DIRECTION by
536 FRACTIONDELTA (which defaults to 0.02 if none is supplied).
537 DIRECTION behaves as specified at the focus command. If a floating
538 window is focused, it grows towards next edge, i.e. either the edge
539 of the next window or the monitor edge in the specified DIRECTION
540 (FRACTIONDELTA is ignored in that case). Example:
541 • resize right +0.05
543 • resize down -0.1
545 shift_edge [-i|-e] DIRECTION
547 Shifts the focused window to the the edge of a tag in the specified
548 DIRECTION. The DIRECTIONS behave as specified at the focus command
549 and -i and -e behave as specified at the focus_edge command.
550 shift [-i|-e] DIRECTION
552 Shifts the focused window to the next frame in the specified
553 DIRECTION. The DIRECTIONS and -i|-e behave as specified at the
554 focus command. If the focused client is floated instead of being
555 tiled, then client is shifted to the next window or screen edge.
556 shift_to_monitor MONITOR
558 Moves the focused window to the tag on the specified MONITOR. See
559 the MONITORS section, how to address a monitor.
560 remove
562 Removes focused frame and merges its windows to its closest
563 neighbour frame.
564 rotate
566 Rotates the layout on the focused tag counterclockwise by 90
567 degrees. This only manipulates the alignment of frames, not the
568 content of them.
569 mirror [vertical|horizontal|both]
571 Mirrors the layout on the focused tag vertically, horizontally, or
572 both; the default is horizontal. This command only manipulates the
573 alignment of frames, not the content of them.
574 set NAME VALUE
576 Sets the specified setting NAME to VALUE. Allowed values for
577 boolean settings are on or true for on, off or false for off,
578 toggle to toggle its value. All SETTINGS are listed in the section
579 below.
580 get NAME
582 Prints the value of setting NAME. All SETTINGS are listed in the
583 section below.
584 toggle NAME
586 Toggles the setting NAME if it’s a boolean setting.
587 cycle_value NAME VALUES ...
589 Cycles value of the setting NAME through VALUES: I.e. it searches
590 the first occurrence of the current value in VALUES and changes the
591 value to the next in the list or to the first one if the end is
592 reached or current value wasn’t found. Example:
593 • cycle_value frame_gap 0 5 10 15
595 • cycle_value frame_bg_normal_color red green blue
597 cycle_monitor [DELTA]
599 Cycles monitor focused by DELTA. DELTA defaults to 1.
600 focus_monitor MONITOR
602 Puts focus to the specified monitor. See the MONITORS section, how
603 to address a monitor.
604 add TAG
606 Creates a new empty tag named TAG.
607 use TAG
609 Switches the focused monitor to specified TAG.
610 use_index INDEX [--skip-visible]
612 Switches the focused monitor to the TAG with the specified INDEX.
613 If INDEX starts with + or -, then INDEX is treated relative to the
614 current TAG. If --skip-visible is passed and INDEX is relative,
615 then tags that are already visible on a monitor are skipped. E.g.
616 this cycles backwards through the tags:
617 • use_index -1 --skip-visible
619 use_previous
621 Switches the focused monitor to the previously viewed tag.
622 merge_tag TAG [TARGET]
624 Removes tag named TAG and moves all its windows to tag TARGET. If
625 TARGET is omitted, the focused tag will be used.
626 rename OLDTAG NEWTAG
628 Renames tag named OLDTAG to NEWTAG.
629 move TAG
631 Moves the focused window to the tag named TAG.
632 move_index INDEX [--skip-visible]
634 Moves the focused window to the tag specified by INDEX. Analogical
635 to the argument for use_index: If INDEX starts with + or -, then it
636 is treated relative. If --skip-visible is passed with a relative
637 index, then already visible tags are skipped.
638 lock_tag [MONITOR]
640 Lock the tag switching on the specified monitor. If no argument is
641 given, the currently focused monitor is used. When the tag
642 switching is disabled for a monitor, the commands use and use_index
643 have no effect when executed there. When swap_monitors_to_get_tag
644 is enabled, switching to a tag which is located on a locked
645 monitor, switches to that monitor instead of stealing it from
646 there. The lock state of a monitor is indicated by "[LOCKED]" in
647 the list_monitors output.
648 unlock_tag [MONITOR]
650 Re-enables the tag switching on the specified monitor. If no
651 argument is given, the currently focused monitor is used. This is
652 the reverse operation to lock_tag and has no further side effects
653 but removing this lock.
654 disjoin_rects RECTS ...
656 Takes a list of rectangles and splits them into smaller pieces
657 until all rectangles are disjoint, the result rectangles are
658 printed line by line. This command does not modify the current list
659 of monitors! So this can be useful in combination with the
660 set_monitors command.
661 • E.g. disjoin_rects 600x400+0+0 600x400+300+250 prints this:
663 300x150+300+250
665 600x250+0+0
666 300x150+0+250
667 300x150+600+250
668 600x250+300+400
669 • In the above example two monitors are split into 5 monitors,
671 which graphically means:
672 ┌──────┐ ┌──────┐
674 │ │ └──────┘
675 │ ┌───┼───┐ ┌─┐┌───┐┌──┐
676 │ │ │ │ disjoin │ ││ ││ │
677 └──┼───┘ │ ─────────> └─┘└───┘└──┘
678 │ │ ┌───────┐
679 └───────┘ └───────┘
680 set_monitors RECTS ...
682 Sets the list of monitors exactly to the list of given rectangles:
683 • The i’th existing monitor is moved to the i’th given RECT
685 • New monitors are created if there are more RECTS than monitors
687 • Existing monitors are deleted if there are more monitors than
689 RECTS
690 detect_monitors -l|--list|--list-all|--no-disjoin
692 Sets the list of monitors to the physically available monitors. If
693 both Xinerama and xrandr are missing, it will fall back to one
694 monitor across the entire screen. If the detected monitors overlap,
695 the will be split into more monitors that are disjoint but cover
696 the same area using disjoin_rects.
697 If -l or --list is passed, the list of rectangles of detected
699 physical monitors is printed. So hc detect_monitors is equivalent
700 to the bash command hc set_monitors $(hc disjoin_rects $(hc
701 detect_monitors -l)).
702 If --list-all is passed, then it is printed which multimonitor
704 detection (xinerama, xrandr) has which set of physical monitors.
705 add_monitor RECT [TAG [NAME]]
707 Adds a monitor on the specified rectangle RECT and displays TAG on
708 it. TAG currently must not be displayed on any other monitor.
709 RECT is a string of the form WxH±X±Y. If no or an empty TAG is
710 given, then any free tag will be chosen. If a NAME is given, you
711 can reference to this monitor by its name instead of using an
712 index. Example:
713 • add_monitor 1024x768-20+0 mynewtag main
715 remove_monitor MONITOR
717 Removes the specified monitor.
718 move_monitor MONITOR RECT [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
720 Moves the specified monitor to rectangle RECT. RECT is defined as
721 in add_monitor. If no or an empty pad is given, it is not changed.
722 raise_monitor [MONITOR]
724 Raises the specified monitor or the current one if MONITOR is
725 omitted.
726 rename_monitor MONITOR NAME
728 (Re)names an already existing monitor. If NAME is empty, it removes
729 the monitor’s name.
730 stack
732 Prints the stack of monitors with the visible tags and their layers
733 as a tree. The order of the printed stack is top to bottom. The
734 style is configured by the tree_style setting.
735 monitor_rect [[-p] MONITOR]
737 Prints the rectangle of the specified monitor in the format: X Y W
738 H If no MONITOR or cur is given, then the current monitor is used.
739 If -p is supplied, then the remaining rect without the pad around
740 this monitor is printed.
741 pad MONITOR [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
743 Sets the pad of specified monitor to the specified padding. If no
744 or an empty padding is given, it is not changed.
745 list_padding [MONITOR]
747 Lists the padding of the specified monitor, or the currently
748 focused monitor if no monitor is given.
749 layout [TAG [INDEX]]
751 Prints the layout of frame with INDEX on TAG, in a nice tree style.
752 Its style is defined by the tree_style setting. If no TAG is given,
753 the current tag is used. If no INDEX is given, the root frame is
754 used. To specify INDEX without specifying TAG (i.e. use current
755 tag), pass an empty string as TAG.
756 An example output is:
758 ╾─┐ horizontal 50% selection=1
760 ├─╼ vertical: 0xe00009
761 └─┐ vertical 50% selection=0
762 ├─╼ vertical: 0xa00009 [FOCUS]
763 └─╼ vertical: 0x1000009
764 dump [TAG [INDEX]]
766 Prints the same information as the layout command but in a machine
767 readable format. Its output can be read back with the load command.
768 An example output (formatted afterwards) is:
770 (split horizontal:0.500000:1
772 (clients vertical:0 0xe00009)
773 (split vertical:0.500000:1
774 (clients vertical:0 0xa00009)
775 (clients vertical:0 0x1000009)))
776 load [TAG] LAYOUT
778 Loads a given LAYOUT description to specified TAG or current tag if
779 no TAG is given.
780 Caution
782 LAYOUT is exactly one parameter. If you are calling it manually
783 from your shell or from a script, quote it properly!
784 complete POSITION [COMMAND ARGS ...]
786 Prints the result of tab completion for the partial COMMAND with
787 optional ARGS. You usually do not need this, because there is
788 already tab completion for bash, zsh and fish. Example:
789 • complete 0 m
791 prints all commands beginning with m
793 • complete 1 toggle fra
795 prints all settings beginning with fra that can be toggled
797 complete_shell POSITION [COMMAND ARGS ...]
799 Behaves like complete with the following extras, useful for
800 completion on posix shells:
801 • Escape sequences are removed in COMMAND and ARGS.
803 • A space is appended to each full completion result.
805 • Special characters will be escaped in the output.
807 emit_hook NAME ARGS ...
809 Emits a custom hook NAME to all idling herbstclients.
810 tag_status [MONITOR]
812 Print a tab separated list of all tags for the specified MONITOR
813 index. If no MONITOR index is given, the focused monitor is used.
814 Each tag name is prefixed with one char, which indicates its state:
815 • . the tag is empty
817 • : the tag is not empty
819 • + the tag is viewed on the specified MONITOR, but this monitor
821 is not focused.
822 • # the tag is viewed on the specified MONITOR and it is focused.
824 • - the tag is viewed on a different MONITOR, but this monitor is
826 not focused.
827 • % the tag is viewed on a different MONITOR and it is focused.
829 • ! the tag contains an urgent window
831 Warning
833 If you use a tab in one of the tag names, then tag_status is
834 probably quite useless for you.
835 floating [[TAG] on|off|toggle|status]
837 Changes specified TAG to floating/tiling mode or prints its current
838 status. If no TAG is given, the current tag is used. If no argument
839 is given, floating mode is toggled. If status is given, then on or
840 off is printed, depending of the floating state of TAG.
841 rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
843 Defines a rule which will be applied to all new clients. Its
844 behaviour is described in the RULES section.
845 unrule LABEL|--all|-F
847 Removes all rules named LABEL. If --all or -F is passed, then all
848 rules are removed.
849 apply_rules WINID|--all
851 Apply the rules to the specified window WINID. If --all is passed,
852 then the rules are applied to all clients.
853 apply_tmp_rule WINID|--all [RULEDESCRIPTION...]
855 Apply the rule RULEDESCRIPTION to one particular client WINID or
856 all clients (--all) without adding the rule to the rule list. The
857 RULEDESCRIPTION specifies a rule consisting of conditions and
858 consequences as one would pass it to the rule command as described
859 in the RULES section. This allows testing rules before adding them.
860 Running apply_tmp_rule only applies the particular rule given in
861 the arguments and ignores the existing rules.
862 fullscreen [on|off|toggle]
864 Sets or toggles the fullscreen state of the focused client. If no
865 argument is given, fullscreen mode is toggled.
866 pseudotile [on|off|toggle]
868 Sets or toggles the pseudotile state of the focused client. If a
869 client is pseudotiled, then in tiling mode the client is only moved
870 but not resized - the client size will stay the floating size. The
871 only reason to resize the client is to ensure that it fits into its
872 tile. If no argument is given, pseudotile mode is toggled.
873 object_tree [PATH]
875 Prints the tree of objects. If the object path PATH is given, only
876 the subtree starting at PATH is printed. See the OBJECTS section
877 for more details.
878 attr [PATH [NEWVALUE]
880 Prints the children and attributes of the given object addressed by
881 PATH. If PATH is an attribute, then print the attribute value. If
882 NEWVALUE is given, assign NEWVALUE to the attribute given by PATH.
883 See the OBJECTS section for more details.
884 get_attr ATTRIBUTE
886 Print the value of the specified ATTRIBUTE as described in the
887 OBJECTS section.
888 set_attr ATTRIBUTE NEWVALUE
890 Assign NEWVALUE to the specified ATTRIBUTE as described in the
891 OBJECTS section.
892 new_attr bool|color|int|string|uint PATH [VALUE]
894 Creates a new attribute with the name and in the object specified
895 by PATH. Its type is specified by the first argument. The attribute
896 name has to begin with my_. If VALUE is supplied, then it is
897 written to the attribute (if this fails the attribute still
898 remains).
899 remove_attr PATH
901 Removes the user defined attribute PATH.
902 substitute IDENTIFIER ATTRIBUTE COMMAND [ARGS ...]
904 Replaces all exact occurrences of IDENTIFIER in COMMAND and its
905 ARGS by the value of the ATTRIBUTE. Note that the COMMAND also is
906 replaced by the attribute value if it equals IDENTIFIER. The
907 replaced command with its arguments then is executed. Example:
908 • substitute MYTITLE clients.focus.title echo MYTITLE
910 Prints the title of the currently focused window.
912 sprintf IDENTIFIER FORMAT [FORMATARG ...] COMMAND [CMDARGS ...]
914 Replaces all exact occurrences of IDENTIFIER in COMMAND and its
915 CMDARGS by the string specified by FORMAT. The FORMAT string may
916 contain several placeholders, similar to the printf(1) command:
917 • %s inserts an attribute value whose path is given by the string
919 value of the next FORMATARG
920 • %c ("constant") inserts the next FORMATARG without
922 modification.
923 • %% stands for a plain %
925 The replaced command with its arguments then is executed. Examples:
927 • sprintf STR title=%s clients.focus.title echo STR
929 Prints the title of the currently focused window prepended by
931 title=.
932 • sprintf X "%c %s tags" "there are" tags.count echo X
934 Prints there are N tags with N replaced by the number of tags.
936 • sprintf X tag=%s tags.focus.name rule once X
938 Moves the next client that appears to the tag that is currently
940 focused.
941 • sprintf X %s/%s tags.focus.index tags.count echo X
943 Tells which tag is focused and how many tags there are
945 • sprintf l somelongstring echo l l l
947 Prints somelongstring three times, separated by spaces.
949 • substitute X tags.count sprintf Y "number=%c" X echo Y
951 has the same output as
953 sprintf Y "number=%s" tags.count echo Y
955 (Note how the %c changes to %s)
957 foreach IDENTIFIER OBJECT COMMAND [ARGS ...]
959 For each child of the given OBJECT the COMMAND is called with its
960 ARGS, where the IDENTIFIER is replaced by the path of the child.
961 The exit code is the exit code of the command executed last.
962 Examples:
963 • foreach T tags.by-name. echo T
965 Prints:
967 tags.by-name.1
969 tags.by-name.2
970 tags.by-name.3
971 [...]
972 • Note that foreach only iterates over children, but not over
974 attributes, so foreach S settings echo S prints nothing, since
975 the settings object has only attributes but no child objects.
976 • foreach C clients. echo C prints the object paths of all
978 clients, but the focused client twice, because it is mentioned
979 in clients. twice: by window id and as clients.focus.
980 mktemp [bool|int|string|uint] IDENTIFIER COMMAND [ARGS ...]
982 Creates a temporary attribute with the given type and replaces all
983 occurrences of IDENTIFIER in COMMAND and ARGS by the path of the
984 temporary attribute. The replaced command with its arguments is
985 executed then. The exit status of COMMAND is returned.
986 compare ATTRIBUTE OPERATOR VALUE
988 Compares the value of ATTRIBUTE with VALUE using the comparison
989 method OPERATOR. If the comparison succeeds, it returns 0, else 1.
990 The operators are:
991 • =: ATTRIBUTE's value equals VALUE
993 • !=: ATTRIBUTE's value does not equal VALUE
995 • le: ATTRIBUTE's value <= VALUE
997 • lt: ATTRIBUTE's value < VALUE
999 • ge: ATTRIBUTE's value >= VALUE
1001 • gt: ATTRIBUTE's value > VALUE
1003 The OPERATORs le,lt,ge,gt can only be used if ATTRIBUTE is of the
1005 type integer or unsigned integer. Note that the first parameter
1006 must always be an attribute and the second a constant value. If you
1007 want to compare two attributes, use the substitute command:
1008 substitute FC tags.focus.frame_count \
1010 compare tags.focus.client_count gt FC
1011 It returns success if there are more clients on the focused tag
1013 than frames.
1014 getenv NAME
1016 Gets the value of the environment variable NAME.
1017 setenv NAME VALUE
1019 Set the value of the environment variable NAME to VALUE. See the
1020 export command for a convenience wrapper.
1021 unsetenv NAME
1023 Unsets the environment variable NAME.
1024 export NAME=VALUE
1026 Set the value of the environment variable NAME to VALUE. The syntax
1027 is the same as for export in unix shells (notice that there is a
1028 =). Intuitively, if you forgot to run export FOO=BAR before
1029 starting herbstluftwm, you can run herbstclient export FOO=BAR from
1030 within your herbstluftwm session for the same effect. The export
1031 command is the same as the setenv command with different syntax.
1032
1034 Settings configure the behaviour of herbstluftwm and can be controlled
1035 via the set, get and toggle commands. The following list mentions all
1036 settings and their type. The settings can also be accessed via the
1037 object tree (see the section OBJECTS).
1038 frame_gap (Integer)
1040 The gap between frames in the tiling mode.
1041 frame_padding (Integer)
1043 The padding within a frame in the tiling mode, i.e. the space
1044 between the border of a frame and the windows within it.
1045 window_gap (Integer)
1047 The gap between windows within one frame in the tiling mode.
1048 snap_distance (Integer)
1050 If a client is dragged in floating mode, then it snaps to neighbour
1051 clients if the distance between them is smaller than snap_distance.
1052 snap_gap (Integer)
1054 Specifies the remaining gap if a dragged client snaps to an edge in
1055 floating mode. If snap_gap is set to 0, no gap will remain.
1056 mouse_recenter_gap (Integer)
1058 Specifies the gap around a monitor. If the monitor is selected and
1059 the mouse position would be restored into this gap, it is set to
1060 the center of the monitor. This is useful, when the monitor was
1061 left via mouse movement, but is reselected by keyboard. If the gap
1062 is 0 (default), the mouse is never recentered.
1063 frame_border_active_color (String/Color)
1065 The border color of a focused frame.
1066 frame_border_normal_color (String/Color)
1068 The border color of an unfocused frame.
1069 frame_border_inner_color (String/Color)
1071 The color of the inner border of a frame.
1072 frame_bg_active_color (String/Color)
1074 The fill color of a focused frame.
1075 frame_bg_normal_color (String/Color)
1077 The fill color of an unfocused frame (It is only visible if
1078 always_show_frame is set).
1079 frame_bg_transparent (Integer)
1081 If set, the background of frames are transparent. That means a
1082 rectangle is cut out from the inner such that only the frame border
1083 and a stripe of width frame_transparent_width can be seen. Use
1084 frame_active_opacity and frame_normal_opacity for real
1085 transparency.
1086 frame_transparent_width (Integer)
1088 Specifies the width of the remaining frame colored with
1089 frame_bg_active_color if frame_bg_transparent is set.
1090 frame_border_width (Integer)
1092 Border width of a frame.
1093 frame_border_inner_width (Integer)
1095 The width of the inner border of a frame. Must be less than
1096 frame_border_width, since it does not add to the frame border width
1097 but is a part of it.
1098 focus_crosses_monitor_boundaries (Boolean)
1100 If set, the focus command crosses monitor boundaries. If there is
1101 no client in the direction given to focus, then the monitor in the
1102 specified direction is focused.
1103 raise_on_focus (Boolean)
1105 If set, a window is raised if it is focused. The value of this
1106 setting is only used in floating mode.
1107 raise_on_focus_temporarily (Boolean)
1109 If set, a window is raised temporarily if it is focused on its tag.
1110 Temporarily in this case means that the window will return to its
1111 previous stacking position if another window is focused.
1112 raise_on_click (Boolean)
1114 If set, a window is raised if it is clicked. The value of this
1115 setting is only noticed in floating mode.
1116 window_border_width (Integer)
1118 Border width of a window. Warning: This only exists for
1119 compatibility reasons; it is only an alias for the attribute
1120 theme.border_width.
1121 window_border_inner_width (Integer)
1123 The width of the inner border of a window. Must be less than
1124 window_border_width, since it does not add to the window border
1125 width but is a part of it. Warning: This only exists for
1126 compatibility reasons; it is only an alias for the attribute
1127 theme.inner_width.
1128 window_border_active_color (String/Color)
1130 Border color of a focused window. Warning: This only exists for
1131 compatibility reasons; it is only an alias for the attribute
1132 theme.active.color.
1133 window_border_normal_color (String/Color)
1135 Border color of an unfocused window. Warning: This only exists for
1136 compatibility reasons; it is only an alias for the attribute
1137 theme.normal.color.
1138 window_border_urgent_color (String/Color)
1140 Border color of an unfocused but urgent window. Warning: This only
1141 exists for compatibility reasons; it is only an alias for the
1142 attribute theme.urgent.color.
1143 window_border_inner_color (String/Color)
1145 Color of the inner border of a window. Warning: This only exists
1146 for compatibility reasons; it is only an alias for the attribute
1147 theme.inner_color.
1148 always_show_frame (Boolean)
1150 If set, all frames are displayed. If unset, only frames with focus
1151 or with windows in them are displayed.
1152 frame_active_opacity (Integer)
1154 Focused frame opacity in percent. Requires a running compositing
1155 manager to take actual effect.
1156 frame_normal_opacity (Integer)
1158 Unfocused frame opacity in percent. Requires a running compositing
1159 manager to take actual effect.
1160 default_frame_layout (Integer)
1162 Index of the frame layout, which is used if a new frame is created
1163 (by split or on a new tag). For a list of valid indices and their
1164 meanings, check the list of layout algorithms above.
1165 default_direction_external_only (Boolean)
1167 This setting controls the behaviour of focus and shift if no -e or
1168 -i argument is given. If set, then focus and shift changes the
1169 focused frame even if there are other clients in this frame in the
1170 specified DIRECTION. Else, a client within current frame is
1171 selected if it is in the specified DIRECTION.
1172 gapless_grid (Boolean)
1174 This setting affects the size of the last client in a frame that is
1175 arranged by grid layout. If set, then the last client always fills
1176 the gap within this frame. If unset, then the last client has the
1177 same size as all other clients in this frame.
1178 hide_covered_windows (Boolean)
1180 If activated, windows are explicitly hidden when they are covered
1181 by another window in a frame with max layout. This only has a
1182 visible effect if a compositor is used. If activated, shadows do
1183 not stack up and transparent windows show the wallpaper behind them
1184 instead of the other clients in the max layout.
1185 smart_frame_surroundings (Boolean)
1187 If set, frame borders and gaps will be removed when there’s no
1188 ambiguity regarding the focused frame.
1189 smart_window_surroundings (Boolean)
1191 If set, window borders and gaps will be removed and minimal when
1192 there’s no ambiguity regarding the focused window. This minimal
1193 window decoration can be configured by the theme.minimal object.
1194 focus_follows_mouse (Boolean)
1196 If set and a window is focused by mouse cursor, this window is
1197 focused (this feature is also known as sloppy focus). If unset, you
1198 need to click to change the window focus by mouse.
1199 If another window is hidden by the focus change (e.g. when having
1202 pseudotiled windows in the max layout) then an extra click is
1203 required to change the focus.
1204 focus_stealing_prevention (Boolean)
1206 If set, only pagers and taskbars are allowed to change the focus.
1207 If unset, all applications can request a focus change.
1208 monitors_locked (Integer)
1210 If greater than 0, then the clients on all monitors aren’t moved or
1211 resized anymore. If it is set to 0, then the arranging of monitors
1212 is enabled again, and all monitors are rearranged if their content
1213 has changed in the meantime. You should not change this setting
1214 manually due to concurrency issues; use the commands lock and
1215 unlock instead.
1216 swap_monitors_to_get_tag (Boolean)
1218 If set: If you want to view a tag, that already is viewed on
1219 another monitor, then the monitor contents will be swapped and you
1220 see the wanted tag on the focused monitor. If not set, the other
1221 monitor is focused if it shows the desired tag.
1222 auto_detect_monitors (Boolean)
1224 If set, detect_monitors is automatically executed every time a
1225 monitor is connected, disconnected or resized.
1226 auto_detect_panels (Boolean)
1228 If set, EWMH panels are automatically detected and reserve space at
1229 the side of the monitors they are on (via pad attributes of each
1230 monitor). This setting is activated per default.
1231 tree_style (String)
1233 It contains the chars that are used to print a nice ascii tree. It
1234 must contain at least 8 characters. e.g. X|:#+*-. produces a tree
1235 like:
1236 X-.
1238 #-. child 0
1239 | #-* child 00
1240 | +-* child 01
1241 +-. child 1
1242 : #-* child 10
1243 : +-* child 11
1244 Useful values for tree_style are: ╾│ ├└╼─┐ or -| |'--. or ╾│
1246 ├╰╼─╮.
1247 wmname (String)
1249 It controls the value of the _NET_WM_NAME property on the root
1250 window, which specifies the name of the running window manager. The
1251 value of this setting is not updated if the actual _NET_WM_NAME
1252 property on the root window is changed externally. Example usage:
1253 • cycle_value wmname herbstluftwm LG3D
1255 pseudotile_center_threshold (Integer)
1257 If greater than 0, it specifies the least distance between a
1258 centered pseudotile window and the border of the frame or tile it
1259 is assigned to. If this distance is lower than
1260 pseudotile_center_threshold, it is aligned to the top left of the
1261 client’s tile.
1262 update_dragged_clients (Integer)
1264 If set, a client’s window content is resized immediately during
1265 resizing it with the mouse. If unset, the client’s content is
1266 resized after the mouse button is released.
1267 verbose (Boolean)
1269 If set, verbose output is logged to herbstluftwm’s stderr. The
1270 default value is controlled by the --verbose command line flag.
1271
1273 Rules are used to change default properties for certain clients when
1274 they appear or when the apply_rules command is called. Each rule
1275 matches against a certain subset of all clients and defines a set of
1276 properties for them (called CONSEQUENCEs). A rule can be defined with
1277 this command:
1278 rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
1280 Each rule consists of a list of FLAGs, CONDITIONs, CONSEQUENCEs and,
1282 optionally, a LABEL. (each of them can be optionally prefixed with two
1283 dashes (--) to provide a more iptables(8)-like feeling).
1284 Each rule can be given a custom label by specifying the LABEL property:
1286 • [--]label=VALUE
1288 If multiple labels are specified, the last one in the list will be
1290 applied. If no label is given, then the rule will be given an integer
1291 name that represents the index of the rule since the last unrule -F
1292 command (which is triggered in the default autostart).
1293 Tip
1295 Rule labels default to an incremental index. These default labels
1296 are unique, unless you assign a different rule a custom integer
1297 LABEL. Default labels can be captured with the printlabel flag.
1298 If a new client appears, herbstluftwm tries to apply each rule to this
1300 new client as follows: If each CONDITION of this rule matches against
1301 this client, then every CONSEQUENCE is executed. (If there are no
1302 conditions given, then this rule is executed for each client)
1303 Each CONDITION consists of a property name, an operator and a value.
1305 Valid operators are:
1306 • ~ matches if client’s property is matched by the regex value.
1308 • = matches if client’s property string is equal to value.
1310 Valid properties are:
1312 instance
1314 the first entry in client’s WM_CLASS.
1315 class
1317 the second entry in client’s WM_CLASS.
1318 title
1320 client’s window title.
1321 pid
1323 the client’s process id (Warning: the pid is not available for
1324 every client. This only matches if the client sets _NET_WM_PID to
1325 the pid itself).
1326 pgid
1328 this client’s process group id. Since the pgid of a window is
1329 derived from its pid the same restrictions apply as above.
1330 maxage
1332 matches if the age of the rule measured in seconds does not exceed
1333 value. This condition only can be used with the = operator. If
1334 maxage already is exceeded (and never will match again), then this
1335 rule is removed. (With this you can build rules that only live for
1336 a certain time.)
1337 windowtype
1339 matches the _NET_WM_WINDOW_TYPE property of a window. If
1340 _NET_WM_WINDOW_TYPE has multiple entries, then only the first entry
1341 is used here.
1342 windowrole
1344 matches the WM_WINDOW_ROLE property of a window if it is set by the
1345 window.
1346 Each CONSEQUENCE consists of a NAME=VALUE pair. Valid NAMES are:
1348 tag
1350 moves the client to tag VALUE.
1351 monitor
1353 moves the client to the tag on monitor VALUE. If the tag
1354 consequence was also specified, and switchtag is set for the
1355 client, move the client to that tag, then display that tag on
1356 monitor VALUE. If the tag consequence was specified, but switchtag
1357 was not, ignore this consequence.
1358 focus
1360 decides whether the client gets the input focus in its tag. The
1361 default is off. VALUE can be on, off or toggle.
1362 switchtag
1364 if focus is activated and the client is put to a not focused tag,
1365 then switchtag tells whether the client’s tag will be shown or not.
1366 If the tag is shown on any monitor but is not focused, the client’s
1367 tag only is brought to the current monitor if
1368 swap_monitors_to_get_tag is activated. VALUE can be on, off or
1369 toggle.
1370 manage
1372 decides whether the client will be managed or not. The default is
1373 on. VALUE can be on, off or toggle.
1374 index
1376 moves the window to a specified index in the tree. VALUE is a
1377 frame index.
1378 floating
1380 sets the floating state of the client. VALUE can be on, off or
1381 toggle.
1382 pseudotile
1384 sets the pseudotile state of the client. VALUE can be on, off or
1385 toggle.
1386 ewmhrequests
1388 sets whether the window state (the fullscreen state and the demands
1389 attention flag) can be changed by the application via ewmh itself.
1390 This does not affect the initial fullscreen state requested by the
1391 window. VALUE can be on, off or toggle, it defaults to on.
1392 ewmhnotify
1394 sets whether hlwm should let the client know about EMWH changes
1395 (currently only the fullscreen state). If this is set, applications
1396 do not change to their fullscreen-mode while still being
1397 fullscreen. VALUE can be on, off or toggle, it defaults to on.
1398 fullscreen
1400 sets the fullscreen flag of the client. VALUE can be on or off.
1401 hook
1403 emits the custom hook rule VALUE WINID when this rule is triggered
1404 by a new window with the id WINID. This consequence can be used
1405 multiple times, which will cause a hook to be emitted for each
1406 occurrence of a hook consequence.
1407 keymask
1409 sets the keymask for a client (see explanation in OBJECTS).
1410 keys_inactive
1412 sets a regex that determines which key bindings are inactive for a
1413 client (see explanation in OBJECTS).
1414 floatplacement
1416 changes the floating position of a window. The VALUE can be one of
1417 the following:
1418 • none does not change the placement at all
1420 • center centers the window on the monitor
1422 • smart tries to place it with as little overlap to other
1424 floating windows as possible. If there are multiple options
1425 with the least overlap, then the position with the least
1426 overlap to tiling windows is chosen.
1427 A rule’s behaviour can be configured by some special FLAGS:
1429 • not: negates the next CONDITION.
1431 • !: same as not.
1433 • once: only apply this rule once (and delete it afterwards).
1435 • printlabel: prints the label of the newly created rule to stdout.
1437 • prepend: prepend the rule to the list of rules instead of appending
1439 it. So its consequences may be overwritten by already existing
1440 rules.
1441 Examples:
1443 • rule --class=Netscape --tag=6 --focus=off
1445 Moves all Netscape instances to tag 6, but doesn’t give focus to
1447 them.
1448 • rule not class~.*[Tt]erm tag=2
1450 Moves all clients to tag 2, if their class does not end with term
1452 or Term.
1453 • rule class=Thunderbird index=/0
1455 Insert all Thunderbird instances in the tree that has no focus and
1457 there in the first child.
1458 • rule --windowtype=_NET_WM_WINDOW_TYPE_DIALOG --focus=on
1460 Sets focus to new dialogs which set their _NET_WM_WINDOW_TYPE
1462 correctly.
1463
1465 Several commands accept a window as reference, e.g. close. The syntax
1466 is as follows:
1467 • an empty string — or missing argument — references the currently
1469 focused window.
1470 • urgent references some window that is urgent.
1472 • 0xHEXID — where HEXID is some hexadecimal number — references the
1474 window with hexadecimal X11 window id HEXID.
1475 • DECID — where DECID is some decimal number — references the window
1477 with the decimal X11 window id DECID.
1478
1480 Warning
1481 The object tree is not stable yet, i.e. its interface may change
1482 until the next stable release. So check this documentation again
1483 after upgrading the next time.
1484 The object tree is a collection of objects with attributes similar to
1486 /sys known from the Linux kernel. Many entities (like tags, monitors,
1487 clients, ...) have objects to access their attributes directly. The
1488 tree is printed by the object_tree command and looks more or less as
1489 follows:
1490 $ herbstclient object_tree
1492 ╾─┐
1493 ├─┐ tags
1494 │ ├─┐ by-name
1495 │ │ ├─╼ 1
1496 │ │ ...
1497 │ │ └─╼ 9
1498 │ └─╼ focus
1499 ├─┐ clients
1500 │ ├─╼ 0x1400022
1501 │ └─╼ focus
1502 └─┐ monitors
1503 ├─╼ by-name
1504 └─╼ focus
1505 To print a subtree starting at a certain object, pass the PATH of the
1507 object to object_tree. The object PATH is the path using the separator
1508 . (dot), e.g. tags.by-name:
1509 $ herbstclient object_tree tags.by-name.
1511 ╾─┐ tags.by-name.
1512 ├─╼ 1
1513 ├─╼ 2
1514 ...
1515 └─╼ 9
1516 To query all attributes and children of a object, pass its PATH to
1518 attr:
1519 $ herbstclient attr tags.
1521 2 children:
1522 by-name.
1523 focus.
1524 1 attributes:
1526 .---- type
1527 | .-- writeable
1528 V V
1529 u - count = 9
1530 $ herbstclient attr tags.focus.
1532 0 children.
1533 6 attributes:
1534 .---- type
1535 | .-- writeable
1536 V V
1537 s w name = "1"
1538 b w floating = false
1539 i - frame_count = 2
1540 i - client_count = 1
1541 i - curframe_windex = 0
1542 i - curframe_wcount = 1
1543 This already gives an intuition of the output: attr first lists the
1545 names of the child objects and then all attributes, telling for each
1546 attribute:
1547 • its type
1549 • b for boolean
1551 • c for color
1553 • i for integer
1555 • r for regex
1557 • s for string
1559 • u for unsigned integer
1561 • if it is writeable by the user: w if yes, - else.
1563 • the name of the attribute
1565 • its current value (only quoted for strings)
1567 To get the unquoted value of a certain attribute, address the attribute
1569 using the same syntax as for object paths and pass it to attr or
1570 get_attr:
1571 $ herbstclient attr clients.focus.title
1573 herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1574 $ herbstclient get_attr clients.focus.title
1575 herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
1576 To change a writeable attribute value pass the new value to attr or to
1578 set_attr:
1579 $ herbstclient attr tags.focus.floating
1581 false
1582 $ herbstclient attr tags.focus.floating true
1583 $ herbstclient attr tags.focus.floating
1584 true
1585 $ herbstclient set_attr tags.focus.floating false
1586 $ herbstclient attr tags.focus.floating
1587 false
1588 Just look around to get a feeling what is there. The detailed tree
1590 content is listed as follows:
1591 • tags: subtree for tags.
1593 ┌──────────┬────────────────┐
1595 │u - count │ number of tags │
1596 └──────────┴────────────────┘
1597 • index: the object of the tag with index index.
1599 • by-name
1601 • TAG: an object for each tag with the name TAG
1603 ┌────────────────────┬────────────────────────────┐
1605 │s w name │ name of the tag │
1606 ├────────────────────┼────────────────────────────┤
1607 │b w floating │ if it is in floating mode │
1608 ├────────────────────┼────────────────────────────┤
1609 │i - index │ index of this tag │
1610 ├────────────────────┼────────────────────────────┤
1611 │i - frame_count │ number of frames │
1612 ├────────────────────┼────────────────────────────┤
1613 │i - client_count │ number of clients on this │
1614 │ │ tag │
1615 ├────────────────────┼────────────────────────────┤
1616 │i - urgent_count │ number of urgent clients │
1617 │ │ on this tag │
1618 ├────────────────────┼────────────────────────────┤
1619 │i - curframe_windex │ index of the focused │
1620 │ │ client in the select frame │
1621 ├────────────────────┼────────────────────────────┤
1622 │i - curframe_wcount │ number of clients in the │
1623 │ │ selected frame │
1624 └────────────────────┴────────────────────────────┘
1625 • focus: the object of the focused tag
1627 • clients
1629 • WINID: a object for each client with its WINID
1631 ┌───────────────────────┬────────────────────────────┐
1633 │s - winid │ its window id │
1634 ├───────────────────────┼────────────────────────────┤
1635 │s - title │ its window title │
1636 ├───────────────────────┼────────────────────────────┤
1637 │r - keymask │ A regular expression that │
1638 │ │ is matched against the │
1639 │ │ string representation of │
1640 │ │ all key bindings (as they │
1641 │ │ are printed by │
1642 │ │ list_keybinds). While this │
1643 │ │ client is focused, only │
1644 │ │ bindings that match the │
1645 │ │ expression will be active. │
1646 │ │ Any other bindings will be │
1647 │ │ disabled. The default │
1648 │ │ keymask is an empty string │
1649 │ │ (""), which does not │
1650 │ │ disable any keybinding. │
1651 ├───────────────────────┼────────────────────────────┤
1652 │r - keys_inactive │ A regular expression that │
1653 │ │ describes which │
1654 │ │ keybindings are inactive │
1655 │ │ while the client is │
1656 │ │ focused. If a key │
1657 │ │ combination is pressed and │
1658 │ │ its string representation │
1659 │ │ (as given by │
1660 │ │ list_keybinds) matches the │
1661 │ │ regex, then the key press │
1662 │ │ is propagated to the │
1663 │ │ client. │
1664 ├───────────────────────┼────────────────────────────┤
1665 │s - tag │ the tag it’s currently on │
1666 ├───────────────────────┼────────────────────────────┤
1667 │i - pid │ the process id of it (-1 │
1668 │ │ if unset) │
1669 ├───────────────────────┼────────────────────────────┤
1670 │s - class │ the class of it (second │
1671 │ │ entry in WM_CLASS) │
1672 ├───────────────────────┼────────────────────────────┤
1673 │s - instance │ the instance of it (first │
1674 │ │ entry in WM_CLASS) │
1675 ├───────────────────────┼────────────────────────────┤
1676 │b w fullscreen │ │
1677 ├───────────────────────┼────────────────────────────┤
1678 │b w floating │ whether this client is in │
1679 │ │ floating mode │
1680 ├───────────────────────┼────────────────────────────┤
1681 │b w pseudotile │ │
1682 ├───────────────────────┼────────────────────────────┤
1683 │b w ewmhrequests │ if ewmh requests are │
1684 │ │ permitted for this client │
1685 ├───────────────────────┼────────────────────────────┤
1686 │b w ewmhnotify │ if the client is told │
1687 │ │ about its state via ewmh │
1688 ├───────────────────────┼────────────────────────────┤
1689 │b w urgent │ its urgent state │
1690 ├───────────────────────┼────────────────────────────┤
1691 │b w sizehints_tiling │ if sizehints for this │
1692 │ │ client should be respected │
1693 │ │ in tiling mode │
1694 ├───────────────────────┼────────────────────────────┤
1695 │b w sizehints_floating │ if sizehints for this │
1696 │ │ client should be respected │
1697 │ │ in floating mode │
1698 └───────────────────────┴────────────────────────────┘
1699 • focus: the object of the focused client, if any
1701 • dragged: the object of a client which is dragged by the mouse,
1703 if any. See the documentation of the mousebind command for
1704 examples.
1705 • monitors
1707 ┌──────────┬────────────────────┐
1709 │u - count │ number of monitors │
1710 └──────────┴────────────────────┘
1711 • INDEX: a object for each monitor with its INDEX
1713 • by-name
1715 • NAME: a object for each named monitor
1717 ┌─────────────┬──────────────────────────┐
1719 │s - name │ its name │
1720 ├─────────────┼──────────────────────────┤
1721 │i - index │ its index │
1722 ├─────────────┼──────────────────────────┤
1723 │s - tag │ the tag currently viewed │
1724 │ │ on it │
1725 ├─────────────┼──────────────────────────┤
1726 │b - lock_tag │ │
1727 └─────────────┴──────────────────────────┘
1728 • focus: the object of the focused monitor
1730 • settings has an attribute for each setting. See SETTINGS for a
1732 list.
1733 • theme has attributes to configure the window decorations. theme
1735 and many of its child objects have the following attributes
1736 ┌─────────────────────┬────────────────────────────┐
1738 │i w border_width │ the base width of the │
1739 │ │ border │
1740 ├─────────────────────┼────────────────────────────┤
1741 │i w padding_top │ additional border width on │
1742 │ │ the top │
1743 ├─────────────────────┼────────────────────────────┤
1744 │i w padding_right │ on the right │
1745 ├─────────────────────┼────────────────────────────┤
1746 │i w padding_bottom │ on the bottom │
1747 ├─────────────────────┼────────────────────────────┤
1748 │i w padding_left │ and on the left of the │
1749 │ │ border │
1750 ├─────────────────────┼────────────────────────────┤
1751 │c w color │ the basic background color │
1752 │ │ of the border │
1753 ├─────────────────────┼────────────────────────────┤
1754 │i w inner_width │ width of the border around │
1755 │ │ the clients content │
1756 ├─────────────────────┼────────────────────────────┤
1757 │c w inner_color │ its color │
1758 ├─────────────────────┼────────────────────────────┤
1759 │i w outer_width │ width of an additional │
1760 │ │ border close to the edge │
1761 ├─────────────────────┼────────────────────────────┤
1762 │c w outer_color │ its color │
1763 ├─────────────────────┼────────────────────────────┤
1764 │c w background_color │ color behind window │
1765 │ │ contents visible on resize │
1766 ├─────────────────────┼────────────────────────────┤
1767 │b w tight_decoration │ specifies whether the size │
1768 │ │ hints also affect the │
1769 │ │ window decoration or only │
1770 │ │ the window contents of │
1771 │ │ tiled clients (requires │
1772 │ │ enabled sizehints_tiling) │
1773 ├─────────────────────┼────────────────────────────┤
1774 │s w reset │ Writing this resets all │
1775 │ │ attributes to a default │
1776 │ │ value │
1777 └─────────────────────┴────────────────────────────┘
1778 inner_color/inner_width
1780 ╻ outer_color/outer_width
1781 │ ╻
1782 │ │
1783 ┌────╴│╶─────────────────┷─────┐ ⎫ border_width
1784 │ │ color │ ⎬ +
1785 │ ┌──┷─────────────────────┐ │ ⎭ padding_top
1786 │ │====================....│ │
1787 │ │== window content ==....│ │
1788 │ │====================..╾──────── background_color
1789 │ │........................│ │
1790 │ └────────────────────────┘ │ ⎱ border_width +
1791 └──────────────────────────────┘ ⎰ padding_bottom
1792 Setting an attribute of the theme object just propagates the value
1794 to the respective attribute of the tiling and the floating object.
1795 • tiling configures the decoration of tiled clients, setting one
1797 of its attributes propagates the respective attribute of the
1798 active, normal and urgent child objects.
1799 • active configures the decoration of focused and tiled
1801 clients
1802 • normal configures the decoration of unfocused and tiled
1804 clients
1805 • urgent configures the decoration of urgent and tiled
1807 clients
1808 • floating behaves analogously to tiling
1810 • minimal behaves analogously to tiling and configures those
1812 minimal decorations triggered by smart_window_surroundings.
1813 • active propagates the attribute values to tiling.active and
1815 floating.active
1816 • normal propagates the attribute values to tiling.normal and
1818 floating.normal
1819 • urgent propagates the attribute values to tiling.urgent and
1821 floating.urgent
1822
1824 There is no configuration file but an autostart file, which is executed
1825 on startup. It is also executed on command reload. If not specified by
1826 the --autostart argument, autostart file is located at
1827 $XDG_CONFIG_HOME/herbstluftwm/autostart or at
1828 ~/.config/herbstluftwm/autostart. Normally it consists of a few
1829 herbstclient calls. If executing the autostart file in a user’s home
1830 fails the global autostart file (mostly placed at
1831 /etc/xdg/herbstluftwm/autostart) is executed as a fallback.
1832 For a quick install, copy the default autostart file to
1834 ~/.config/herbstluftwm/.
1835
1837 On special events, herbstluftwm emits some hooks (with parameters). You
1838 can receive or wait for them with herbstclient(1). Also custom hooks
1839 can be emitted with the emit_hook command. The following hooks are
1840 emitted by herbstluftwm itself:
1841 fullscreen [on|off] WINID
1843 The fullscreen state of window WINID was changed to [on|off].
1844 tag_changed TAG MONITOR
1846 The tag TAG was selected on MONITOR.
1847 focus_changed WINID TITLE
1849 The window WINID was focused. Its window title is TITLE.
1850 window_title_changed WINID TITLE
1852 The title of the focused window was changed. Its window id is WINID
1853 and its new title is TITLE.
1854 tag_flags
1856 The flags (i.e. urgent or filled state) have been changed.
1857 tag_added TAG
1859 A tag named TAG was added.
1860 tag_removed TAG
1862 The tag named TAG was removed.
1863 tag_renamed OLD NEW
1865 The tag name changed from OLD to NEW.
1866 urgent [on|off] WINID
1868 The urgent state of client with given WINID has been changed to
1869 [on|off].
1870 rule NAME WINID
1872 A window with the id WINID appeared which triggered a rule with the
1873 consequence hook=NAME.
1874 There are also other useful hooks, which never will be emitted by
1876 herbstluftwm itself, but which can be emitted with the emit_hook
1877 command:
1878 quit_panel
1880 Tells a panel to quit. The default panel.sh quits on this hook.
1881 Many scripts are using this hook.
1882 reload
1884 Tells all daemons that the autostart file is reloaded — and tells
1885 them to quit. This hook should be emitted in the first line of
1886 every autostart file.
1887
1889 Every tag has its own stack of clients that are on this tag. Similar to
1890 the EWMH specification each tag stack contains several layers, which
1891 are from top to bottom:
1892 • the focused client (if raise_on_focus_temporarily is enabled)
1894 • clients in fullscreen
1896 • normal clients
1898 • frame decorations
1900 All monitors are managed in one large stack which only consists of the
1902 stacks of the visible tags put above each other. The stacking order of
1903 these monitors is independent from their indices and can be modified
1904 using the raise_monitor command. The current stack is illustrated by
1905 the stack command.
1906
1908 As far as possible, herbstluftwm tries to be EWMH compliant. That
1909 includes:
1910 • Information about tag names and client lists is provided.
1912 • Desktop windows from desktop environments are not managed and kept
1914 below the other windows.
1915 • Client requests like getting focused are only processed if the
1917 setting focus_stealing_prevention is disabled.
1918
1920 DISPLAY
1921 Specifies the DISPLAY to use.
1922
1924 The following files are used by herbstluftwm:
1925 • autostart, see section AUTOSTART FILE.
1927
1929 Returns 0 on success. Returns EXIT_FAILURE if it cannot startup or if
1930 wmexec fails.
1931
1933 See the herbstluftwm distribution BUGS file.
1934
1936 Feel free to join the IRC channel #herbstluftwm on irc.freenode.net.
1937
1939 herbstluftwm was written by Thorsten Wißmann. All contributors are
1940 listed in the herbstluftwm distribution AUTHORS file.
1941
1943 Homepage: http://herbstluftwm.org
1944 Github page: http://github.com/herbstluftwm/herbstluftwm
1946 Patch submission and bug reporting:
1948 hlwm@lists.herbstluftwm.org
1950
1952 Copyright 2011-2020 Thorsten Wißmann. All rights reserved.
1953 This software is licensed under the "Simplified BSD License". See
1955 LICENSE for details.
1956 herbstluftwm 0.9.0 2021-01-26 HERBSTLUFTWM(1)