From f47054c4853ac1067e9fb923cb6ef143044c9cf4 Mon Sep 17 00:00:00 2001
From: Paul Beckingham <paul@beckingham.net>
Date: Sun, 7 Sep 2014 22:13:31 -0400
Subject: [PATCH] Hooks

- Added README describing the hook system.
- Corrected hook interface details regarding exit codes.
---
 scripts/hooks/README    | 26 ++++++++++++++++++++++++++
 scripts/hooks/on-add    |  8 ++++----
 scripts/hooks/on-exit   |  4 ++--
 scripts/hooks/on-launch |  8 ++++----
 scripts/hooks/on-modify |  8 ++++----
 5 files changed, 40 insertions(+), 14 deletions(-)
 create mode 100644 scripts/hooks/README

diff --git a/scripts/hooks/README b/scripts/hooks/README
new file mode 100644
index 000000000..e6955c5f8
--- /dev/null
+++ b/scripts/hooks/README
@@ -0,0 +1,26 @@
+Example Hook Scripts
+
+Hooks are supported in Taskwarrior 2.4.0 and later. Hooks require no
+configuration, and simply need to exist, in the expected location, with the
+expected name, with execute permission. If these conditions are met, the hook
+scripts will be run.
+
+Expected Location
+  The hooks scripts all reside in one location, which is in a 'hooks'
+  subdirectory, in your ~/.task (or rc.data.location override) directory.
+
+Expected Name
+  A hook scripts must be named according to which event triggers the script. A
+  script named 'on-add' will be triggered by a task add event. Multiple hook
+  scripts can coexist, and will all be run, in collating sequence. If there are
+  two scripts, named 'on-add-check-for-missing-priority' and 'on-add.x', they
+  are both executed, in the order shown here.
+
+Expected Permissions
+  A hook script must have execute permission for the user running taskwarrior,
+  otherwise it is skipped.
+
+Interface
+  Each hook script has a unique interface. This is documented in the example
+  scripts here.
+
diff --git a/scripts/hooks/on-add b/scripts/hooks/on-add
index c01280f20..350aec2d0 100755
--- a/scripts/hooks/on-add
+++ b/scripts/hooks/on-add
@@ -14,9 +14,9 @@ read new_task
 echo on-add
 
 # Exit:
-#   0 Means: - all emitted JSON lines are added/modified
-#            - all emitted non-JSON lines become footnote entries
-#   1 Means: - all emitted JSON lines are ignored
-#            - all emitted non-JSON lines become error entries
+#   0 Means:     - all emitted JSON lines are added/modified
+#                - all emitted non-JSON lines become footnote entries
+#   non-0 Means: - all emitted JSON lines are ignored
+#                - all emitted non-JSON lines become error entries
 exit 0
 
diff --git a/scripts/hooks/on-exit b/scripts/hooks/on-exit
index 95c5a0b6e..781f846f1 100755
--- a/scripts/hooks/on-exit
+++ b/scripts/hooks/on-exit
@@ -12,7 +12,7 @@
 echo on-exit
 
 # Exit:
-#   0 Means: - all emitted non-JSON lines become footnote entries
-#   1 Means: - all emitted non-JSON lines become error entries
+#   0 Means:     - all emitted non-JSON lines become footnote entries
+#   non-0 Means: - all emitted non-JSON lines become error entries
 exit 0
 
diff --git a/scripts/hooks/on-launch b/scripts/hooks/on-launch
index 783e2ecab..14218e993 100755
--- a/scripts/hooks/on-launch
+++ b/scripts/hooks/on-launch
@@ -13,9 +13,9 @@
 echo on-launch
 
 # Exit:
-#   0 Means: - all emitted JSON lines are added/modified
-#            - all emitted non-JSON lines become footnote entries
-#   1 Means: - all emitted JSON lines are ignored
-#            - all emitted non-JSON lines become error entries
+#   0 Means:     - all emitted JSON lines are added/modified
+#                - all emitted non-JSON lines become footnote entries
+#   non-0 Means: - all emitted JSON lines are ignored
+#                - all emitted non-JSON lines become error entries
 exit 0
 
diff --git a/scripts/hooks/on-modify b/scripts/hooks/on-modify
index f9db99dbe..0167d283d 100755
--- a/scripts/hooks/on-modify
+++ b/scripts/hooks/on-modify
@@ -16,9 +16,9 @@ read modified_task
 echo on-modify
 
 # Exit:
-#   0 Means: - all emitted JSON lines are added/modified
-#            - all emitted non-JSON lines become footnote entries
-#   1 Means: - all emitted JSON lines are ignored
-#            - all emitted non-JSON lines become error entries
+#   0 Means:     - all emitted JSON lines are added/modified
+#                - all emitted non-JSON lines become footnote entries
+#   non-0 Means: - all emitted JSON lines are ignored
+#                - all emitted non-JSON lines become error entries
 exit 0