1HERBSTLUFTWM-TUTORI(7) HERBSTLUFTWM-TUTORI(7)
2
6 herbstluftwm-tutorial - A tutorial introduction to herbstluftwm
7
9 This tutorial explains how to create a basic herbstluftwm setup and
10 introduces the major herbstluftwm features. This tutorial neither
11 covers all features nor specifies the mentioned features entirely; see
12 herbstluftwm(1) for a compact and more complete description.
13 This tutorial covers these topics:
15 • Basic installation
17 • Usage of the client
19 • The tiling method
21 • Tags (or workspaces...)
23 • Multi-Monitor handling
25
27 This describes two alternate installation methods. In any case, you
28 also have to install the dependencies. Beside the standard libraries
29 (XLib) which are found on nearly any system, you should install dzen2
30 (as current as possible) which is needed by the default panel.sh.
31 Via the package manager
33 You always should prefer installing herbstluftwm via your package
34 manager on your system. It should be called herbstluftwm.
35 After installing it, the default configuration file has to be copied to
37 your home directory:
38 mkdir -p ~/.config/herbstluftwm
40 cp /etc/xdg/herbstluftwm/autostart ~/.config/herbstluftwm/
41 You also should activate the tab completion for herbstclient. In case
43 of bash, you can either activate the tab completion in general or
44 source the herbstclient-completion from the bash_completion.d directory
45 in your bashrc. In case of zsh the tab-completion normally is activated
46 already (if not, consider activating it).
47 Directly from git
49 If there is no package for your platform or if you want to use the
50 current git version, then you can pull directly from the main
51 repository:
52 git clone https://github.com/herbstluftwm/herbstluftwm
54 cd herbstluftwm
55 make # build the binaries
56 # install files
58 mkdir -p ~/bin
59 # you also have to put $HOME/bin to your path, e.g. by:
60 echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc # or to your zshrc, etc...
61 ln -s `pwd`/herbstluftwm ~/bin/
62 ln -s `pwd`/herbstclient ~/bin/
63 # copy the configuration
65 mkdir -p ~/.config/herbstluftwm/
66 cp share/autostart ~/.config/herbstluftwm/
67 cp share/panel.sh ~/.config/herbstluftwm/
68 • If you are using bash, then source the bash completion file in your
70 ~/.bashrc
71 source path-to/herbstluftwm/share/herbstclient-completion
73 • If you are using zsh, then copy the share/_herbstclient file to the
75 appropriate zsh-completion directory.
76 Each time there is an update, you have to do the following steps in
78 your herbstluftwm directory:
79 git pull
81 make
82
84 As usual you can define herbstluftwm as your window manager by either
85 selecting herbstluftwm in your login manager or by starting it in your
86 ~/.xinitrc, mostly by writing to your xinitrc (or .xsession on some
87 systems):
88 # start herbstluftwm in locked mode (it will be unlocked at the end of your
90 # autostart)
91 exec herbstluftwm --locked
92 After logging in the next time, you will get a default herbstluftwm
94 session.
95
97 After starting herbstluftwm, the screen is surrounded by a green frame
98 initially, which indicates that there is only one large frame. A frame
99 is a container where actual windows can be placed or which can be split
100 into two frames.
101 Start an xterm by pressing Alt-Return, which will fill your entire
103 screen.
104
106 The only way to communicate to herbstluftwm is by using the client
107 application called herbstclient. Its usual syntax is: herbstclient
108 COMMAND [ARGUMENTS]. This calls a certain COMMAND within your running
109 herbstluftwm instance. This causes some effect (which depends on the
110 given COMMAND and ARGUMENTS), produces some output which is printed by
111 herbstclient and lets herbstclient exit with a exit-code (e.g. 0 for
112 success) like many other UNIX tools:
113 shell COMMANDS,
115 ╲ COMMAND, ARGUMENTS
116 ╲ ARGUMENTS ╭────────────╮
117 ╲ │ │
118 V │ V
119 herbstclient herbstluftwm
120 ╱ ^ │
121 ╱ output, │ │
122 ╱ exit-code ╰────────────╯
123 V output,
124 shell/terminal exit-code
125 The most simple command only prints the herbstluftwm version:
127 $ # lines prefixed with $ describes what to type, other lines describe the
129 $ # typical output
130 $ # Type: her<tab>c<tab> ve<tab>
131 $ herbstclient version
132 herbstluftwm 0.4.1 (built on Aug 30 2012)
133 $ herbstclient set window_border_active_color red
134 $ # now the window border turned red
135 The configuration of herbstluftwm only is done by calling commands via
137 herbstclient. So the only configuration file is the autostart which is
138 placed at ~/.config/herbstluftwm/ and which is a sequence of those
139 herbstclient calls.
140 Open it in your favourite text editor and replace the Mod-line by this
142 to use the Super-key (or also called Windows-key) as the main modifier:
143 # Mod=Mod1 # use alt as the main modifier
145 Mod=Mod4 # use Super as the main modifier
146 After saving the autostart file, you have to reload the configuration:
148 # the following line is identical to directly calling:
150 # ~/.config/herbstluftwm/autostart
151 herbstclient reload
152 Now you may notice that the red border color of your terminal turned
154 green again, because the color is set in the default autostart. That’s
155 the typical configuration workflow:
156 1. Try some new settings in the command line
158 2. Add them to the autostart file
160 3. Press Mod-Shift-r which calls the reload command or directly
162 execute the autostart file from your shell to get the error
163 messages if something went wrong.
164 To learn more about herbstluftwm, just go through the man page line by
166 line and check using the herbstluftwm(1) man page what it does. For a
167 quick introduction to the central paradigms, continue reading this.
168
170 Initially there is one frame. Each frame has one of the two following
171 possible types:
172 1. It serves as a container for windows, i.e. it can hold zero up to
174 arbitrarily many windows. Launch several more terminals to see what
175 happens: If there are multiple windows in one frame, they are
176 aligned below each other. To change this layout algorithm, press
177 Mod-space to cycle all the available layouting algorithms for the
178 focused frame.
179 2. A frame also can be split into two subframes, which can be aligned
181 next to or below each other. Press Mod-o to split to an horizontal
182 alignment. To navigate to the fresh frame right of the old one
183 press Mod-l. Press Mod-u to split vertically. The intuitive
184 navigation is:
185 ⎧ h (or ←) ⎫ ⎧ left
188 ⎪ j (or ↓) ⎪ means ⎪ down
189 Mod + ⎨ k (or ↑) ⎬ ═══════> focus ⎨ up
190 ⎩ l (or →) ⎭ ⎩ right
191 To undo splitting, you can remove a frame via Mod-r. To shift some
193 window from one frame to one of its neighbours, use the same
194 keyboard shortcut while holding the Shift key pressed. It is not
195 possible to resize single windows, only to resize frames. The
196 according keyboard shortcut is the same while holding Control
197 pressed. All in all it is:
198 ⎧ h (or ←) ⎫ ⎧ left
200 ⎧ ⎫ ⎪ j (or ↓) ⎪ means ⎧ focus frame ⎫ ⎪ down
201 Mod + ⎨ Shift ⎬ + ⎨ k (or ↑) ⎬ ═════> ⎨ move window ⎬ ⎨ up
202 ⎩ Control ⎭ ⎩ l (or →) ⎭ ⎩ resize frame ⎭ ⎩ right
203 With this, you can define a custom layout. It can be printed via the
205 layout command:
206 $ herbstclient layout
208 ╾─┐ horizontal 50% selection=1
209 ├─┐ vertical 70% selection=0
210 │ ├─╼ vertical: 0x1400009
211 │ └─╼ vertical:
212 └─╼ max: 0x1a00009 [FOCUS]
213 Just play with it a bit to understand how it works. You also can
215 permanently save the layout using the dump command:
216 $ herbstclient dump
218 (split horizontal:0.500000:1
219 (split vertical:0.700000:0
220 (clients vertical:0 0x1400009)
221 (clients vertical:0))
222 (clients max:0 0x1a00009))
223 $ layout=$(herbstclient dump)
224 And after some changes you can rewind to the original layout with the
226 load command:
227 $ herbstclient load "$layout" # mind the quotes!
229
231 A tag consists of a name and a frame layout with clients on it. With
232 the default autostart, there are nine tags named 1 to 9. You can switch
233 to the ith tag using Mod-i, e.g. Mod-4 to switch to tag 4 or with the
234 command use 4. A window can be move to tag i via Mod-Shift-i, i.e. with
235 the move command.
236
238 The notion of a monitor in herbstluftwm is treated much more abstract
239 and general than in other window managers: A monitor just is a
240 rectangular part of your screen which shows exactly one tag on it.
241 Initially there is only one large monitor ranging over your entire
243 screen:
244 $ herbstclient list_monitors
246 0: 1440x900+0+0 with tag "1" [FOCUS]
247 The output shows that there is only one monitor with index 0 at
249 position +0+0 of size 1440x900 showing tag 1. In most cases, the
250 herbstluftwm monitors will match the list of physical monitors. So to
251 add another physical monitor, you have to perform several steps:
252 1. Enable it, such that it shows a part of your screen. You can use
254 xrandr, xinerama or any other tool you like.
255 2. Register it in herbstluftwm: Lets assume your new monitor has the
257 resolution 1024x768 and is right of your main screen, then you can
258 activate it via:
259 $ herbstclient set_monitors 1440x900+0+0 1024x768+1440+0
261 Alternatively, if xinerama or xrandr works for your setup, simply
263 run:
264 $ herbstclient detect_monitors
266 For even more automation, you can enable the setting
268 auto_detect_monitors. For more advanced examples, look at the
269 q3terminal.sh example script, which implements a drop-down-terminal
270 like monitor where you can put any application you like.
271 herbstluftwm 0.9.5 2022-07-30 HERBSTLUFTWM-TUTORI(7)