Package: tw-hooks
Taskwarrior HooksDescriptionThis is a collection ofTaskwarrior
hooksthat I use in my
day-to-day workflows. It comes along a detection and easy-registration mechanism
that should make it easy to develop and then distribute your own hooks. The
hooks are structured as classes under thetw_hooks/hooksdirectory.InstallationInstall it fromPyPI:pip3install--user--upgradetw_hooksTo get the latest version install directly from source:pip3install--user--upgradegit+https://github.com/bergercookie/tw-hooksAfter the installation, you have to run theinstall-hooks-shimsexecutable
(which by this point should be in your$PATH). Running it will create shims
(thin wrapper scripts) under~/.task/hooksin order to register all the hooks
with Taskwarrior.Available hooksCurrently the following hooks are available out-of-the-box:HookDescriptionEventsAutoTagBasedOnTagsInspect the list of tags in the added/modified tasks provided and add additional tags if requiredon-modify,on-addCorrectTagNamesChange tag names based on a predefined lookup tableon-modify,on-addDetectMutuallyExclusiveTagsSee whether the user has specified an incompatible combination of tagson-modify,on-addPostLatestStartToI3StatusWhen a task is started, send the title of the task to i3status-rs via DBuson-modifyWarnOnTaskCongestionWarn the user if there are too many tasks (due:today)on-exitStructure of a HookThe purpose of this package is to facilitate the development and distribution of
Taskwarrior hooks. To this purposeinstall-hooks-shimsallows you to easily
register your own hooks, without having to manually copy items over to the
taskwarrior hooks location.install-hooks-shimswill install a shim which will
call your hook automatically when required.This is an example of a Taskwarrior hook that will be executed on Taskwarrior
exit:fromtw_hooksimportOnExitHookclassWarnOnTaskCongestion(OnExitHook):"""Warn the user if there are too many tasks."""def_on_exit(self,_):# <--- Mandatory to implement this signature# ...return0Assuming that this hook is in a module calledwarn_on_task_congestion.pyand
that the directory of this module is in your python path (e.g., by adding it
explicitly to$PYTHONPATH), then you can run the following to register your
hook with taskwarrior:install-hooks-shims-rwarn_on_task_congestionDuring your next Taskwarrior operation, if there are too many due:today tasks,
you should see something like this:tadd+testkalimera
Createdtask719.[WarnOnTaskCongestion]Toomanydue:todaytasks[threshold=9]Hooks APISubclass one of the following base hooks, and your method is going to be called
during that event:OnAddHookImplement the_on_add(self, added_task: TaskT)method.OnExitHookImplement the_on_exit(self, added_modified_tasks: List[TaskT])method.OnLaunchHookImplement the_on_launch(self)method.OnModifyHookImplement the_on_modify(self, original_task: TaskT, modified_task: TaskT)method.Usage instructions forinstall-hooks-shimsusage:DetectTaskwarriorhooksandregisteranexecutableshimforeachoneofthem.[-h][-tTASK_DIR][-a][-l][-rREGISTER_ADDITIONAL[REGISTER_ADDITIONAL...]]optionalarguments:-h,--helpshowthishelpmessageandexit-tTASK_DIR,--task-dirTASK_DIRPathtothetaskwarriormaindirectory-a,--all-hooksInstallshimsforallthehooks-l,--list-hooksListtheavailablehooksandexit-rREGISTER_ADDITIONAL[REGISTER_ADDITIONAL...],--register-additionalREGISTER_ADDITIONAL[REGISTER_ADDITIONAL...]Usageexamples:===============-InstallonlytheWarnOnTaskCongestionhook(assumingyou've installed tw_hooks with e.g., pip3)install-hook-shims-rtw_hooks.hooks.warn_on_task_congestion-Installalltheavailablehooksfromthisrepo(assumingyou've installed tw_hooks with e.g., pip3)install-hook-shims--all-hooks-Installacustomhookdefinedin.../dir/mod/hook_name.py."dir"shouldbeinyourPYTHONPATHinstall-hook-shims-rmod.hook_name-Listalltheavailablehooksandexitinstall-hook-shims--list-hooksMiscellaneousContributing GuideFAQWhy should I use this over raw taskwarrior hooks?Because this package does the heavy lifting pre-processing the input tasks
from the command line. It does so in a robust manner making sure it does
the right thing regardless of weather one or two commands are provided and
being robust to errors (e.g.,utf-8decoding errors).It takes care to make the hooks fail safely even if it can't find required
modules (e.g., if you try invokingtaskfrom inside avirtualenvwheretw-hooksis not importable.It gives you a class-oriented approach and lets you install multiple hooks
from the same class, thus allowing these hooks to share common
configuration.It allows you to keep all your hooks together and keep
them as a package in some other place in your filesystem, e.g., in your
dotfiles and automatically adds the right glue-code so that Taskwarrior your
scripts without having to explicitly place it in~/.task/hooksor
symlinking it.Self PromotionIf you find this tool useful, pleasestar it on
Githuband consider donating.SupportIf something doesn't work, feel free to open an issue. You can also find me in
the#taskwarrior Libera Chat.TODO ListSeeISSUES
listfor the things that I'm currently either working on or interested in
implementing in the near future. In case there's something you are interesting
in working on, don't hesitate to either ask for clarifications or just do it and
directly make a PR.