# 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](./config-file.md).

## Built-In Reports

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

```text
$ 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:

```toml
[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](./filters.md).
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:

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

The available values of `sort_by` are

<!-- INSERT GENERATED DOCUMENTATION - report-sort-by -->

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:

<!-- INSERT GENERATED DOCUMENTATION - report-columns -->