README.md

   1 # 🌱 herbe
   2 > Daemon-less notifications without D-Bus. Minimal and lightweight.
   3
   4 <p align="center">
   5   <img src="https://user-images.githubusercontent.com/24730635/90975811-cd62fd00-e537-11ea-9169-92e68a71d0a0.gif" />
   6 </p>
   7
   8 ## Features
   9 * Under 200 lines of code
  10 * Doesn't run in the background, just displays the notification and exits
  11 * No external dependencies except Xlib and Xft
  12 * Configurable through `config.h` or Xresources ([using this patch](https://github.com/dudik/herbe/pull/11))
  13 * [Actions support](#actions)
  14 * Extensible through [patches](https://github.com/dudik/herbe/pulls?q=is%3Aopen+is%3Apr+label%3Apatch)
  15
  16 ## Table of contents
  17
  18 * [Usage](#usage)
  19   * [Patches](#patches)
  20   * [Dismiss a notification](#dismiss-a-notification)
  21   * [Actions](#actions)
  22   * [Newlines](#newlines)
  23   * [Multiple notifications](#multiple-notifications)
  24   * [Notifications don't show up](#notifications-dont-show-up)
  25 * [Installation](#installation)
  26   * [Packages](#packages)
  27   * [Dependencies](#dependencies)
  28   * [Build](#build)
  29 * [Configuration](#configuration)
  30 * [Contribute](#contribute)
  31
  32 ## Usage
  33
  34 ### Patches
  35 [List of available patches](https://github.com/dudik/herbe/pulls?q=is%3Aopen+is%3Apr+label%3Apatch)
  36
  37 To create a new patch you'll have to open a pull request with your changes. Append `.diff` to the pull request URL to get a downloadable diff file. Don't forget to prefix the title with `patch:` and to apply the `patch` label to it. For inspiration, look at [my Xresources patch](https://github.com/dudik/herbe/pull/11). Thank you.
  38
  39 _Note: This patching method was heavily inspired by [dylan's sowm](https://github.com/dylanaraps/sowm)._
  40
  41 ### Dismiss a notification
  42 A notification can be dismissed either by clicking on it with `DISMISS_BUTTON` (set in config.h, defaults to left mouse button) or sending a `SIGUSR1` signal to it:
  43 ```shell
  44 $ pkill -SIGUSR1 herbe
  45 ```
  46 Dismissed notifications return exit code 2.
  47
  48 ### Actions
  49 Action is a piece of shell code that runs when a notification gets accepted. Accepting a notification is the same as dismissing it, but you have to use either `ACTION_BUTTON` (defaults to right mouse button) or the `SIGUSR2` signal.
  50 An accepted notification always returns exit code 0. To specify an action:
  51 ```shell
  52 $ herbe "Notification body" && echo "This is an action"
  53 ```
  54 Where everything after `&&` is the action and will get executed after the notification gets accepted.
  55
  56 ### Newlines
  57 Every command line argument gets printed on a separate line by default e.g.:
  58 ```shell
  59 $ herbe "First line" "Second line" "Third line" ...
  60 ```
  61 You can also use `\n` e.g. in `bash`:
  62 ```shell
  63 $ herbe $'First line\nSecond line\nThird line'
  64 ```
  65 But by default `herbe` prints `\n` literally:
  66 ```shell
  67 $ herbe "First line\nStill the first line"
  68 ```
  69 Output of other programs will get printed correctly, just make sure to escape it (so you don't end up with every word on a separate line):
  70 ```shell
  71 $ herbe "$(ps axch -o cmd:15,%cpu --sort=-%cpu | head)"
  72 ```
  73
  74 ### Multiple notifications
  75 Notifications are put in a queue and shown one after another in order of creation (first in, first out). They don't overlap and each one is shown for its entire duration.
  76
  77 ### Notifications don't show up
  78 Most likely a running notification got terminated forcefully (SIGKILL or any uncaught signal) which caused the semaphore not getting unlocked. First, kill any `herbe` instance that is stuck:
  79 ```shell
  80 $ pkill -SIGKILL herbe
  81 ```
  82 Then just call `herbe` without any arguments:
  83 ```shell
  84 $ herbe
  85 ```
  86 Notifications should now show up as expected.
  87
  88 Don't ever send any signals to `herbe` except these:
  89 ```shell
  90 # same as pkill -SIGTERM herbe, terminates every running herbe process
  91 $ pkill herbe
  92
  93 $ pkill -SIGUSR1 herbe
  94 $ pkill -SIGUSR2 herbe
  95 ```
  96 And you should be fine. That's all you really need to interact with `herbe`.
  97
  98 ## Installation
  99 ### Packages
 100 [![Packaging status](https://repology.org/badge/vertical-allrepos/herbe.svg)](https://repology.org/project/herbe/versions)
 101
 102 [OpenBSD patch](https://github.com/dudik/herbe/pull/4)
 103
 104 [FreeBSD patch](https://github.com/dudik/herbe/pull/16)
 105
 106 [Wayland port](https://github.com/muevoid/Wayherb) by [muevoid](https://github.com/muevoid)
 107
 108 **Only the [herbe-git AUR package](https://aur.archlinux.org/packages/herbe-git/) is maintained by me.**
 109
 110 ### Dependencies
 111 * X11 (Xlib)
 112 * Xft
 113
 114 The names of packages are different depending on which distribution you use.
 115 For example, if you use [Void Linux](https://voidlinux.org/) you will have to install these dependencies:
 116 ```shell
 117 sudo xbps-install base-devel libX11-devel libXft-devel
 118 ```
 119
 120 ### Build
 121 ```shell
 122 git clone https://github.com/dudik/herbe
 123 cd herbe
 124 sudo make install
 125 ```
 126 `make install` requires root privileges because it copies the resulting binary to `/usr/local/bin`. This makes `herbe` accessible globally.
 127
 128 You can also use `make clean` to remove the binary from the build folder, `sudo make uninstall` to remove the binary from `/usr/local/bin` or just `make` to build the binary locally.
 129
 130 ## Configuration
 131 herbe is configured at compile-time by editing `config.h`. Every option should be self-explanatory. There is no `height` option because height is determined by font size and text padding.
 132
 133 [Xresources patch](https://github.com/dudik/herbe/pull/11)
 134
 135 ## Contribute
 136 If you want to report a bug or you have a feature request, feel free to [open an issue](https://github.com/dudik/herbe/issues).
 137
 138 ## Projects with herbe integration
 139 - [qutebrowser](https://qutebrowser.org/) supports showing web notifications via herbe, via the `content.notifications.presenter` setting.