Taskwarrior virtual tag logic

23 Mar 2021 | all notes

Information about this is a bit scattered in the Taskwarrior docs, but the two main sources are:

The information below is what I figured out by trial and error (using taskwarrior 2.5.3).

Mandatory virtual tag sets

Task status

The following 4 virtual tags are mutually exclusive, and any task will have exactly one of them:

COMPLETED (has an end date)
DELETED (has an end date)
WAITING (has a wait date. the wait entry is automatically removed when the wait date is reached)
PENDING for any task for which none of the above apply (INCOMPLETE would’ve been a more intuitive label tbh) It’s noteworthy that both PENDING and WAITING tasks can be assigned ACTIVE! Only completed and deleted tasks cannot be started.

(There is also the RECURRING tag for recurring events which is not covered here.)

Task dependencies

The following 2 virtual tags are mutually exclusive, and any task will have exactly one of them:

BLOCKED if there is at least one incomplete(?) depending task
UNBLOCKED otherwise

TODO what are the conditions for a BLOCKING task?

Optional virtual tags

Task readiness

SCHEDULED if the task has a scheduled date, whether it is in the past or the future. Note that this virtual tag is not mutually exclusive with:
READY if the task is both PENDING and UNBLOCKED and has either no scheduled date or the scheduled date is in the past

Task activeness

ACTIVE if the task has a start date

Both the start date (and with it the virtual tag) are removed when a task is completed or deleted. However, a currently active task maintains its ACTIVE state when it is assigned a wait date (and thus changes to a WAITING task status).

Task dueness

Like with ACTIVE, all of the following tags are only applied to PENDING and WAITING tasks.

When a task has a due date it is given the following virtual tags if the due date is within the same named time unit as ‘now’ independently of whether the actual due date is in the past or the future from now: YEAR, QUARTER, MONTH, WEEK, TOMORROW, TODAY, DUETODAY (not sure what’s the difference there?), YESTERDAY

There are also two mutually exclusive tags:

OVERDUE if the due date is in the past
DUE if the due date lies between ‘now’ and midnight 6 days from now

Task expiry

Any task with an until date carries the UNTIL virtual tag, which seems to not interact with the any of the other tags. Upon reaching the until date, the task is automatically deleted (not sure what happens with the until date or the tag at this point).