|CircleCI| |Version| |GPLv3|
Simple zsh plugin that automatically sends out a notification when a long running task has completed.
Useful for those commands you don't predict will take long to run or just plain forgot
to keep track of. Leave the task running and go do something else - auto-notify will
let you know when the task is done! :tada:
Temporarily Disabling Notifications_Running Tests_You don't need to do anything. Once it's installed,
zsh-auto-notify will let you know if a long running task has completed its work via a
notification in your desktop environment.
.. image:: img/notification-example.png
auto-notify officially supports zsh versions 5.1 onwards.
It is possible the plugin might work on even older versions. However they would not have been tested as part of the CI test process.
Supported desktop environments:
notify-send to be installed)Add one of the following to your .zshrc file depending on your
package manager:
ZPlug_
::
zplug "MichaelAquilina/zsh-auto-notify"Antigen_
::
antigen bundle "MichaelAquilina/zsh-auto-notify"Zgen_
::
zgen load "MichaelAquilina/zsh-auto-notify"Fig_
Install zsh-auto-notify with Fig in just one click.
.. image:: https://fig.io/badges/install-with-fig.svg :target: https://fig.io/plugins/other/zsh-auto-notify_MichaelAquilina :alt: Install with Fig
oh-my-zsh_
Copy this repository to $ZSH_CUSTOM/custom/plugins, where $ZSH_CUSTOM
is the directory with custom plugins of oh-my-zsh (read more) <https://github.com/robbyrussell/oh-my-zsh/wiki/Customization/>_:
::
git clone https://github.com/MichaelAquilina/zsh-auto-notify.git $ZSH_CUSTOM/plugins/auto-notifyThen add this line to your .zshrc. Make sure it is before the line source $ZSH/oh-my-zsh.sh.
::
plugins=(auto-notify $plugins)Notification Threshold
By default, auto-notify will send notifications for tasks that take longer than 10 seconds. You
can configure this value by setting the environment variable AUTO_NOTIFY_THRESHOLD:
::
# Set threshold to 20seconds
export AUTO_NOTIFY_THRESHOLD=20Notification Formatting
You can change the formatting of notifications by setting the values for AUTO_NOTIFY_TITLE and
AUTO_NOTIFY_BODY. When writing these values, the following variables will be replaced according to
the data that auto-notify has detected:
%command - the command that the user executed%elapsed - number of seconds that elapsed%exit_code - the exit code of the command that was executedAn example of how these values can be set is shown below:
::
export AUTO_NOTIFY_TITLE="Hey! %command has just finished"
export AUTO_NOTIFY_BODY="It completed in %elapsed seconds with exit code %exit_code"Notification Expiration Time
You can set how long a notification sent by auto-notify will remain showing by setting the environment
variable AUTO_NOTIFY_EXPIRE_TIME to a custom value in milliseconds. The default value is set to 8 seconds.
NOTE: This configuration option currently only works for Linux.
::
# Set notification expiry to 10 seconds
export AUTO_NOTIFY_EXPIRE_TIME=10000Ignored Commands
A number of commands do not get notifications for long running times due to their nature (e.g. watch or man).
The list of ignored commands is specified in the AUTO_NOTIFY_IGNORE environment variable. This can be modified
or completely overwritten based on your use case.
::
# Add docker to list of ignored commands
AUTO_NOTIFY_IGNORE+=("docker")Make sure that you append to the array above after your plugin manager has been loaded in your zshrc.
If you wish to completely redefine what is ignored and not ignored, then just set AUTO_NOTIFY_IGNORE to
a new array.
::
# redefine what is ignored by auto-notify
export AUTO_NOTIFY_IGNORE=("docker" "man" "sleep")Using a Whitelist to ignore commands
If you wish to use a whitelist approach instead of the default blacklist approach used by AUTO_NOTIFY_IGNORE,
you can do so by defining the environment variable AUTO_NOTIFY_WHITELIST with the elements you wish to
allow auto-notify to track and send notifications for. NOTE: If AUTO_NOTIFY_WHITELIST is defined,
then all the values in AUTO_NOTIFY_IGNORE are not used.
::
export AUTO_NOTIFY_WHITELIST=("apt-get" "docker")Adding an icon - Linux
If you wish to have an icon displayed on command success and/or failure, you can do so by defining the environmental variables AUTO_NOTIFY_ICON_SUCCESS and AUTO_NOTIFY_ICON_FAILURE respectively.
::
export AUTO_NOTIFY_ICON_SUCCESS=/path/to/success/icon.png
export AUTO_NOTIFY_ICON_FAILURE=/path/to/failure/icon.pngYou can temporarily disable auto notify by running the command disable_auto_notify.
When you want to re-enable notifications, run the command enable_auto_notify.
Pull requests and Feedback are welcome! :tada:
I have tried to cater for as many use cases that I can think of. However, they are naturally tailored to to my own workflow and I could be missing many others.
Because of this if there is a specific use case that does not work as
you would expect or if you have any suggestions to how the plugin should
behave, feel free to open an issue <https://github.com/MichaelAquilina/zsh-auto-notify/issues/new>__
Install zunit <https://zunit.xyz/>__. Run zunit in the root
directory of the repo.
::
$ zunit
Launching ZUnit
ZUnit: 0.8.2
ZSH: zsh 5.3.1 (x86_64-suse-linux-gnu)
✔ version exported
✔ hook functions are loaded by default
✔ enable/disable auto-notify
✔ auto-notify-send does not send notification for short task
✔ auto-notify-send does not send notification for ignored commandsNOTE: It is required that you use a minimum zunit version of 0.8.2
.. _Zplug: https://github.com/zplug/zplug
.. _Antigen: https://github.com/zsh-users/antigen
.. _ZGen: https://github.com/tarjoilija/zgen
.. _Fig: https://fig.io
.. _oh-my-zsh: https://github.com/robbyrussell/oh-my-zsh
.. |GPLv3| image:: https://img.shields.io/badge/License-GPL%20v3-blue.svg :target: https://www.gnu.org/licenses/gpl-3.0
.. |CircleCI| image:: https://circleci.com/gh/MichaelAquilina/zsh-auto-notify.svg?style=svg :target: https://circleci.com/gh/MichaelAquilina/zsh-auto-notify
.. |Version| image:: https://badge.fury.io/gh/MichaelAquilina%2Fzsh-auto-notify.svg :target: https://badge.fury.io/gh/MichaelAquilina%2Fzsh-auto-notify