1HERBSTLUFTWM-TUTORI(7)                                  HERBSTLUFTWM-TUTORI(7)
2
3
4

NAME

6       herbstluftwm-tutorial - A tutorial introduction to herbstluftwm
7

DESCRIPTION

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
14       This tutorial covers these topics:
15
16       ·   Basic installation
17
18       ·   Usage of the client
19
20       ·   The tiling method
21
22       ·   Tags (or workspaces...)
23
24       ·   Multi-Monitor handling
25

BASIC INSTALLATION

27       This describes two alternate installation methods. In any case, you
28       also have to install the dependencies. Beside the standard libraries
29       (GLib, XLib) which are found on nearly any system, you should install
30       dzen2 (as current as possible) which is needed by the default panel.sh.
31
32   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
36       After installing it, the default configuration file has to be copied to
37       your home directory:
38
39           mkdir -p ~/.config/herbstluftwm
40           cp /etc/xdg/herbstluftwm/autostart ~/.config/herbstluftwm/
41
42       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
48   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
53           git clone https://github.com/herbstluftwm/herbstluftwm
54           cd herbstluftwm
55           make # build the binaries
56
57           # 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
64           # copy the configuration
65           mkdir -p ~/.config/herbstluftwm/
66           cp share/autostart ~/.config/herbstluftwm/
67           cp share/panel.sh ~/.config/herbstluftwm/
68
69       ·   If you are using bash, then source the bash completion file in your
70           ~/.bashrc
71
72               source path-to/herbstluftwm/share/herbstclient-completion
73
74       ·   If you are using zsh, then copy the share/_herbstclient file to the
75           appropriate zsh-completion directory.
76
77       Each time there is an update, you have to do the following steps in
78       your herbstluftwm directory:
79
80           git pull
81           make
82

CONFIGURE HERBSTLUFTWM AS YOUR WINDOW MANAGER

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
89           # start herbstluftwm in locked mode (it will be unlocked at the end of your
90           # autostart)
91           exec herbstluftwm --locked
92
93       After logging in the next time, you will get a default herbstluftwm
94       session.
95

FIRST START

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
102       Start an xterm by pressing Alt-Return, which will fill your entire
103       screen.
104

USING THE CLIENT

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
114               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
126       The most simple command only prints the herbstluftwm version:
127
128           $ # 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
136       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
141       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
144           # Mod=Mod1 # use alt as the main modifier
145           Mod=Mod4 # use Super as the main modifier
146
147       After saving the autostart file, you have to reload the configuration:
148
149           # the following line is identical to directly calling:
150           # ~/.config/herbstluftwm/autostart
151           herbstclient reload
152
153       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
157        1. Try some new settings in the command line
158
159        2. Add them to the autostart file
160
161        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
165       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

TILING

170       Initially there is one frame. Each frame has one of the two following
171       possible types:
172
173        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
180        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
186
187                     ╭ h (or ←) ╮                 ╭ left
188                     ⎪ j (or ↓) ⎪   means         ⎪ down
189               Mod + ┥ k (or ↑) ┝  ═══════> focus ┥ up
190                     ╰ l (or →) ╯                 ╰ right
191
192           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
199                                   ╭ 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
204       With this, you can define a custom layout. It can be printed via the
205       layout command:
206
207           $ herbstclient layout
208           ╾─┐ horizontal 50% selection=1
209             ├─┐ vertical 70% selection=0
210             │ ├─╼ vertical: 0x1400009
211             │ └─╼ vertical:
212             └─╼ max: 0x1a00009 [FOCUS]
213
214       Just play with it a bit to understand how it works. You also can
215       permanently save the layout using the dump command:
216
217           $ 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
225       And after some changes you can rewind to the original layout with the
226       load command:
227
228           $ herbstclient load "$layout"       # mind the quotes!
229

TAGS (OR WORKSPACES OR VIRTUAL DESKTOPS OR ....)

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

MONITORS

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
242       Initially there is only one large monitor ranging over your entire
243       screen:
244
245           $ herbstclient list_monitors
246           0: 1440x900+0+0 with tag "1" [FOCUS]
247
248       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
253        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
256        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
260               $ herbstclient set_monitors 1440x900+0+0 1024x768+1440+0
261
262           Alternatively, if xinerama works for your setup, simply run:
263
264               $ herbstclient detect_monitors
265
266       For even more automation, you can enable the setting
267       auto_detect_monitors. For more advanced examples, look at the
268       q3terminal.sh example script, which implements a drop-down-terminal
269       like monitor where you can put any application you like.
270
271
272
273  herbstluftwm 0.7.2\             2019-05-28            HERBSTLUFTWM-TUTORI(7)
Impressum