Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HERBSTLUFTWM(1)						       HERBSTLUFTWM(1)

NAME
       herbstluftwm - a	manual tiling window manager for X

SYNOPSIS
       herbstluftwm [OPTION ...]

DESCRIPTION
       Starts the herbstluftwm window manager on DISPLAY. It also listens for
       calls from herbstclient(1) and executes them. The list of available
       COMMANDS	is listed below.

       OPTION can be:

       -v, --version
	   print version and exit

       -h, --help
	   print a short help and exit

       -c, --autostart PATH
	   use PATH as autostart file instead of the one in $XDG_CONFIG_HOME

       -l, --locked
	   Initially set the monitors_locked setting to	1

       --exit-on-xerror
	   Make	herbstluftwm exit whenever xlib	reports	an error. This may
	   only	be activated for automated testing and never for actual
	   sessions.

       --no-tag-import
	   Do not preserve the tags (virtual desktops) from a previous running
	   window manager.

       --verbose
	   print verbose information to	stderr.	This can be switched at
	   run-time by the verbose setting.

       This manual documents the scripting and configuration interface.	For a
       more verbose introduction see herbstluftwm-tutorial(7).

TILING ALGORITHM
       The basic tiling	concept	is that	the layout is represented by a binary
       tree. On	startup	you see	one big	frame across the entire	screen.	A
       frame fulfills exactly one of the following conditions:

	1. Frame contains windows:

	   It shows some clients and arranges them. The	current	layout
	   algorithms are:

	   o   0: vertical - clients are placed	below each other

	   o   1: horizontal - clients are placed next to each other

	   o   2: max -	all clients are	maximized in this frame

	   o   3: grid - clients are arranged in an almost quadratic grid

	2. Frame is split into subframes:

	   It is split into exactly two	subframes in a configurable fraction
	   either in a vertical	or horizontal way. So it produces two frames
	   which fulfill the same conditions (new frames always	are about to
	   contain windows). If	you split a frame that already contains
	   windows, the	windows	are inherited by the first new child frame.

       If a new	window appears,	it is put in the currently focused frame. Only
       the leaves of the frame tree can	be focused.

       A frame can be removed, it is then merged with its neighbour frame. Due
       to the layout structure of a binary tree, each frame (i.e. node in
       binary tree) has	exactly	one neighbour.

       The analogy to a	binary tree is explained the best way with a small
       example:	On startup you have a simple binary tree, with one frame that
       can contain clients:

	   C

       When splitting it (e.g. with the	command	split vertical 0.5) you	will
       get this:

	     V
	    / \
	   C   C

       You also	can split the left frame horizontally and you will get:

	       V
	      /	\
	     H	 C
	    / \
	   C   C

       If you change the focus to the client on	the right and remove this
       frame, it will be merged	with the left subtree and you will get:

	     H
	    / \
	   C   C

       The layout command prints the current layout of all tags	as a tree.

FRAME INDEX
       The exact position of a frame in	the layout tree	may be described by
       its index which is just a string	of characters. The lookup algorithm
       starts at the root frame	and interprets the index string	character by
       character as follows:

       o   0: select the first subtree

       o   1: select the second	subtree

       o   .: select the subtree having	the focus

       o   /: select the subtree not having the	focus

       o   @: select the frame having the focus. In contrast to	., this	passes
	   multiple layers all down to the focused leaf	of the frame tree.

       o   p: select the parent	tree

       o   e: finds a suitable empty frame: if the focused frame is not	empty,
	   this	selects	the closest frame that is empty	(in any	subtree)

       For example:

       o   An empty string refers to the root frame

       o   00 refers to	the first subtree of the first subtree of the root
	   frame.

       o   1e refers to	the first empty	frame in the second subtree.

       o   /@ refers to	the focused frame within the unfocused "half" of the
	   frame tree

       o   @p/ refers to the sibling of	the focused frame

TAGS
       Tags are	very similar to	workspaces, virtual desktops or	window groups.
       Each tag	has one	layout.	There is a list	of tags. You can add or	remove
       tags dynamically.

MONITORS
       Monitors	in herbstluftwm	are totally independent	of the actual physical
       screens.	This means you can for example split your screen in two
       virtual monitors	to view	two tags at once on a big screen.

       Each monitor displays exactly one tag on	a specified rectangle on the
       screen.

       Each monitor may	have a name, which can be set via add_monitor and
       rename_monitor. It can be unset with the	rename_monitor command.	A
       monitor name is an arbitrary non-empty string which must	not start with
       +, - or any digit.

       A monitor can be	referenced in different	ways:

       o   by its absolute index as listed in the list_monitors	command.

       o   by its relative index: a + or - followed by a delta,	e.g.: +3

       o   by its relative position to the focused monitor.  -l	denotes	the
	   monitor left	of the focused monitor,	-r right of, -u	above of, and
	   -d below of,	respectively.

       o   by "" (an empty string) which represents the	current	monitor.

       o   by its name.

COMMANDS
       herbstluftwm is controlled by internal commands,	which can be executed
       via herbstclient(1) or via keybindings.

       quit
	   Quits herbstluftwm.

       reload
	   Executes the	autostart file.

       version
	   Prints the version of the running herbstluftwm instance.

       echo [ARGS ...]
	   Prints all given ARGS separated by a	single space and a newline
	   afterwards.

       true
	   Ignores all arguments and always returns success, i.e. 0.

       false
	   Ignores all arguments and always returns failure, i.e. 1.

       help [OBJECT|ATTRIBUTE]
	   Print help on a given object	or attribute.

       list_commands
	   Lists all available commands.

       list_monitors
	   List	currently configured monitors with their index,	area (as
	   rectangle), name (if	named) and currently viewed tag.

       list_rules
	   Lists all active rules. Each	line consists of all the parameters
	   the rule was	called with, plus its label, separated by tabs.

       list_keybinds
	   Lists all bound keys	with their associated command. Each line
	   consists of one key combination and the command with	its parameters
	   separated by	tabs.

	   Warning
	   Tabs	within command parameters are not escaped!

       lock
	   Increases the monitors_locked setting. Use this if you want to do
	   multiple window actions at once (i.e. without repainting between
	   the single steps). See also:	unlock

       unlock
	   Decreases the monitors_locked setting. If monitors_locked is
	   changed to 0, then all monitors are repainted again.	See also: lock

       keybind KEY COMMAND [ARGS ...]
	   Adds	a key binding. When KEY	is pressed, the	internal COMMAND (with
	   its ARGS) is	executed. A key	binding	is a (possibly empty) list of
	   modifiers (Mod1, Mod2, Mod3,	Mod4, Mod5, Alt, Super,	Control/Ctrl,
	   Shift) and one key (see keysymdef.h for a list of keys). Modifiers
	   and the key are concatenated	with - or + as separator. If there is
	   already a binding for this KEY, it will be overwritten. Examples:

	   o   keybind Mod4+Ctrl+q quit

	   o   keybind Mod1-i toggle always_show_frame

	   o   keybind Mod1-Shift-space	cycle_layout -1

       keyunbind KEY|-F|--all
	   Removes the key binding for KEY. The	syntax for KEY is defined in
	   keybind. If -F or --all is given, then all key bindings will	be
	   removed.

       mousebind BUTTON	ACTION [COMMAND	...]
	   Adds	a mouse	binding	for the	floating mode. When BUTTON is pressed,
	   the specified ACTION	will be	performed.  BUTTON has a similar
	   syntax to the KEY argument of keybind: It consists of a list	of
	   modifiers (separated	by - or	+, valid modifiers are listed in the
	   description of keybind) and exactly one button name:

	   o   B1 or Button1

	   o   B2 or Button2

	   o   B3 or Button3

	   o   B4 or Button4

	   o   B5 or Button5

	   ACTION must be one of the following actions:

	   o   move: Moves the window by dragging the cursor.

	   o   resize: Resizes the window by dragging a	corner.

	   o   zoom: Resizes the window	into all four directions while keeping
	       the center of the window	constant.

	   o   call: Only calls	the specified COMMAND while client.dragged
	       links to	the client on which the	BUTTON has been	performed.

	   While an ACTION is performed, client.dragged	is the client which is
	   dragged. E.g.:

	   o   mousebind Mod1-Button3 zoom

	   o   mousebind Mod1-B4 call substitute WID clients.dragged.winid
	       spawn transset-df --inc -i WID 0.05

	   o   mousebind Mod1-B5 call substitute WID clients.dragged.winid
	       spawn transset-df --dec -i WID -m 0.2 0.05

       drag WINID ACTION
	   Starts dragging the specified client	window WINID with the
	   specified ACTION (see mousebind). E.g.  drag	'' resize starts
	   resizing the	focused	window.

       mouseunbind
	   Removes all mouse bindings.

       spawn EXECUTABLE	[ARGS ...]
	   Spawns an EXECUTABLE	with its ARGS. For details see man 3 execvp.
	   Example:

	   o   spawn xterm -e man 3 execvp

       wmexec [WINDOWMANAGER [ARGS ...]]
	   Executes the	WINDOWMANAGER with its ARGS. This is useful to switch
	   the window manager in the running session without restarting	the
	   session. If no or an	invalid	WINDOWMANAGER is given,	then
	   herbstluftwm	is restarted. For details see man 3 execvp. Example:

	   o   wmexec openbox

       chain SEPARATOR [COMMANDS ...]
	   chain expects a SEPARATOR and a list	of COMMANDS with arguments.
	   The commands	have to	be separated by	the specified SEPARATOR. The
	   SEPARATOR can by any	word and only is recognized as the separator
	   between commands if it exactly matches SEPARATOR. "chain" outputs
	   the appended	outputs	of all commands	and returns the	exit code of
	   the last executed command. Examples are:

	   o   Create a	tag called "foo" and directly use it:

	       chain , add foo , use foo

	   o   Rotate the layout clockwise:

	       chain .-. lock .-. rotate .-. rotate .-.	rotate .-. unlock

	   Counterexamples are:

	   o   This will only create a tag called "foo,":

	       chain , add foo,	use foo

	   o   Separator "." defined, but "," is used:

	       chain . add foo , use foo

       and SEPARATOR [COMMANDS ...]
	   "and" behaves like the chain	command	but only executes the
	   specified COMMANDS while the	commands return	the exit code 0.

       or SEPARATOR [COMMANDS ...]
	   "or"	behaves	like the chain command but only	executes the specified
	   COMMANDS until one command returns the exit code 0.

       ! COMMAND
	   "!" executes	the provided command, but inverts its return value. If
	   the provided	command	returns	a nonzero, "!" returns a 0, if the
	   command returns a zero, "!" returns a 1.

       try COMMAND
	   "try" executes the provided command,	prints its output, but always
	   returns success, i.e. 0.

       silent COMMAND
	   "silent" executes the provided command, but discards	its output and
	   only	returns	its exit code.

       focus_nth INDEX
	   Focuses the nth window in a frame. The first	window has INDEX 0. If
	   INDEX is negative or	greater	than the last window index, then the
	   last	window is focused.

       cycle [DELTA]
	   Cycles the selection	within the current frame by DELTA. If DELTA is
	   omitted, DELTA = 1 will be used.  DELTA can be negative; DELTA = -1
	   means: cycle	in the opposite	direction by 1.

       cycle_all [--skip-invisible] [DIRECTION]
	   Cycles through all non-minimized windows and	frames on the current
	   tag.	 DIRECTION = 1 means forward (default value), DIRECTION	= -1
	   means backward, DIRECTION = 0 has no	effect.	If there are multiple
	   windows within one frame, then it acts similar to the cycle
	   command. If --skip-invisible	is given, then this only cycles
	   through all visible windows and skips invisible windows in the max
	   layout (the flag only affects invisible windows in the max layout;
	   minimized windows are always	skipped). After	each focus change, the
	   focused window is raised.

       cycle_frame [DIRECTION]
	   Cycles through all frames on	the current tag.  DIRECTION = 1	means
	   forward, DIRECTION =	-1 means backward, DIRECTION = 0 has no
	   effect.  DIRECTION defaults to 1.

       cycle_layout [DELTA [LAYOUTS ...]]
	   Cycles the layout algorithm in the current frame by DELTA.  DELTA
	   defaults to 1. You can find a list of layout	algorithms above. If a
	   list	of LAYOUTS is given, cycle_layout will cycle through those
	   instead of the default layout algorithm list. This is done by
	   finding the first occurrence	of the current layout in LAYOUTS and
	   picking the next layout according to	DELTA. If the current layout
	   doesn't occur in LAYOUTS, the first entry is	picked.	Example:

	   o   cycle_layout -1

	   o   cycle_layout 1 vertical grid

       set_layout LAYOUT
	   Sets	the layout algorithm in	the current frame to LAYOUT. For the
	   list	of layouts, check the list of layout algorithms	above.

       close WINID
	   Closes the specified	window gracefully or the focused window	if
	   none	is given explicitly. See the section on	WINDOW IDS how to
	   reference a certain window.

       close_or_remove
	   Closes the focused window or	removes	the current frame if no	window
	   is focused. In floating mode, this acts as the close	command.

       close_and_remove
	   Closes the focused window and removes the current frame if no other
	   window is present in	that frame. In floating	mode, this acts	as the
	   close command.

       split ALIGN [FRACTION [FRAMEINDEX]]
	   Splits the focused frame (or	the frame specified by FRAMEINDEX, see
	   the section frame index) into two subframes with a specified
	   FRACTION between 0 and 1 which defaults to 0.5.  ALIGN is one of

	   o   top

	   o   bottom (= vertical)

	   o   left

	   o   right (=	horizontal)

	   o   explode

	   o   auto (split along longest side)

	       It specifies which of the two halves will be empty after	the
	       split. The other	half will be occupied by the currently focused
	       frame. After splitting, the originally focused frame will stay
	       focused.	One special ALIGN mode is explode, which splits	the
	       frame in	such a way that	the window focus, window sizes,	and
	       positions are kept as much as possible (so the default FRACTION
	       is not always 0.5, unlike for the other ALIGN modes). Example:

	   o   split explode

	   o   split bottom 0.5

	   o   split horiz 0.3

	   o   split vertical 0.5

	   o   split h

	   o   split top 0.2 ''	(splits	the root frame)

       focus [-i|-e] DIRECTION
	   Moves the focus from	current	frame to the next frame	or client in
	   DIRECTION which is in:

	   o   l[eft]

	   o   r[ight]

	   o   u[p]

	   o   d[own]

	   If -i (internal) is given or	default_direction_external_only	is
	   unset, then the next	client in DIRECTION can	also be	within the
	   same	frame. If there	is no client within this frame or -e
	   (external) is given,	then the next frame in specified DIRECTION
	   will	be focused.

	   The direction between frames	is defined as follows: The focus is in
	   a leaf of the binary	tree. Each inner node in the tree remembers
	   the last focus direction (child 0 or	child 1). The algorithm	uses
	   the shortest	possible way from the leaf (the	currently focused
	   frame) to the root until it is possible to change focus in the
	   specified DIRECTION.	From there the focus goes back to the leaf.

	   Example: The	focus is at frame A. After executing focus right focus
	   will	be at frame C.

		Tree:  H,0     Screen: aaaaaaaaaaaaaa (before)
		       a+- a^2		   a  B	 aa  C	a
		      a+-   a^2		   aaaaaaaaaaaaaa
		    V,1	  V,0	       aaaaaaaaaaaaaa
		    a+-	a^2   a+- a^2	       a  A* aa	 D  a
		   B  A* C   D	       aaaaaaaaaaaaaa

		Tree:  H,1     Screen: aaaaaaaaaaaaaa (after focus right)
		       a+- a^2		   a  B	 aa  C*	a
		      a+-   a^2		   aaaaaaaaaaaaaa
		    V,1	  V,0	       aaaaaaaaaaaaaa
		    a+-	a^2   a+- a^2	       a  A  aa	 D  a
		   B   A C*  D	       aaaaaaaaaaaaaa

	   If the currently focused client is floated, then the	next floating
	   window in the specified direction is	focused	and raised.

	   If focus_crosses_monitor_boundaries is set and no client or frame
	   is found in the specified DIRECTION,	then the next monitor in that
	   DIRECTION is	focused.

       focus_edge [-i|-e] DIRECTION
	   Focuses the window on the edge of the tag in	the specified
	   DIRECTION. The DIRECTIONS and -e behave as specified	at the focus
	   command.

	   If -i (internal) is given or	default_direction_external_only	is
	   unset, then the window on the edge of the tag will be focused.
	   Else, only the frame	on the edge of the tag will be focused,	and
	   the window that was last focused in that frame will be focused.

       raise WINID
	   Raises the specified	window.	See the	section	on WINDOW IDS on how
	   to reference	a certain window. Its result is	only visible in
	   floating mode.

	   Tip
	   The WINID also can specify an unmanaged window, although the
	   completion for the raise command does not list the IDs of unmanaged
	   windows.

       jumpto WINID
	   Puts	the focus to the specified window. See the section on WINDOW
	   IDS on how to reference a certain window.

       bring WINID
	   Moves the specified window to the current frame and focuses it.
	   Floating windows are	brought	to the current tag, but	keep their
	   floating state. See the section on WINDOW IDS on how	to reference a
	   certain window.

       resize DIRECTION	[FRACTIONDELTA]
	   Changes the size of the focused frame in the	specified DIRECTION by
	   FRACTIONDELTA (which	defaults to 0.02 if none is supplied).
	   DIRECTION behaves as	specified at the focus command.	If a floating
	   window is focused, it grows towards next edge, i.e. either the edge
	   of the next window or the monitor edge in the specified DIRECTION
	   (FRACTIONDELTA is ignored in	that case). Example:

	   o   resize right +0.05

	   o   resize down -0.1

       shift_edge [-i|-e] DIRECTION
	   Shifts the focused window to	the the	edge of	a tag in the specified
	   DIRECTION. The DIRECTIONS behave as specified at the	focus command
	   and -i and -e behave	as specified at	the focus_edge command.

       shift [-i|-e] DIRECTION
	   Shifts the focused window to	the next frame in the specified
	   DIRECTION. The DIRECTIONS and -i|-e behave as specified at the
	   focus command. If the focused client	is floated instead of being
	   tiled, then client is shifted to the	next window or screen edge.

       shift_to_monitor	MONITOR
	   Moves the focused window to the tag on the specified	MONITOR. See
	   the MONITORS	section, how to	address	a monitor.

       remove
	   Removes focused frame and merges its	windows	to its closest
	   neighbour frame.

       rotate
	   Rotates the layout on the focused tag counterclockwise by 90
	   degrees. This only manipulates the alignment	of frames, not the
	   content of them.

       mirror [vertical|horizontal|both]
	   Mirrors the layout on the focused tag vertically, horizontally, or
	   both; the default is	horizontal. This command only manipulates the
	   alignment of	frames,	not the	content	of them.

       set NAME	VALUE
	   Sets	the specified setting NAME to VALUE. Allowed values for
	   boolean settings are	on or true for on, off or false	for off,
	   toggle to toggle its	value. All SETTINGS are	listed in the section
	   below.

       get NAME
	   Prints the value of setting NAME. All SETTINGS are listed in	the
	   section below.

       toggle NAME
	   Toggles the setting NAME if it's a boolean setting.

       cycle_value NAME	VALUES ...
	   Cycles value	of the setting NAME through VALUES: I.e. it searches
	   the first occurrence	of the current value in	VALUES and changes the
	   value to the	next in	the list or to the first one if	the end	is
	   reached or current value wasn't found. Example:

	   o   cycle_value frame_gap 0 5 10 15

	   o   cycle_value frame_bg_normal_color red green blue

       cycle_monitor [DELTA]
	   Cycles monitor focused by DELTA.  DELTA defaults to 1.

       focus_monitor MONITOR
	   Puts	focus to the specified monitor.	See the	MONITORS section, how
	   to address a	monitor.

       add TAG
	   Creates a new empty tag named TAG.

       use TAG
	   Switches the	focused	monitor	to specified TAG.

       use_index INDEX [--skip-visible]
	   Switches the	focused	monitor	to the TAG with	the specified INDEX.
	   If INDEX starts with	+ or -,	then INDEX is treated relative to the
	   current TAG.	If --skip-visible is passed and	INDEX is relative,
	   then	tags that are already visible on a monitor are skipped.	E.g.
	   this	cycles backwards through the tags:

	   o   use_index -1 --skip-visible

       use_previous
	   Switches the	focused	monitor	to the previously viewed tag.

       merge_tag TAG [TARGET]
	   Removes tag named TAG and moves all its windows to tag TARGET. If
	   TARGET is omitted, the focused tag will be used.

       rename OLDTAG NEWTAG
	   Renames tag named OLDTAG to NEWTAG.

       move TAG
	   Moves the focused window to the tag named TAG.

       move_index INDEX	[--skip-visible]
	   Moves the focused window to the tag specified by INDEX. Analogical
	   to the argument for use_index: If INDEX starts with + or -, then it
	   is treated relative.	If --skip-visible is passed with a relative
	   index, then already visible tags are	skipped.

       lock_tag	[MONITOR]
	   Lock	the tag	switching on the specified monitor. If no argument is
	   given, the currently	focused	monitor	is used. When the tag
	   switching is	disabled for a monitor,	the commands use and use_index
	   have	no effect when executed	there. When swap_monitors_to_get_tag
	   is enabled, switching to a tag which	is located on a	locked
	   monitor, switches to	that monitor instead of	stealing it from
	   there. The lock state of a monitor is indicated by "[LOCKED]" in
	   the list_monitors output.

       unlock_tag [MONITOR]
	   Re-enables the tag switching	on the specified monitor. If no
	   argument is given, the currently focused monitor is used. This is
	   the reverse operation to lock_tag and has no	further	side effects
	   but removing	this lock.

       disjoin_rects RECTS ...
	   Takes a list	of rectangles and splits them into smaller pieces
	   until all rectangles	are disjoint, the result rectangles are
	   printed line	by line. This command does not modify the current list
	   of monitors!	So this	can be useful in combination with the
	   set_monitors	command.

	   o   E.g.  disjoin_rects 600x400+0+0 600x400+300+250 prints this:

		   300x150+300+250
		   600x250+0+0
		   300x150+0+250
		   300x150+600+250
		   600x250+300+400

	   o   In the above example two	monitors are split into	5 monitors,
	       which graphically means:

		   aaaaaaaa		     aaaaaaaa
		   a	  a		     aaaaaaaa
		   a  aaaaa1/4aaaa		aaaaaaaaaaaa
		   a  a	  a   a	  disjoin    a aa   aa	a
		   aaaa1/4aaaa	 a  aaaaaaaaa>	aaaaaaaaaaaa
		      a	      a			aaaaaaaaa
		      aaaaaaaaa			aaaaaaaaa

       set_monitors RECTS ...
	   Sets	the list of monitors exactly to	the list of given rectangles:

	   o   The i'th	existing monitor is moved to the i'th given RECT

	   o   New monitors are	created	if there are more RECTS	than monitors

	   o   Existing	monitors are deleted if	there are more monitors	than
	       RECTS

       detect_monitors -l|--list|--list-all|--no-disjoin
	   Sets	the list of monitors to	the physically available monitors. If
	   both	Xinerama and xrandr are	missing, it will fall back to one
	   monitor across the entire screen. If	the detected monitors overlap,
	   the will be split into more monitors	that are disjoint but cover
	   the same area using disjoin_rects.

	   If -l or --list is passed, the list of rectangles of	detected
	   physical monitors is	printed. So hc detect_monitors is equivalent
	   to the bash command hc set_monitors $(hc disjoin_rects $(hc
	   detect_monitors -l)).

	   If --list-all is passed, then it is printed which multimonitor
	   detection (xinerama,	xrandr)	has which set of physical monitors.

       add_monitor RECT	[TAG [NAME]]
	   Adds	a monitor on the specified rectangle RECT and displays TAG on
	   it.	TAG currently must not be displayed on any other monitor.
	   RECT	is a string of the form	WxH+-X+-Y. If no or an empty TAG is
	   given, then any free	tag will be chosen. If a NAME is given,	you
	   can reference to this monitor by its	name instead of	using an
	   index. Example:

	   o   add_monitor 1024x768-20+0 mynewtag main

       remove_monitor MONITOR
	   Removes the specified monitor.

       move_monitor MONITOR RECT [PADUP	[PADRIGHT [PADDOWN [PADLEFT]]]]
	   Moves the specified monitor to rectangle RECT.  RECT	is defined as
	   in add_monitor. If no or an empty pad is given, it is not changed.

       raise_monitor [MONITOR]
	   Raises the specified	monitor	or the current one if MONITOR is
	   omitted.

       rename_monitor MONITOR NAME
	   (Re)names an	already	existing monitor. If NAME is empty, it removes
	   the monitor's name.

       stack
	   Prints the stack of monitors	with the visible tags and their	layers
	   as a	tree. The order	of the printed stack is	top to bottom. The
	   style is configured by the tree_style setting.

       monitor_rect [[-p] MONITOR]
	   Prints the rectangle	of the specified monitor in the	format:	X Y W
	   H If	no MONITOR or cur is given, then the current monitor is	used.
	   If -p is supplied, then the remaining rect without the pad around
	   this	monitor	is printed.

       pad MONITOR [PADUP [PADRIGHT [PADDOWN [PADLEFT]]]]
	   Sets	the pad	of specified monitor to	the specified padding. If no
	   or an empty padding is given, it is not changed.

       list_padding [MONITOR]
	   Lists the padding of	the specified monitor, or the currently
	   focused monitor if no monitor is given.

       layout [TAG [INDEX]]
	   Prints the layout of	frame with INDEX on TAG, in a nice tree	style.
	   Its style is	defined	by the tree_style setting. If no TAG is	given,
	   the current tag is used. If no INDEX	is given, the root frame is
	   used. To specify INDEX without specifying TAG (i.e. use current
	   tag), pass an empty string as TAG.

	   An example output is:

	       a3/4aa horizontal 50% selection=1
		 aaa1/4	vertical: 0xe00009
		 aaa vertical 50% selection=0
		   aaa1/4 vertical: 0xa00009 [FOCUS]
		   aaa1/4 vertical: 0x1000009

       dump [TAG [INDEX]]
	   Prints the same information as the layout command but in a machine
	   readable format. Its	output can be read back	with the load command.

	   An example output (formatted	afterwards) is:

	       (split horizontal:0.500000:1
		   (clients vertical:0 0xe00009)
		   (split vertical:0.500000:1
		       (clients	vertical:0 0xa00009)
		       (clients	vertical:0 0x1000009)))

       load [TAG] LAYOUT
	   Loads a given LAYOUT	description to specified TAG or	current	tag if
	   no TAG is given.

	   Caution
	   LAYOUT is exactly one parameter. If you are calling it manually
	   from	your shell or from a script, quote it properly!

       complete	POSITION [COMMAND ARGS ...]
	   Prints the result of	tab completion for the partial COMMAND with
	   optional ARGS. You usually do not need this,	because	there is
	   already tab completion for bash, zsh	and fish. Example:

	   o   complete	0 m

	       prints all commands beginning with m

	   o   complete	1 toggle fra

	       prints all settings beginning with fra that can be toggled

       complete_shell POSITION [COMMAND	ARGS ...]
	   Behaves like	complete with the following extras, useful for
	   completion on posix shells:

	   o   Escape sequences	are removed in COMMAND and ARGS.

	   o   A space is appended to each full	completion result.

	   o   Special characters will be escaped in the output.

       emit_hook NAME ARGS ...
	   Emits a custom hook NAME to all idling herbstclients.

       tag_status [MONITOR]
	   Print a tab separated list of all tags for the specified MONITOR
	   index. If no	MONITOR	index is given,	the focused monitor is used.
	   Each	tag name is prefixed with one char, which indicates its	state:

	   o   .  the tag is empty

	   o   : the tag is not	empty

	   o   + the tag is viewed on the specified MONITOR, but this monitor
	       is not focused.

	   o   # the tag is viewed on the specified MONITOR and	it is focused.

	   o   - the tag is viewed on a	different MONITOR, but this monitor is
	       not focused.

	   o   % the tag is viewed on a	different MONITOR and it is focused.

	   o   !  the tag contains an urgent window

	   Warning
	   If you use a	tab in one of the tag names, then tag_status is
	   probably quite useless for you.

       floating	[[TAG] on|off|toggle|status]
	   Changes specified TAG to floating/tiling mode or prints its current
	   status. If no TAG is	given, the current tag is used.	If no argument
	   is given, floating mode is toggled. If status is given, then	on or
	   off is printed, depending of	the floating state of TAG.

       rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]
	   Defines a rule which	will be	applied	to all new clients. Its
	   behaviour is	described in the RULES section.

       unrule LABEL|--all|-F
	   Removes all rules named LABEL. If --all or -F is passed, then all
	   rules are removed.

       apply_rules WINID|--all
	   Apply the rules to the specified window WINID. If --all is passed,
	   then	the rules are applied to all clients.

       apply_tmp_rule WINID|--all [RULEDESCRIPTION...]
	   Apply the rule RULEDESCRIPTION to one particular client WINID or
	   all clients (--all) without adding the rule to the rule list. The
	   RULEDESCRIPTION specifies a rule consisting of conditions and
	   consequences	as one would pass it to	the rule command as described
	   in the RULES	section. This allows testing rules before adding them.
	   Running apply_tmp_rule only applies the particular rule given in
	   the arguments and ignores the existing rules.

       fullscreen [on|off|toggle]
	   Sets	or toggles the fullscreen state	of the focused client. If no
	   argument is given, fullscreen mode is toggled.

       pseudotile [on|off|toggle]
	   Sets	or toggles the pseudotile state	of the focused client. If a
	   client is pseudotiled, then in tiling mode the client is only moved
	   but not resized - the client	size will stay the floating size. The
	   only	reason to resize the client is to ensure that it fits into its
	   tile. If no argument	is given, pseudotile mode is toggled.

       object_tree [PATH]
	   Prints the tree of objects. If the object path PATH is given, only
	   the subtree starting	at PATH	is printed. See	the OBJECTS section
	   for more details.

       attr [PATH [NEWVALUE]
	   Prints the children and attributes of the given object addressed by
	   PATH. If PATH is an attribute, then print the attribute value. If
	   NEWVALUE is given, assign NEWVALUE to the attribute given by	PATH.
	   See the OBJECTS section for more details.

       get_attr	ATTRIBUTE
	   Print the value of the specified ATTRIBUTE as described in the
	   OBJECTS section.

       set_attr	ATTRIBUTE NEWVALUE
	   Assign NEWVALUE to the specified ATTRIBUTE as described in the
	   OBJECTS section.

       new_attr	bool|color|int|string|uint PATH	[VALUE]
	   Creates a new attribute with	the name and in	the object specified
	   by PATH. Its	type is	specified by the first argument. The attribute
	   name	has to begin with my_. If VALUE	is supplied, then it is
	   written to the attribute (if	this fails the attribute still
	   remains).

       watch PATH
	   Watch the value of the given	attribute PATH.	Whenever the value
	   changes from	OLDVALUE to NEWVALUE, a	hook is	emitted:

	   attribute_changed PATH OLDVALUE NEWVALUE

       remove_attr PATH
	   Removes the user defined attribute PATH.

       substitute IDENTIFIER ATTRIBUTE COMMAND [ARGS ...]
	   Replaces all	exact occurrences of IDENTIFIER	in COMMAND and its
	   ARGS	by the value of	the ATTRIBUTE. Note that the COMMAND also is
	   replaced by the attribute value if it equals	IDENTIFIER. The
	   replaced command with its arguments then is executed. Example:

	   o   substitute MYTITLE clients.focus.title echo MYTITLE

	       Prints the title	of the currently focused window.

       sprintf IDENTIFIER FORMAT [FORMATARG ...] COMMAND [CMDARGS ...]
	   Replaces all	exact occurrences of IDENTIFIER	in COMMAND and its
	   CMDARGS by the string specified by FORMAT. The FORMAT string	may
	   contain several placeholders, similar to the	printf(1) command:

	   o   %s inserts an attribute value whose path	is given by the	string
	       value of	the next FORMATARG

	   o   %c ("constant") inserts the next	FORMATARG without
	       modification.

	   o   %% stands for a plain %

	   The replaced	command	with its arguments then	is executed. Examples:

	   o   sprintf STR title=%s clients.focus.title	echo STR

	       Prints the title	of the currently focused window	prepended by
	       title=.

	   o   sprintf X "%c %s	tags" "there are" tags.count echo X

	       Prints there are	N tags with N replaced by the number of	tags.

	   o   sprintf X tag=%s	tags.focus.name	rule once X

	       Moves the next client that appears to the tag that is currently
	       focused.

	   o   sprintf X %s/%s tags.focus.index	tags.count echo	X

	       Tells which tag is focused and how many tags there are

	   o   sprintf l somelongstring	echo l l l

	       Prints somelongstring three times, separated by spaces.

	   o   substitute X tags.count sprintf Y "number=%c" X echo Y

	       has the same output as

	       sprintf Y "number=%s" tags.count	echo Y

	       (Note how the %c	changes	to %s)

       foreach IDENTIFIER OBJECT COMMAND [ARGS ...]
	   For each child of the given OBJECT the COMMAND is called with its
	   ARGS, where the IDENTIFIER is replaced by the path of the child.
	   The exit code is the	exit code of the command executed last.
	   Examples:

	   o   foreach T tags.by-name. echo T

	       Prints:

		   tags.by-name.1
		   tags.by-name.2
		   tags.by-name.3
		   [...]

	   o   Note that foreach only iterates over children, but not over
	       attributes, so foreach S	settings echo S	prints nothing,	since
	       the settings object has only attributes but no child objects.

	   o   foreach C clients. echo C prints	the object paths of all
	       clients,	but the	focused	client twice, because it is mentioned
	       in clients.  twice: by window id	and as clients.focus.

       mktemp [bool|int|string|uint] IDENTIFIER	COMMAND	[ARGS ...]
	   Creates a temporary attribute with the given	type and replaces all
	   occurrences of IDENTIFIER in	COMMAND	and ARGS by the	path of	the
	   temporary attribute.	The replaced command with its arguments	is
	   executed then. The exit status of COMMAND is	returned.

       compare ATTRIBUTE OPERATOR VALUE
	   Compares the	value of ATTRIBUTE with	VALUE using the	comparison
	   method OPERATOR. If the comparison succeeds,	it returns 0, else 1.
	   The operators are:

	   o   =: ATTRIBUTE's value equals VALUE

	   o   !=: ATTRIBUTE's value does not equal VALUE

	   o   le: ATTRIBUTE's value <=	VALUE

	   o   lt: ATTRIBUTE's value < VALUE

	   o   ge: ATTRIBUTE's value >=	VALUE

	   o   gt: ATTRIBUTE's value > VALUE

	   The OPERATORs le,lt,ge,gt can only be used if ATTRIBUTE is of the
	   type	integer	or unsigned integer. Note that the first parameter
	   must	always be an attribute and the second a	constant value.	If you
	   want	to compare two attributes, use the substitute command:

	       substitute FC tags.focus.frame_count \
		   compare tags.focus.client_count gt FC

	   It returns success if there are more	clients	on the focused tag
	   than	frames.

       getenv NAME
	   Gets	the value of the environment variable NAME.

       setenv NAME VALUE
	   Set the value of the	environment variable NAME to VALUE. See	the
	   export command for a	convenience wrapper.

       unsetenv	NAME
	   Unsets the environment variable NAME.

       export NAME=VALUE
	   Set the value of the	environment variable NAME to VALUE. The	syntax
	   is the same as for export in	unix shells (notice that there is a
	   =). Intuitively, if you forgot to run export	FOO=BAR	before
	   starting herbstluftwm, you can run herbstclient export FOO=BAR from
	   within your herbstluftwm session for	the same effect. The export
	   command is the same as the setenv command with different syntax.

SETTINGS
       Settings	configure the behaviour	of herbstluftwm	and can	be controlled
       via the set, get	and toggle commands. The following list	mentions all
       settings	and their type.	The settings can also be accessed via the
       object tree (see	the section OBJECTS).

       frame_gap (Integer)
	   The gap between frames in the tiling	mode.

       frame_padding (Integer)
	   The padding within a	frame in the tiling mode, i.e. the space
	   between the border of a frame and the windows within	it.

       window_gap (Integer)
	   The gap between windows within one frame in the tiling mode.

       snap_distance (Integer)
	   If a	client is dragged in floating mode, then it snaps to neighbour
	   clients if the distance between them	is smaller than	snap_distance.

       snap_gap	(Integer)
	   Specifies the remaining gap if a dragged client snaps to an edge in
	   floating mode. If snap_gap is set to	0, no gap will remain.

       mouse_recenter_gap (Integer)
	   Specifies the gap around a monitor. If the monitor is selected and
	   the mouse position would be restored	into this gap, it is set to
	   the center of the monitor. This is useful, when the monitor was
	   left	via mouse movement, but	is reselected by keyboard. If the gap
	   is 0	(default), the mouse is	never recentered.

       frame_border_active_color (String/Color)
	   The border color of a focused frame.

       frame_border_normal_color (String/Color)
	   The border color of an unfocused frame.

       frame_border_inner_color	(String/Color)
	   The color of	the inner border of a frame.

       frame_bg_active_color (String/Color)
	   The fill color of a focused frame.

       frame_bg_normal_color (String/Color)
	   The fill color of an	unfocused frame	(It is only visible if
	   always_show_frame is	set).

       frame_bg_transparent (Integer)
	   If set, the background of frames are	transparent. That means	a
	   rectangle is	cut out	from the inner such that only the frame	border
	   and a stripe	of width frame_transparent_width can be	seen. Use
	   frame_active_opacity	and frame_normal_opacity for real
	   transparency.

       frame_transparent_width (Integer)
	   Specifies the width of the remaining	frame colored with
	   frame_bg_active_color if frame_bg_transparent is set.

       frame_border_width (Integer)
	   Border width	of a frame.

       frame_border_inner_width	(Integer)
	   The width of	the inner border of a frame. Must be less than
	   frame_border_width, since it	does not add to	the frame border width
	   but is a part of it.

       focus_crosses_monitor_boundaries	(Boolean)
	   If set, the focus command crosses monitor boundaries. If there is
	   no client in	the direction given to focus, then the monitor in the
	   specified direction is focused.

       raise_on_focus (Boolean)
	   If set, a window is raised if it is focused.	The value of this
	   setting is only used	in floating mode.

       raise_on_focus_temporarily (Boolean)
	   If set, a window is raised temporarily if it	is focused on its tag.
	   Temporarily in this case means that the window will return to its
	   previous stacking position if another window	is focused.

       raise_on_click (Boolean)
	   If set, a window is raised if it is clicked.	The value of this
	   setting is only noticed in floating mode.

       window_border_width (Integer)
	   Border width	of a window.  Warning: This only exists	for
	   compatibility reasons; it is	only an	alias for the attribute
	   theme.border_width.

       window_border_inner_width (Integer)
	   The width of	the inner border of a window. Must be less than
	   window_border_width,	since it does not add to the window border
	   width but is	a part of it.  Warning:	This only exists for
	   compatibility reasons; it is	only an	alias for the attribute
	   theme.inner_width.

       window_border_active_color (String/Color)
	   Border color	of a focused window.  Warning: This only exists	for
	   compatibility reasons; it is	only an	alias for the attribute
	   theme.active.color.

       window_border_normal_color (String/Color)
	   Border color	of an unfocused	window.	 Warning: This only exists for
	   compatibility reasons; it is	only an	alias for the attribute
	   theme.normal.color.

       window_border_urgent_color (String/Color)
	   Border color	of an unfocused	but urgent window.  Warning: This only
	   exists for compatibility reasons; it	is only	an alias for the
	   attribute theme.urgent.color.

       window_border_inner_color (String/Color)
	   Color of the	inner border of	a window.  Warning: This only exists
	   for compatibility reasons; it is only an alias for the attribute
	   theme.inner_color.

       always_show_frame (Boolean)
	   If set, all frames are displayed. If	unset, only frames with	focus
	   or with windows in them are displayed.

       frame_active_opacity (Integer)
	   Focused frame opacity in percent. Requires a	running	compositing
	   manager to take actual effect.

       frame_normal_opacity (Integer)
	   Unfocused frame opacity in percent. Requires	a running compositing
	   manager to take actual effect.

       default_frame_layout (Integer)
	   Index of the	frame layout, which is used if a new frame is created
	   (by split or	on a new tag). For a list of valid indices and their
	   meanings, check the list of layout algorithms above.

       default_direction_external_only (Boolean)
	   This	setting	controls the behaviour of focus	and shift if no	-e or
	   -i argument is given. If set, then focus and	shift changes the
	   focused frame even if there are other clients in this frame in the
	   specified DIRECTION.	Else, a	client within current frame is
	   selected if it is in	the specified DIRECTION.

       gapless_grid (Boolean)
	   This	setting	affects	the size of the	last client in a frame that is
	   arranged by grid layout. If set, then the last client always	fills
	   the gap within this frame. If unset,	then the last client has the
	   same	size as	all other clients in this frame.

       hide_covered_windows (Boolean)
	   If activated, windows are explicitly	hidden when they are covered
	   by another window in	a frame	with max layout. This only has a
	   visible effect if a compositor is used. If activated, shadows do
	   not stack up	and transparent	windows	show the wallpaper behind them
	   instead of the other	clients	in the max layout.

       smart_frame_surroundings	(Boolean)
	   If set, frame borders and gaps will be removed when there's no
	   ambiguity regarding the focused frame.

       smart_window_surroundings (Boolean)
	   If set, window borders and gaps will	be removed and minimal when
	   there's no ambiguity	regarding the focused window. This minimal
	   window decoration can be configured by the theme.minimal object.

       focus_follows_mouse (Boolean)
	   If set and a	window is focused by mouse cursor, this	window is
	   focused (this feature is also known as sloppy focus). If unset, you
	   need	to click to change the window focus by mouse.

	   If another window is	hidden by the focus change (e.g. when having
	   pseudotiled windows in the max layout) then an extra	click is
	   required to change the focus.

       focus_stealing_prevention (Boolean)
	   If set, only	pagers and taskbars are	allowed	to change the focus.
	   If unset, all applications can request a focus change.

       monitors_locked (Integer)
	   If greater than 0, then the clients on all monitors aren't moved or
	   resized anymore. If it is set to 0, then the	arranging of monitors
	   is enabled again, and all monitors are rearranged if	their content
	   has changed in the meantime.	You should not change this setting
	   manually due	to concurrency issues; use the commands	lock and
	   unlock instead.

       swap_monitors_to_get_tag	(Boolean)
	   If set: If you want to view a tag, that already is viewed on
	   another monitor, then the monitor contents will be swapped and you
	   see the wanted tag on the focused monitor. If not set, the other
	   monitor is focused if it shows the desired tag.

       auto_detect_monitors (Boolean)
	   If set, detect_monitors is automatically executed every time	a
	   monitor is connected, disconnected or resized.

       auto_detect_panels (Boolean)
	   If set, EWMH	panels are automatically detected and reserve space at
	   the side of the monitors they are on	(via pad attributes of each
	   monitor). This setting is activated per default.

       tree_style (String)
	   It contains the chars that are used to print	a nice ascii tree. It
	   must	contain	at least 8 characters. e.g.  X|:#+*-.  produces	a tree
	   like:

	       X-.
		 #-. child 0
		 | #-* child 00
		 | +-* child 01
		 +-. child 1
		 : #-* child 10
		 : +-* child 11

	   Useful values for tree_style	are: a3/4a aaa1/4aa or -| |'--.	 or
	   a3/4a aa<degree>a1/4aa(R).

       wmname (String)
	   It controls the value of the	_NET_WM_NAME property on the root
	   window, which specifies the name of the running window manager. The
	   value of this setting is not	updated	if the actual _NET_WM_NAME
	   property on the root	window is changed externally. Example usage:

	   o   cycle_value wmname herbstluftwm LG3D

       pseudotile_center_threshold (Integer)
	   If greater than 0, it specifies the least distance between a
	   centered pseudotile window and the border of	the frame or tile it
	   is assigned to. If this distance is lower than
	   pseudotile_center_threshold,	it is aligned to the top left of the
	   client's tile.

       update_dragged_clients (Integer)
	   If set, a client's window content is	resized	immediately during
	   resizing it with the	mouse. If unset, the client's content is
	   resized after the mouse button is released.

       verbose (Boolean)
	   If set, verbose output is logged to herbstluftwm's stderr. The
	   default value is controlled by the --verbose	command	line flag.

RULES
       Rules are used to change	default	properties for certain clients when
       they appear or when the apply_rules command is called. Each rule
       matches against a certain subset	of all clients and defines a set of
       properties for them (called CONSEQUENCEs). A rule can be	defined	with
       this command:

       rule [[--]FLAG|[--]LABEL|[--]CONDITION|[--]CONSEQUENCE ...]

       Each rule consists of a list of FLAGs, CONDITIONs, CONSEQUENCEs and,
       optionally, a LABEL. (each of them can be optionally prefixed with two
       dashes (--) to provide a	more iptables(8)-like feeling).

       Each rule can be	given a	custom label by	specifying the LABEL property:

       o   [--]label=VALUE

       If multiple labels are specified, the last one in the list will be
       applied.	If no label is given, then the rule will be given an integer
       name that represents the	index of the rule since	the last unrule	-F
       command (which is triggered in the default autostart).

	   Tip
	   Rule	labels default to an incremental index.	These default labels
	   are unique, unless you assign a different rule a custom integer
	   LABEL. Default labels can be	captured with the printlabel flag.

       If a new	client appears,	herbstluftwm tries to apply each rule to this
       new client as follows: If each CONDITION	of this	rule matches against
       this client, then every CONSEQUENCE is executed.	(If there are no
       conditions given, then this rule	is executed for	each client)

       Each CONDITION consists of a property name, an operator and a value.
       Valid operators are:

       o   ~ matches if	client's property is matched by	the regex value.

       o   = matches if	client's property string is equal to value.

       Valid properties	are:

       instance
	   the first entry in client's WM_CLASS.

       class
	   the second entry in client's	WM_CLASS.

       title
	   client's window title.

       pid
	   the client's	process	id (Warning: the pid is	not available for
	   every client. This only matches if the client sets _NET_WM_PID to
	   the pid itself).

       pgid
	   this	client's process group id. Since the pgid of a window is
	   derived from	its pid	the same restrictions apply as above.

       maxage
	   matches if the age of the rule measured in seconds does not exceed
	   value. This condition only can be used with the = operator. If
	   maxage already is exceeded (and never will match again), then this
	   rule	is removed. (With this you can build rules that	only live for
	   a certain time.)

       windowtype
	   matches the _NET_WM_WINDOW_TYPE property of a window. If
	   _NET_WM_WINDOW_TYPE has multiple entries, then only the first entry
	   is used here.

       windowrole
	   matches the WM_WINDOW_ROLE property of a window if it is set	by the
	   window.

       Each CONSEQUENCE	consists of a NAME=VALUE pair. Valid NAMES are:

       tag
	   moves the client to tag VALUE.

       monitor
	   moves the client to the tag on monitor VALUE. If the	tag
	   consequence was also	specified, and switchtag is set	for the
	   client, move	the client to that tag,	then display that tag on
	   monitor VALUE. If the tag consequence was specified,	but switchtag
	   was not, ignore this	consequence.

       focus
	   decides whether the client gets the input focus in its tag. The
	   default is off.  VALUE can be on, off or toggle.

       switchtag
	   if focus is activated and the client	is put to a not	focused	tag,
	   then	switchtag tells	whether	the client's tag will be shown or not.
	   If the tag is shown on any monitor but is not focused, the client's
	   tag only is brought to the current monitor if
	   swap_monitors_to_get_tag is activated.  VALUE can be	on, off	or
	   toggle.

       manage
	   decides whether the client will be managed or not. The default is
	   on.	VALUE can be on, off or	toggle.

       index
	   moves the window to a specified index in the	tree.  VALUE is	a
	   frame index.

       floating
	   sets	the floating state of the client.  VALUE can be	on, off	or
	   toggle.

       pseudotile
	   sets	the pseudotile state of	the client.  VALUE can be on, off or
	   toggle.

       ewmhrequests
	   sets	whether	the window state (the fullscreen state and the demands
	   attention flag) can be changed by the application via ewmh itself.
	   This	does not affect	the initial fullscreen state requested by the
	   window.  VALUE can be on, off or toggle, it defaults	to on.

       ewmhnotify
	   sets	whether	hlwm should let	the client know	about EMWH changes
	   (currently only the fullscreen state). If this is set, applications
	   do not change to their fullscreen-mode while	still being
	   fullscreen.	VALUE can be on, off or	toggle,	it defaults to on.

       fullscreen
	   sets	the fullscreen flag of the client.  VALUE can be on or off.

       hook
	   emits the custom hook rule VALUE WINID when this rule is triggered
	   by a	new window with	the id WINID. This consequence can be used
	   multiple times, which will cause a hook to be emitted for each
	   occurrence of a hook	consequence.

       keymask
	   sets	the keymask for	a client (see explanation in OBJECTS).

       keys_inactive
	   sets	a regex	that determines	which key bindings are inactive	for a
	   client (see explanation in OBJECTS).

       floatplacement
	   changes the floating	position of a window. The VALUE	can be one of
	   the following:

	   o   none does not change the	placement at all

	   o   center centers the window on the	monitor

	   o   smart tries to place it with as little overlap to other
	       floating	windows	as possible. If	there are multiple options
	       with the	least overlap, then the	position with the least
	       overlap to tiling windows is chosen.

       A rule's	behaviour can be configured by some special FLAGS:

       o   not:	negates	the next CONDITION.

       o   !: same as not.

       o   once: only apply this rule once (and	delete it afterwards).

       o   printlabel: prints the label	of the newly created rule to stdout.

       o   prepend: prepend the	rule to	the list of rules instead of appending
	   it. So its consequences may be overwritten by already existing
	   rules.

       Examples:

       o   rule	--class=Netscape --tag=6 --focus=off

	   Moves all Netscape instances	to tag 6, but doesn't give focus to
	   them.

       o   rule	not class~.*[Tt]erm tag=2

	   Moves all clients to	tag 2, if their	class does not end with	term
	   or Term.

       o   rule	class=Thunderbird index=/0

	   Insert all Thunderbird instances in the tree	that has no focus and
	   there in the	first child.

       o   rule	--windowtype=_NET_WM_WINDOW_TYPE_DIALOG	--focus=on

	   Sets	focus to new dialogs which set their _NET_WM_WINDOW_TYPE
	   correctly.

WINDOW IDS
       Several commands	accept a window	as reference, e.g. close. The syntax
       is as follows:

       o   an empty string -- or missing argument -- references	the currently
	   focused window.

       o   urgent references some window that is urgent.

       o   0xHEXID -- where HEXID is some hexadecimal number --	references the
	   window with hexadecimal X11 window id HEXID.

       o   DECID -- where DECID	is some	decimal	number -- references the
	   window with the decimal X11 window id DECID.

OBJECTS
       The object tree is a collection of objects with attributes similar to
       /sys known from the Linux kernel. Many entities (like tags, monitors,
       clients,	...) have objects to access their attributes directly. The
       tree is printed by the object_tree command and looks more or less as
       follows:

	   $ herbstclient object_tree
	   a3/4aa
	     aaa tags
	     a aaa by-name
	     a a aaa1/4	1
	     a a ...
	     a a aaa1/4	9
	     a aaa1/4 focus
	     aaa clients
	     a aaa1/4 0x1400022
	     a aaa1/4 focus
	     aaa monitors
	       aaa1/4 by-name
	       aaa1/4 focus

       To print	a subtree starting at a	certain	object,	pass the PATH of the
       object to object_tree. The object PATH is the path using	the separator
       . (dot),	e.g. tags.by-name:

	   $ herbstclient object_tree tags.by-name.
	   a3/4aa tags.by-name.
	     aaa1/4 1
	     aaa1/4 2
	     ...
	     aaa1/4 9

       To query	all attributes and children of a object, pass its PATH to
       attr:

	   $ herbstclient attr tags.
	   2 children:
	     by-name.
	     focus.

	   1 attributes:
	    .---- type
	    | .-- writable
	    V V
	    u -	count		     = 9

	   $ herbstclient attr tags.focus.
	   0 children.
	   6 attributes:
	    .---- type
	    | .-- writable
	    V V
	    s w	name		     = "1"
	    b w	floating	     = false
	    i -	frame_count	     = 2
	    i -	client_count	     = 1
	    i -	curframe_windex	     = 0
	    i -	curframe_wcount	     = 1

       This already gives an intuition of the output: attr first lists the
       names of	the child objects and then all attributes, telling for each
       attribute:

       o   its type

	   o   b for boolean

	   o   c for color

	   o   i for integer

	   o   r for regex

	   o   s for string

	   o   u for unsigned integer

       o   if it is writable by	the user: w if yes, - else.

       o   the name of the attribute

       o   its current value (only quoted for strings)

       To get the unquoted value of a certain attribute, address the attribute
       using the same syntax as	for object paths and pass it to	attr or
       get_attr:

	   $ herbstclient attr clients.focus.title
	   herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM
	   $ herbstclient get_attr  clients.focus.title
	   herbstluftwm.txt = (~/dev/c/herbstluftwm/doc) - VIM

       To change a writable attribute value pass the new value to attr or to
       set_attr:

	   $ herbstclient attr tags.focus.floating
	   false
	   $ herbstclient attr tags.focus.floating true
	   $ herbstclient attr tags.focus.floating
	   true
	   $ herbstclient set_attr tags.focus.floating false
	   $ herbstclient attr tags.focus.floating
	   false

       More information	on an attribute	or object is given by the help
       command:

	   $ herbstclient help clients.focus

       Just look around	to get a feeling what is there.	The entry point	is a
       root object that	has the	following child	objects:

   clients:
       The managed windows. For	every (managed)	window id there	is an entry
       here.

       o   dragged: the	object of a client which is currently dragged by the
	   mouse, if any. See the documentation	of the mousebind command for
	   examples. For attributes and	children, see clients.focus

       o   focus: the focused client (only exists if a client is focused).  a
	   managed window

	   o   string class: the class of it (second entry in WM_CLASS)

	   o   bool ewmhnotify = true: if the client is	told about its state
	       via ewmh

	   o   bool ewmhrequests = true: if ewmh requests are permitted	for
	       this client

	   o   bool floating = false: whether this client is floated above the
	       tiled clients.

	   o   bool fullscreen = false:	whether	this client covers all other
	       windows and panels on its monitor.

	   o   string instance:	the instance of	it (first entry	in WM_CLASS)

	   o   regex keymask = "": A regular expression	that is	matched
	       against the string representation of all	key bindings (as they
	       are printed by list_keybinds). While this client	is focused,
	       only bindings that match	the expression will be active. Any
	       other bindings will be disabled.	The default keymask is an
	       empty string (),	which does not disable any keybinding.

	   o   regex keys_inactive = "": A regular expression that describes
	       which keybindings are inactive while the	client is focused. If
	       a key combination is pressed and	its string representation (as
	       given by	list_keybinds) matches the regex, then the key press
	       is propagated to	the client.

	   o   bool minimized =	false: whether this client is minimized	(also
	       called iconified).

	   o   int pgid	= -1

	   o   int pid = -1: the process id of it (-1 if unset).

	   o   bool pseudotile = false:	if activated, the client always	has
	       its floating window size, even if it is in tiling mode.

	   o   bool sizehints_floating = true: if sizehints for	this client
	       should be respected in floating mode

	   o   bool sizehints_tiling = false: if sizehints for this client
	       should be respected in tiling mode

	   o   string tag: the name of the tag it's currently on.

	   o   string title = "": its window title

	   o   bool urgent = false: the	urgency	state (also known as: demands
	       attention)

	   o   bool visible = visible_already: whether this client is rendered
	       currently

	   o   string winid = "": its window id	(as a hexadecimal number with
	       0x prefix)

	   o   parent_frame: the frame contaning this client if	the client is
	       tiled. For attributes and children, see tags.focus.tiling.root

   monitors:
       Every monitor is	a rectangular part of the screen on which a tag	is
       shown. These monitors may or maynot match the actual outputs. This has
       an entry	INDEX for each monitor withindex INDEX.

       o   uint	count

       o   by-name: This has an	entry name for every object with the given
	   name. If an object has an empty name	then it	is not listed here.

       o   focus: the focused monitor.	The monitor is a rectangular part on
	   the screen that holds precisely one tag at a	time. The pad
	   attributes reserve space on the monitor's edge for panels, so this
	   space (given	in number of pixels) is	never occupied by tiled
	   clients.

	   o   Rectangle geometry = rect_: the outer geometry of the monitor

	   o   uint index = 0: the monitor's index (starts at index 0)

	   o   bool lock_tag = false: if activated, then it it is not possible
	       to switch this monitor to a different tag.

	   o   string name = "": the monitor's name (can be empty)

	   o   int pad_down = 0: space for panels at the monitor's lower edge

	   o   int pad_left = 0: space for panels at the monitor's left	edge

	   o   int pad_right = 0: space	for panels at the monitor's right edge

	   o   int pad_up = 0: space for panels	at the monitor's upper edge

	   o   string tag: the name of the tag viewed here

   settings:
       This has	an attribute for each setting. Many settings are wrappers
       around attributes and only exist	for compatibility.

       o   bool	always_show_frame = false

       o   bool	auto_detect_monitors = false

       o   bool	auto_detect_panels = true

       o   bool	default_direction_external_only	= false

       o   uint	default_frame_layout = 0

       o   bool	focus_crosses_monitor_boundaries = true

       o   bool	focus_follows_mouse = false

       o   bool	focus_stealing_prevention = true

       o   int frame_active_opacity = 100

       o   color frame_bg_active_color = black

       o   color frame_bg_normal_color = black

       o   bool	frame_bg_transparent = false

       o   color frame_border_active_color = red

       o   color frame_border_inner_color = black

       o   int frame_border_inner_width	= 0

       o   color frame_border_normal_color = blue

       o   int frame_border_width = 2

       o   int frame_gap = 5

       o   int frame_normal_opacity = 100

       o   int frame_padding = 0

       o   int frame_transparent_width = 0

       o   bool	gapless_grid = true

       o   bool	hide_covered_windows = false

       o   int monitors_locked = 0

       o   int mouse_recenter_gap = 0

       o   int pseudotile_center_threshold = 10

       o   bool	raise_on_click = true

       o   bool	raise_on_focus = false

       o   bool	raise_on_focus_temporarily = false

       o   bool	smart_frame_surroundings = false

       o   bool	smart_window_surroundings = false

       o   int snap_distance = 10

       o   int snap_gap	= 5

       o   bool	swap_monitors_to_get_tag = true

       o   string tree_style = "*| +`--."

       o   bool	update_dragged_clients = false

       o   bool	verbose	= false

       o   color window_border_active_color

       o   color window_border_inner_color

       o   int window_border_inner_width

       o   color window_border_normal_color

       o   color window_border_urgent_color

       o   int window_border_width

       o   int window_gap = 0

       o   string wmname = herbstluftwm

   tags:
       The tags	(or virtual desktops or	workspaces). This contains an entry
       index for each tag with the given index.

       o   uint	count

       o   by-name: For	attributes and children, see monitors.by-name

       o   focus: the object of	the focused tag, equivalently, the tag on the
	   focused monitor.

	   o   int client_count: the number of clients on this tag

	   o   int curframe_wcount: number of clients in the selected frame

	   o   int curframe_windex: index of the focused client	in the
	       selected	frame

	   o   bool floating = false: if the entire tag	is set to floating
	       mode

	   o   bool floating_focused = false: if the floating layer is focused
	       (otherwise the tiling layer is)

	   o   int frame_count:	the number of frames on	this tag

	   o   uint index = 0: index of	this tag (the first index is 0)

	   o   string name = name_: name of the	tag (must be non-empty)

	   o   int urgent_count: the number of urgent clients on this tag

	   o   bool visible = false: if	this tag is shown on some monitor

	   o   focused_client: For attributes and children, see	clients.focus

	   o   tiling:

	       o   focused_frame: The focused frame (leaf) in this frame tree.
		   For attributes and children,	see tags.focus.tiling.root

	       o   root	can be a frame leaf.

		   o   LayoutAlgorithm algorithm

		   o   int client_count

		   o   string index

		   o   int selection

	       o   root	can be a frame split.

		   o   decimal fraction

		   o   string index

		   o   int selection

		   o   SplitAlign split_type

		   o   0 can be	a frame	leaf. For attributes and children, see
		       tags.focus.tiling.root

		   o   0 can be	a frame	split. For attributes and children,
		       see tags.focus.tiling.root

		   o   1 can be	a frame	leaf. For attributes and children, see
		       tags.focus.tiling.root

		   o   1 can be	a frame	split. For attributes and children,
		       see tags.focus.tiling.root

   theme:
	   inner_color/inner_width
		 a>>	    outer_color/outer_width
		 a		    a>>
		 a		    a
	   aaaaaa'aa<paragraph>aaaaaaaaaaaaaaaaaa.aaaaaa a<< border_width
	   a	 a	color		  a a~ + title_height
	   a  aaaa.aaaaaaaaaaaaaaaaaaaaaa  a a + padding_top
	   a  a====================....a  a
	   a  a== window content ==....a  a
	   a  a====================..a3/4aaaaaaaa background_color
	   a  a........................a  a
	   a  aaaaaaaaaaaaaaaaaaaaaaaaaa  a a+-	border_width +
	   aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa a<degree> padding_bottom

       Setting an attribute of the theme object	just propagates	the value to
       the respective attribute	of the tiling and the floating object.

       o   color background_color = black

       o   uint	border_width = 0

       o   color color = black

       o   color inner_color = black

       o   uint	inner_width = 0

       o   color outer_color = black

       o   uint	outer_width = 0

       o   uint	padding_bottom = 0

       o   uint	padding_left = 0

       o   uint	padding_right =	0

       o   uint	padding_top = 0

       o   string reset: writing this resets all attributes to a default value

       o   bool	tight_decoration = false

       o   color title_color = black

       o   font	title_font = fixed

       o   uint	title_height = 0

       o   active: configures the decoration of	the focused client.

	   o   color background_color =	black

	   o   uint border_width = 0

	   o   color color = black

	   o   color inner_color = black

	   o   uint inner_width	= 0

	   o   color outer_color = black

	   o   uint outer_width	= 0

	   o   uint padding_bottom = 0

	   o   uint padding_left = 0

	   o   uint padding_right = 0

	   o   uint padding_top	= 0

	   o   string reset: writing this resets all attributes	to a default
	       value

	   o   bool tight_decoration = false

	   o   color title_color = black

	   o   font title_font = fixed

	   o   uint title_height = 0

       o   floating: behaves analogously to tiling.

	   o   color background_color =	black

	   o   uint border_width = 0

	   o   color color = black

	   o   color inner_color = black

	   o   uint inner_width	= 0

	   o   color outer_color = black

	   o   uint outer_width	= 0

	   o   uint padding_bottom = 0

	   o   uint padding_left = 0

	   o   uint padding_right = 0

	   o   uint padding_top	= 0

	   o   string reset: writing this resets all attributes	to a default
	       value

	   o   bool tight_decoration = false

	   o   color title_color = black

	   o   font title_font = fixed

	   o   uint title_height = 0

	   o   active: configures the decoration of the	focused	client.	For
	       attributes and children,	see theme.active

	   o   normal: the default decoration scheme for clients. For
	       attributes and children,	see theme.active

	   o   urgent: configures the decoration of urgent clients. For
	       attributes and children,	see theme.active

       o   fullscreen: configures clients in fullscreen	state. For attributes
	   and children, see theme.floating

       o   minimal: configures clients with minimal decorations	triggered by
	   smart_window_surroundings. For attributes and children, see
	   theme.floating

       o   normal: the default decoration scheme for clients. For attributes
	   and children, see theme.active

       o   tiling: configures the decoration of	tiled clients, setting one of
	   its attributes propagates the respective attribute of the active,
	   normal and urgent child objects. For	attributes and children, see
	   theme.floating

       o   urgent: configures the decoration of	urgent clients.	For attributes
	   and children, see theme.active

   watchers:
       o   uint	count: the number of attributes	that are watched

AUTOSTART FILE
       There is	no configuration file but an autostart file, which is executed
       on startup. It is also executed on command reload. If not specified by
       the --autostart argument, autostart file	is located at
       $XDG_CONFIG_HOME/herbstluftwm/autostart or at
       ~/.config/herbstluftwm/autostart. Normally it consists of a few
       herbstclient calls. If executing	the autostart file in a	user's home
       fails the global	autostart file (mostly placed at
       /etc/xdg/herbstluftwm/autostart)	is executed as a fallback.

       For a quick install, copy the default autostart file to
       ~/.config/herbstluftwm/.

HOOKS
       On special events, herbstluftwm emits some hooks	(with parameters). You
       can receive or wait for them with herbstclient(1). Also custom hooks
       can be emitted with the emit_hook command. The following	hooks are
       emitted by herbstluftwm itself:

       attribute_changed PATH OLDVALUE NEWVALUE
	   The attribute PATH was changed from OLDVALUE	to NEWVALUE. Requires
	   that	the attribute PATH has been passed to the watch	command
	   before.

       fullscreen [on|off] WINID
	   The fullscreen state	of window WINID	was changed to [on|off].

       tag_changed TAG MONITOR
	   The tag TAG was selected on MONITOR.

       focus_changed WINID TITLE
	   The window WINID was	focused. Its window title is TITLE.

       window_title_changed WINID TITLE
	   The title of	the focused window was changed.	Its window id is WINID
	   and its new title is	TITLE.

       tag_flags
	   The flags (i.e. urgent or filled state) have	been changed.

       tag_added TAG
	   A tag named TAG was added.

       tag_removed TAG
	   The tag named TAG was removed.

       tag_renamed OLD NEW
	   The tag name	changed	from OLD to NEW.

       urgent [on|off] WINID
	   The urgent state of client with given WINID has been	changed	to
	   [on|off].

       rule NAME WINID
	   A window with the id	WINID appeared which triggered a rule with the
	   consequence hook=NAME.

       There are also other useful hooks, which	never will be emitted by
       herbstluftwm itself, but	which can be emitted with the emit_hook
       command:

       quit_panel
	   Tells a panel to quit. The default panel.sh quits on	this hook.
	   Many	scripts	are using this hook.

       reload
	   Tells all daemons that the autostart	file is	reloaded -- and	tells
	   them	to quit. This hook should be emitted in	the first line of
	   every autostart file.

STACKING
       Every tag has its own stack of clients that are on this tag. Similar to
       the EWMH	specification each tag stack contains several layers, which
       are from	top to bottom:

       o   the focused client (if raise_on_focus_temporarily is	enabled)

       o   clients in fullscreen

       o   normal clients

       o   frame decorations

       All monitors are	managed	in one large stack which only consists of the
       stacks of the visible tags put above each other.	The stacking order of
       these monitors is independent from their	indices	and can	be modified
       using the raise_monitor command.	The current stack is illustrated by
       the stack command.

EWMH
       As far as possible, herbstluftwm	tries to be EWMH compliant. That
       includes:

       o   Information about tag names and client lists	is provided.

       o   Desktop windows from	desktop	environments are not managed and kept
	   below the other windows.

       o   Client requests like	getting	focused	are only processed if the
	   setting focus_stealing_prevention is	disabled.

ENVIRONMENT VARIABLES
       DISPLAY
	   Specifies the DISPLAY to use.

FILES
       The following files are used by herbstluftwm:

       o   autostart, see section AUTOSTART FILE.

EXIT STATUS
       Returns 0 on success. Returns EXIT_FAILURE if it	cannot startup or if
       wmexec fails.

BUGS
       See the herbstluftwm Github issues:
       https://github.com/herbstluftwm/herbstluftwm/issues

COMMUNITY
       Feel free to join the IRC channel #herbstluftwm on irc.freenode.net.

AUTHOR
       herbstluftwm was	written	by Thorsten WiAmann. All contributors are
       listed in the herbstluftwm distribution AUTHORS file.

RESOURCES
       Homepage: http://herbstluftwm.org

       Github page: http://github.com/herbstluftwm/herbstluftwm

       Patch submission	and bug	reporting:

	   hlwm@lists.herbstluftwm.org

COPYING
       Copyright 2011-2020 Thorsten WiAmann. All rights	reserved.

       This software is	licensed under the "Simplified BSD License". See
       LICENSE for details.

  herbstluftwm 0.9.2		  2021-11-06		       HERBSTLUFTWM(1)

NAME | SYNOPSIS | DESCRIPTION | TILING ALGORITHM | FRAME INDEX | TAGS | MONITORS | COMMANDS | SETTINGS | RULES | WINDOW IDS | OBJECTS | AUTOSTART FILE | HOOKS | STACKING | EWMH | ENVIRONMENT VARIABLES | FILES | EXIT STATUS | BUGS | COMMUNITY | AUTHOR | RESOURCES | COPYING

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=herbstluftwm&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help