feat: add plugins for zsh
This commit is contained in:
235
.zsh/zsh-auto-notify/README.rst
Normal file
235
.zsh/zsh-auto-notify/README.rst
Normal file
@@ -0,0 +1,235 @@
|
||||
ZSH Auto-Notify
|
||||
===============
|
||||
|
||||
|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:
|
||||
|
||||
* Usage_
|
||||
* Requirements_
|
||||
* Installation_
|
||||
* Configuration_
|
||||
* `Temporarily Disabling Notifications`_
|
||||
* Contributing_
|
||||
* `Running Tests`_
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
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
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
``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:
|
||||
|
||||
* Linux X/Wayland (Requires ``notify-send`` to be installed)
|
||||
* MacOSX
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
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-notify
|
||||
|
||||
|
||||
Then add this line to your ``.zshrc``. Make sure it is **before** the line ``source $ZSH/oh-my-zsh.sh``.
|
||||
|
||||
::
|
||||
|
||||
plugins=(auto-notify $plugins)
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
**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=20
|
||||
|
||||
**Notification 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 executed
|
||||
|
||||
An 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=10000
|
||||
|
||||
|
||||
**Ignored 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.png
|
||||
|
||||
|
||||
|
||||
Temporarily Disabling Notifications
|
||||
-----------------------------------
|
||||
|
||||
You 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``.
|
||||
|
||||
Contributing
|
||||
------------
|
||||
|
||||
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>`__
|
||||
|
||||
Running Tests
|
||||
-------------
|
||||
|
||||
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 commands
|
||||
|
||||
NOTE: 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
|
||||
Reference in New Issue
Block a user