Reports

As a to-do list manager, listing tasks is an important TaskChampion feature. Reports are tabular displays of tasks, and allow very flexible filtering, sorting, and customization of columns.

TaskChampion includes several "built-in" reports, as well as supporting custom reports in the configuration file.

Built-In Reports

The next report is the default, and lists all pending tasks:

$ ta
Id Description              Active Tags              
1  learn about TaskChampion        +next
2  buy wedding gift         *      +buy
3  plant tomatoes                  +garden

The Id column contains short numeric IDs that are assigned to pending tasks. These IDs are easy to type, such as to mark task 2 done (ta 2 done).

The list report lists all tasks, with a similar set of columns.

Custom Reports

Custom reports are defined in the configuration file's reports table. This is a mapping from each report's name to its definition. Each definition has the following properties:

• filter - criteria for the tasks to include in the report (optional)
• sort - how to order the tasks (optional)
• columns - the columns of information to display for each task

For example:

[reports.garden]
sort = [
    { sort_by = "description" }
]
filter = [
    "status:pending",
    "+garden"
]
columns = [
    { label = "ID", property = "id" },
    { label = "Description", property = "description" },
]

The filter property is a list of filters. It will be merged with any filters provided on the command line when the report is invoked.

The sort order is defined by an array of tables containing a sort_by property and an optional ascending property. Tasks are compared by the first criterion, and if that is equal by the second, and so on. If ascending is given, it can be true for the default sort order, or false for the reverse.

In most cases tasks are just sorted by one criterion, but a more advanced example might look like:

[reports.garden]
sort = [
    { sort_by = "description" }
    { sort_by = "uuid", ascending = false }
]
...

The available values of sort_by are

• id

  Sort by the task's shorthand ID

• uuid

  Sort by the task's full UUID

• wait

  Sort by the task's wait date, with non-waiting tasks first

• description

  Sort by the task's description

Finally, the columns configuration specifies the list of columns to display. Each element has a label and a property, as shown in the example above.

The avaliable properties are:

• id

  The task's shorthand ID

• uuid

  The task's full UUID

• active

  * if the task is active (started)

• wait

  Wait date of the task

• description

  The task's description

• tags

  The task's tags