Reports

Taskwarrior has three kinds of reports. There are built-in reports that cannot be modified, such as info and summary. There are built-in reports which can be redefined completely or eliminated, such as list, next. And finally there are your own custom reports. To generate a list of *all* the reports, use the reports command:

$ task reports

Report           Description
---------------- --------------------------------------------------
active           Active tasks
all              Pending, waiting and completed tasks by age
blocked          Lists all blocked tasks
blocking         Blocking (and blocked) tasks
burndown.daily   Shows a graphical burndown chart, by day
burndown.monthly Shows a graphical burndown chart, by month
burndown.weekly  Shows a graphical burndown chart, by week
completed        Completed tasks
ghistory.annual  Shows a graphical report of task history, by year
ghistory.monthly Shows a graphical report of task history, by month
history.annual   Shows a report of task history, by year
history.monthly  Shows a report of task history, by month
information      Shows all data and metadata
list             Actionable tasks by due date, project and urgency
long             All details of pending tasks by creation date
ls               Pending tasks sorted by description
minimal          Pending tasks by project and description
newest           The newest pending tasks
next             The top 7 most urgent actionable tasks
oldest           The oldest pending tasks
overdue          These task are late!
projects         Shows all project names used
ready            The most urgent actionable tasks
recurring        Repeating Tasks
summary          Shows a report of task status by project
tags             Shows a list of all tags used
unblocked        Lists all unblocked
waiting          Waiting tasks

28 reports

Built-In Static Reports

Typically a report consists of a table of data, with one row of data corresponding to a single task, with the task attributes represented as columns. But there are other reports which do not conform to this structure. Those are the built-in static reports, and they are not modifiable, because they are quirky and require custom code. These reports are:

burndown.daily
burndown.monthly
burndown.weekly
calendar
colors
export
ghistory.annual
ghistory.monthly
history.annual
history.monthly
information
summary
timesheet

Each of these reports takes non-standard arguments, may or may not support filters, and generates distinctive output.

Built-In Modifiable Reports

These reports are standard format, using standard arguments, and are also modifiable.

active
all
blocked
blocking
completed
list
long
ls
minimal
newest
next
oldest
overdue
ready
recurring
unblocked
waiting

Suppose you wanted to remove a column from one of these reports, for example removing tags from the minimal report. First look at the existing columns and labels of the minimal report:

$ task show report.minimal.labels

Config Variable       Value
--------------------- ---------------------------
report.minimal.labels ID,Project,Tags,Description

$ task show report.minimal.columns

Config Variable        Value
---------------------- ---------------------------------------
report.minimal.columns id,project,tags.count,description.count

Having determined what the current values are, simply override with the new values:

$ task config report.minimal.labels  'ID,Project,Description'
...
$ task config report.minimal.columns 'id,project,description.count'

You can think of the built-in modifiable reports as a set of default custom reports.

Custom Reports

Defining a custom report is straightforward. You have control over the data shown, the sort order and the column labels. A custom report is simply a set of configuration values, and those values include:

  • description
  • columns
  • labels
  • sort
  • filter

Let us quickly create a custom report, which will be named simple. This report will display the task ID, project name and description. We will need to gather the five settings listed above.

The description is the easiest, and in this case the report will be described:

Simple list of open tasks by project

This is just a descriptive label that will be used when the report is listed. Next we need to specify the columns in the report, and the order in which those are shown. Here the _columns helper command will show the columns available:

$ task _columns
depends
description
due
end
entry
foo
id
imask
mask
modified
parent
priority
project
recur
scheduled
start
status
tags
until
urgency
uuid
wait

That represents all the data that Taskwarrior stores, and therefore all the data that may be shown in a report. Our simple report will show id, project and description, which are all in the list. This means our column list is simply:

id,project,description

But there are also formats for each column, and the columns command shows them, with examples. Here are the formats for our three columns:

$ task columns id

Columns Supported Formats Example
------- ----------------- ------------------------------------
id      number*           123
uuid    long*             f30cb9c3-3fc0-483f-bfb2-3bf134f00694
        short             f30cb9c3

This is easy, because there is only one id format.

$ task columns project

Columns Supported Formats Example
------- ----------------- -------------
project full*             home.garden
        parent            home
        indented            home.garden

There are three formats for the project column, and the default, full is the one we want.

$ task columns description

Columns     Supported Formats Example
----------- ----------------- -----------------------------------------------------------------------------
description combined*         Move your clothes down on to the lower peg
                                2014-02-08 Immediately before your lunch
                                2014-02-08 If you are playing in the match this afternoon
                                2014-02-08 Before you write your letter home
                                2014-02-08 If you're not getting your hair cut
            desc              Move your clothes down on to the lower peg
            oneline           Move your clothes down on to the lower peg 2014-02-08 Immediately before ...
                              this afternoon 2014-02-08 Before you write your letter home 2014-02-08 If ...
            truncated         Move your clothes do...
            count             Move your clothes down on to the lower peg [4]

There are five formats for description. This time we prefer the count format, so our columns list is now:

id,project,description.count

Labels are the column heading labels in the report. There are defaults, but we wish to specify these like this:

ID,Proj,Desc

Sorting is also straightforward, and we want the tasks sorted by project, and then by entry, which is the creation date for a task. This illustrates that a task attribute that is not visible can be used in the sort. The sort order is then:

project+/,entry+

The + means an ascending order, but we could have used - for descending. The / solidus indicates that project is a break column, which means a blank line is inserted between unique values, for a visual grouping effect. 2.4.0

Finally we need a filter, otherwise our report will just display all tasks, which is rarely wanted. Here we wish to see only pending tasks, and that means the filter is:

status:pending

Now we have our report definition, so we just create the five configuration entries like this:

$ task config report.simple.description 'Simple list of open tasks by project'
$ task config report.simple.columns     'id,project,description.count'
$ task config report.simple.labels      'ID,Proj,Desc'
$ task config report.simple.sort        'project+/,entry+'
$ task config report.simple.filter      'status:pending'

And it is finished. Run the report like this:

$ task simple

ID Proj Desc
-- ---- -----------------
 1 Home Wash the windows
 3 Home Vacuum the floors

 2      Food shopping

Custom reports also show up in the help output.

$ task help | grep simple
task  sime                  Simple list of open tasks by project

I can inspect the configuration.

$ task show report.simple

Config Variable           Value
------------------------- ------------------------------------
report.simple.columns     id,project,description.count
report.simple.description Simple list of open tasks by project
report.simple.filter      status:pending
report.simple.labels      ID,Proj,Desc
report.simple.sort        project+/,entry+

Now the report is fully configured, it joins the others and is used in the same way.