@@ -31,12 +34,121 @@
Recurring Tasks
+ Task supports recurring tasks, which is a task that keeps falling due, on a
+ regular schedule. An example of this may be "pay rent". Here is how
+ recurring tasks work in task:
+ Ordinarily, a task is a single item that is entered in the pending state, and
+ remains so until it is either completed or deleted. This is an example of a
+ single instance task.
-
+
+ A recurring task is different. When a recurring task is entered, it remains
+ hidden from view, but acts as a root task for a task instances that are
+ generated on a regular basis. Consider the example:
+
+
+
% task Pay rent due:7/1/2008 recur:monthly
+
+
+ If today's date is 7/10, for example, then that due date is in the past, and
+ you might expect there to be an already overdue task for 7/1/2008, and another
+ due on 8/1/2008. This means that from that root, task has created two
+ instances with different due dates.
+
+
+
% task list
+
+ID Project Pri Due Active Age Description
+1 7/1/2008 1 min Pay rent
+2 8/1/2008 1 min Pay rent
+
+2 tasks
+
+
+ Task creates any overdue tasks, then creates one additional due task. These
+ new task instances are then completed or deleted as you normally would.
+
+
+
+ In the example above, a new task instance is created every month, and this will
+ repeat indefinitely. Task also supports an end date. Suppose you are taking
+ every Friday off work for the summer. You'll need to submit your TPS report on
+ Thursdays instead:
+
+
+
% task TPS report due:thursday recur:weekly until:8/31/2008
+
+
+ This create a weekly recurring task that expires on 8/31/2008. What this means
+ is that after all those task instances have been created, then completed or
+ deleted, the root task will expire and disappear. Task will tell you what it
+ is doing when this happens.
+
+
+
Deletion
+
+ When a recurring task is deleted, you will be asked if you would also like to
+ delete all recurring task instances:
+
+
+
% task del 1
+Permanently delete task? (y/n) y
+This is a recurring task. Do you want to delete all pending
+recurrences of this same task? (y/n) y
+
+
Recurrence Periods
+
+ In the above examples, the recurrence period was specified as "monthly" and
+ "weekly". Task supports several ways of specifying this:
+
+
+
+
+ | Period |
+ Meaning |
+
+
+ | daily, day, 1d, 2d ... |
+ Every day, or a number of days |
+
+
+ | weekly, 1w, 2w ... |
+ Every week, or a number of weeks |
+
+
+ | biweekly, fortnight |
+ Every two weeks |
+
+
+ | monthly, 1m, 2m ... |
+ Every month, or a number of months |
+
+
+ | bimonthly |
+ Every two months |
+
+
+ | quarterly, 1q, 2q ... |
+ Every three months, a quarter, or a number of quarters |
+
+
+ | semiannual |
+ Every six months |
+
+
+ | annual, yearly, 1y, 2y ... |
+ Every year, or a number of years |
+
+
+ | biannual, biyearly, 2y |
+ Every two-years |
+
+
+