Taskwarrior supports a set of standard attributes for a task,
known as the core attributes. These include project
,
description
, due
and so on. There are
more than 20 standard attributes (see
columns
for a full list). They are necessary to provide all the
functionality of Taskwarrior. For example, the
project
attribute is used to provide feedback on
completion of a project, the projects
command itself,
and project hierarchy filtering. The project
attribute has a lot of functionality associated with it, and this
is why project
is a core attribute.
Other attributes, such as priority
do not have much
associated functionality. In fact, beyond storing the value,
allowing modification, sorting and inclusion in reports, the
priority
field contributes nothing. This is why
priority
is not really a core attribute, and will
be migrated out of the code and into configuration.
Occasionally people will ask for new attributes, because their
workflow includes more metadata than Taskwarrior supports. A very
common request is for an estimate
attribute, which
would store a scalar quantity of some kind, perhaps a number of
days, or large/medium/small. Until now, the answer to most of
these requests is to use tags or annotations to approximate the
storage of the metadata. Now we have UDAs to achieve this.
A UDA is a new metadata item that you define, and taskwarrior
faithfully stores, displays, and modifies. But that is the
extent of it, because Taskwarrior does not leverage it for
functionality like the project
attribute, but simply
treats it as a data value with a name, allowing you to sort by it,
use it in a report, import and export it.
It is intended that, once configured, a UDA is indistinguishable from core attributes, and will not impart performance penalties.
A UDA has a type, which may be one string
,
numeric
, date
or duration
.
If a UDA has type date
, then it will naturally only
accept date values, just like the core attribute due
.
The string
UDA type is special, in that a list of
acceptable values may also be provided, and taskwarrior will only
allow modifications if the new value is in the list.
A UDA is created by modifying configuration. There are two or
three configuration settings involved. Let's create an
estimate
UDA that is numeric:
$ task config uda.estimate.type numeric $ task config uda.estimate.label Est
That's all - but note there are three pieces of information there: first there is "estimate", which is the attribute name, then "numeric" which is the type, and finally "Est", which is the default label used when the UDA is included in a report. Now you can add or modify a task to include an estimate.
$ task add "Paint the door" project:Home estimate:4 ...
Now suppose you are developing software in an Agile environment.
You may wish to have a size
attribute that may
contain a fixed set of values, such as "large", "medium" or
"small". This is achieved using an additional configuration
setting:
$ task config uda.size.type string $ task config uda.size.label Size $ task config uda.size.values large,medium,small
Now if you attempt to store a value such as "tiny", taskwarrior will disallow it.
Default values may be defined. Continuing the example above, to
specify a medium
size default for each task, use
this setting:
uda.size.default=medium
This default value will be applied to any task that does not
otherwise have a size
value.
You can specify that a UDA contributes to the urgency calculation
of a task. As an example, the above size
UDA could
be given an urgency coefficient like this:
urgency.uda.size.coefficient=2.8
Then whenever a task has a non-trivial value in the
size
UDA, the urgency is boosted by 2.8.
To assign an urgency coefficient that has an empty value leave no space between the attribute and the coefficient. As an example, to match urgency to an empty priority, the coefficient can be assigned like this:
urgency.uda.priority..coefficient=2.5
Suppose you define an estimate
UDA and use it. Then
you remove the configuration for the UDA. You have just created
a situation where the data is stored, but is no longer something
that can be used in a report or a filter. This is an orphan UDA.
You might think this is an unusual situation, but it is exactly
what happens if you sync data with UDAs to a taskwarrior
installation that does not have the UDA configured. Data loss
would be unacceptable, so taskwarrior will preserve all orphan
UDA data, but will not let you manipulate it. Only defined UDAs
can be manipulated. There is one exception -
the edit
command will let you remove UDA orphans by
making their values blank, which eliminates any attribute.
UDA fields may be used in custom reports, just like any other attribute. A report containing an attribute that is an orphan UDA is not a valid report.
The priority
attribute is soon to be replaced by a
UDA equivalent. This is not something that anyone will notice,
but it will make for a smaller, more stable core product. UDAs
are useful for other capabilities though. An example would be the
import of bugs from a Request Tracker. The additional metadata
in the Request Tracker could be created as UDAs in taskwarrior,
which will then allow for a full import without data loss.