The API defined here is the [Hooks v2] API. This API is part of the TaskWarrior 2.4.3 release.
Command Line Arguments
To support an evolving Hooks API, Taskwarrior must provide hook scripts with a mechanism for determining which version of the Hooks API is providing the context for the script. It is anticipated that in future versions, new events will be added, and changes to the interfaces will occur. A hook script needs to act according to the API version, otherwise it risks incompatibility with Taskwarrior.
The interfaces define what is provided as standard input, and what is expected on standard output.
v2 there will also be command line arguments provided to the script.
A script may take advantage of the
v2 enhancements though, to extend its capabilities.
Here is a contrived example simulating how a hook script will be invoked:
$ ~/.task/hooks/on-xxx.yyy \ api:2 \ args:'task rc:~/mytaskrc list' \ command:add \ rc:/home/foo/mytaskrc \ data:/home/foo/.task \ version:2.4.3 \ <input.txt \ >output.txt
This information can be used by the script to see that an alternate
rc file was specified on the command line.
v2 API is identical, so any hook script will run unmodified in both scenarios.
This may not be true for future versions.
A script that requires
v2 but is run in a
v1 context should issue a warning that it is not able to perform its function, but it should not fail.