🌿 herbie 🌿
A herbstluftwm interactive environment thingy.
Table of Contents
Intro
herbie is helper for managing a herbstluftwm interactive environment. Interactivity is provide through keybindings and rofi and the rofi-menu Python interface.
Documentation
You are reading it. This file is it. You can see it rendered by github or more beautifully by Emacs (with the help of fniessen's ReadTheOrg)
Installation
herbie attempts to be a well behaved Python package so install it as such however you normally do. Recommended:
uv tool install git+https://github.com/brettviren/herbie
However, you may first need:
apt install libgirepository1.0-dev
Usage
The herbie package provides a herbie
command line program. Run it to print a
brief help message:
Usage: herbie [OPTIONS] COMMAND [ARGS]... Options: -h, --hc TEXT Set the herbstclient executable name -c, --config PATH Set configuration file -l, --log-file TEXT Set log file, default is terminal -L, --log-level TEXT Set log level --help Show this message and exit. Commands: hooks Start herbie loop and respond react to herbstlufwm hooks
Hooks
Once started, herbie is long-running and the primary measns to communicate it is with herbstlufwm "hooks". herbie will react to standard and custom hooks. For example,
$ herbstclient emit_hook window_jump_tag
Or, when herbstlufwm restarts, it emits the restart
hook and herbie will react
by restarting itself. Every hook is handled by a method in the Herbie
class of
hte same name. See that class for a definitive list but here are some of the
existing hook handlers:
window_jump_tag
- opens a rofi menu for jumping to a window in the current tag.
window_jump_any
- as above but include all windows across tabs.
window_menu
- open a menu on current window to apply some operation (close, minimize, toggle some property like floating or fullscreen).
layout_{drop,save,load}
- open a menu to operate on layouts (see below)
task_{start,clear}
- open a menu to operate on tasks (see below).
Many of the hooks that herbie reacts to are most conveniently emitted via a key
binding. Here is a snippet of ~/.config/herbstluftwm/autostart
that shows some
examples:
# emit to herbie hc keybind $Mod-n emit_hook window_jump_tag hc keybind $Mod-Shift-n emit_hook window_jump_any hc keybind $Mod-w emit_hook window_menu # k for kill hc keybind $Mod-k emit_hook layout_drop # capital-K for "keep"? hc keybind $Mod-Shift-k emit_hook layout_save # y for yank hc keybind $Mod-y emit_hook layout_load hc keybind $Mod-i emit_hook task_start hc keybind $Mod-Shift-i emit_hook task_clear
Layouts
A "layout" is a description of how herbstluftwm places windows in a tag. For example, you may see the layout of your current tag with:
$ herbstclient dump (split horizontal:0.5:0 (clients grid:0 0x120000e) (clients grid:0 0x3c00142))
herbie has support for managing a persistent store of layouts and applying them. It does this by presenting the user with a rofi menu in response to the layout_{drop,save,load}
hooks.
The menu items include the layout name as well as a little icon that herbie generates to show the window outlines in the layout. Here is an example:
Layouts are saved in:
~/.config/herbie/layouts/<tag>/<name>.layout
The user may create or edit these files by hand but perhaps it is easiest to configure a layout via herbstluftwm and then save it.
Layouts from herbstclient dump
include a window ID number and these may appear
in .layout
files. This window ID is ignored by herbie.
Tasks
Tasks are like layouts with added support for starting applications. They are configured through the herbie config file
~/.config/herbie/herbie.cfg
A task is specified in a form similar to a herbstluftwm layout but the (clients)
form supports an additional window:<name>
field. It specifies an application that should exist in the herbstluftwm frame. This is most clear with an example:
[window firefox-rss] title = Mozilla Firefox command = firefox -P rss-profile [window liferea] class = Liferea command = liferea [tasks] rss = (split horizontal:0.75:1 (clients window:firefox-rss) (split vertical:0.50:0 (clients window:liferea) (clients )))
Each [window <name>]
gives a command
to run to populate the frame while the class
or title
gives string that is used to match these client attributes as may be found with, for example:
herbstclient attr clients.<window-id>.{title,class}
When task_start
hook is received, herbie will present a rofi menu with all known tasks. Selecting one will create a tag with that task, assure the configured applications are present and following the layout and make that tag current. If the tag already exists, herbie will simply make it become the current tag.
The result is an automatically and repeatably populated tag.
See also
- https://herbstluftwm.org/ of course.
- A random collection of tips and tricks to use herbsluftwm.
Todo
[ ]
Layouts should be definable inherbie.cfg
and that set should be a union of what is manged inlayouts/
.[ ]
The task layout should be considered without needing to be redefined explicitly as a layout.[ ]
The OG herbie kept a custommy_focused_time
window attribute so that it can implement a "switch to last used window" operation. This has become broken in the new async version.[ ]
herbie modules starting with "a" for "async" are largely current. The rest is mostly cruft remaining from the old, non-async version. It should be integrated or purged.