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
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.
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.
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:
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,entry,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 tasksime 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.
Get Involved
Submit a bug
Clone the code
Monitor
System status
Operations Information
Related Sites
tasktools.org
holidata.net
Donate
Copyright © 2017 Göteborg Bit Factory