Durations

Taskwarrior supports duration values. In the core, durations are used directly in one place - the recur attribute, used for recurring tasks. For example, here is a recurring task that recurs every monday:

$ task add Take out the trash due:monday recur:weekly
The value monday is interpreted as 'next monday', and the value weekly is interpreted as a 7-day duration.

The other place where durations are supported directly is with UDA attributes of type duration.

Relative Date

There is indirect support for durations everywhere that a date value is expected. For example, here is a task due in two days:

$ task add Birthday party due:2days
Whenever Taskwarrior expects a date (due date in this example) but instead finds a duration, it is interpreted as a relative duration added to the current date/time, in this example now + 2days.

Duration Format

Example Meaning
5 seconds
5 second
5 secs
5 sec
5 s
5seconds
5second
5secs
5sec
5s
Five seconds.
second
sec
One second. Missing ordinal implies one second.
5 minutes
5 minute
5 mins
5 min
5minutes
5minute
5mins
5min
Five minutes.
minute
min
One minute. Missing ordinal implies one minute.
3 hours
3 hour
3 hrs
3 hr
3 h
3hours
3hour
3hrs
3hr
3h
Three hours.
hour
hr
One hour. Missing ordinal implies one hour.
2 days
2 day
2 d
2days
2day
2d
Two days.
daily
day
One day. Missing ordinal implies one day.
3 weeks
3 week
3 wks
3 wk
3 w
3weeks
3week
3wks
3wk
3w
Three weeks.
weekly
week
wk
One week. Missing ordinal implies one week.
weekdays
Every weekday, Monday to Friday.
2 fortnight
2 sennight
2fortnight
2sennight
Twenty eight days.
biweekly
fortnight
sennight
Fourteen days. Missing ordinal implies fourteen days.
5 months
5 month
5 mnths
5 mths
5 mth
5 mo
5 m
5months
5month
5mnths
5mths
5mth
5mo
5m
Five months.
monthly
month
mth
mo
30 days. Missing ordinal implies one month. This is an imprecise value.
bimonthly
Sixty one days. Missing ordinal implies two months. This is an imprecise value.
1 quarterly
1 quarters
1 quarter
1 qrtrs
1 qrtr
1 qtr
1 q
1quarterly
1quarters
1quarter
1qrtrs
1qrtr
1qtr
1q
Ninety one days.
quarterly
quarter
qrtr
qtr
Ninety one days. Missing ordinal implies three months. This is an imprecise value.
semiannual
One hundred and eighty three days. Missing ordinal implies six months. This is an imprecise value.
1 years
1 year
1 yrs
1 yr
1 y
1years
1year
1yrs
1yr
1y
One year.
annual
yearly
year
yr
Three hundred and sixty five days. Missing ordinal implies one year. This is an imprecise value.
biannual
biyearly
Seven hundred and thirty days. Missing ordinal implies two years. This is an imprecise value.

ISO-8601 Format

ISO-8601 defines a duration format which is supported by Taskwarrior. The format looks like this:

P[nY][nM][nD][T[nH][nM][nS]]

The format always begins with a 'P' (period). The date elements ([nY][nM][nD]) are optional, as are the time elements ([nH][nM][nS]), but there must be one element specified.

Even though the month and minute values use the character 'M', there is no ambiguity because of the placement of the character 'T' which delineates date from time elements.

Here is a list of examples:

Example Meaning
P3D Three days.
P1000D One thousand days.
P2M Two months. This is an imprecise value.
P2M3D Two months and three days. This is an imprecise value.
P1Y One year. This is an imprecise value.
P1Y3D One year and three days. This is an imprecise value.
P1Y2M One year and two months. This is an imprecise value.
P1Y2M3D One year, two months and three days. This is an imprecise value.
PT50S Fifty seconds.
PT40M Forty minutes.
PT40M50S Forty minutes and fifty seconds.
PT12H Twelve hours.
PT12H50S Twelve hours and fifty seconds.
PT12H40M Twelve hours and forty minutes.
PT12H40M50S Twelve hours, forty minutes and fifty seconds.
P1Y2M3DT12H40M50S One year, two months, three days, twelve hours, forty minutes and fifty seconds. This is an imprecise value.

Precise values include days, hours, minutes, seconds. Year and month are not precise because they vary, and can only be made precise if the duration is anchored to a known date.