mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-07-07 20:06:36 +02:00
Update documentation for reports, new CLI
This is basically a redraft of the documentation to be more complete and better cover some of the features added since it was written.
This commit is contained in:
Dustin J. Mitchell
parent
b29f75a075
commit
8b4f345387
10 changed files with 189 additions and 85 deletions
|
|
@ -2,7 +2,12 @@
|
|||
|
||||
- [Welcome to TaskChampion](./welcome.md)
|
||||
- [Installation](./installation.md)
|
||||
- [Usage](./usage.md)
|
||||
* [Using the Task Command](./using-task-command.md)
|
||||
* [Configuration](./config-file.md)
|
||||
* [Reports](./reports.md)
|
||||
* [Synchronization](./task-sync.md)
|
||||
* [Running the Sync Server](./running-sync-server.md)
|
||||
* [Debugging](./debugging.md)
|
||||
- [Internal Details](./internals.md)
|
||||
- [Data Model](./data-model.md)
|
||||
- [Replica Storage](./storage.md)
|
||||
|
|
|
|||
42
docs/src/config-file.md
Normal file
42
docs/src/config-file.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
# Configuration
|
||||
|
||||
The `task` command will work out-of-the-box with no configuration file, using default values.
|
||||
|
||||
Configuration is read from `taskchampion.yaml` in your config directory.
|
||||
On Linux systems, that directory is `~/.config`.
|
||||
On OS X, it's `~/Library/Preferences`.
|
||||
On Windows, it's `AppData/Roaming` in your home directory.
|
||||
The path can be overridden by setting `$TASKCHAMPION_CONFIG`.
|
||||
|
||||
Individual configuration parameters can be overridden by environment variables, converted to upper-case and prefixed with `TASKCHAMPION_`, e.g., `TASKCHAMPION_DATA_DIR`.
|
||||
Nested configuration parameters such as `reports` cannot be overridden by environment variables.
|
||||
|
||||
## Directories
|
||||
|
||||
* `data_dir` - path to a directory containing the replica's task data (which will be created if necessary).
|
||||
Default: `taskchampion` in the local data directory.
|
||||
|
||||
## Sync Server
|
||||
|
||||
If using a local server:
|
||||
|
||||
* `server_dir` - path to a directory containing the local server's data.
|
||||
This is only used if `server_origin` or `server_client_key` are not set.
|
||||
Default: `taskchampion-sync-server` in the local data directory.
|
||||
|
||||
If using a remote server:
|
||||
|
||||
* `server_origin` - Origin of the TaskChampion sync server, e.g., `https://taskchampion.example.com`.
|
||||
If not set, then sync is done to a local server.
|
||||
* `encryption_secret` - Secret value used to encrypt all data stored on the server.
|
||||
This should be a long random string.
|
||||
If you have `openssl` installed, a command like `openssl rand -hex 35` will generate a suitable value.
|
||||
This value is only used when synchronizing with a remote server -- local servers are unencrypted.
|
||||
Treat this value as a password.
|
||||
* `server_client_key` - Client key to identify this replica to the sync server (a UUID)
|
||||
If not set, then sync is done to a local server.
|
||||
|
||||
# Reports
|
||||
|
||||
* `reports` - a mapping of each report's name to its definition.
|
||||
See [Reports](./reports.md) for details.
|
||||
9
docs/src/debugging.md
Normal file
9
docs/src/debugging.md
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
# Debugging
|
||||
|
||||
Both `task` and `taskchampion-sync-server` use [env-logger](https://docs.rs/env_logger) and can be configured to log at various levels with the `RUST_LOG` environment variable.
|
||||
For example:
|
||||
```shell
|
||||
$ RUST_LOG=taskchampion=trace task add foo
|
||||
```
|
||||
|
||||
The output may provide valuable clues in debugging problems.
|
||||
81
docs/src/reports.md
Normal file
81
docs/src/reports.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
# 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
|
||||
$ task
|
||||
Id Description Active Tags
|
||||
1 learn about TaskChampion +next
|
||||
2 buy wedding gift * +buy
|
||||
```
|
||||
|
||||
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 (`task 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` property.
|
||||
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
|
||||
* `sort` - how to order the tasks
|
||||
* `columns` - the columns of information to display for each task
|
||||
|
||||
The filter is a list of filter arguments, just like those that can be used on the command line.
|
||||
See the `task help` output for more details on this syntax.
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
reports:
|
||||
garden:
|
||||
filter:
|
||||
- "status:pending"
|
||||
- "+garden"
|
||||
```
|
||||
|
||||
The sort order is defined by an array of objects 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.
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
reports:
|
||||
garden:
|
||||
sort:
|
||||
- sort_by: description
|
||||
- sort_by: uuid
|
||||
ascending: false
|
||||
```
|
||||
If `ascending` is given, it can be `true` for the default sort order, or `false` for the reverse.
|
||||
|
||||
The available values of `sort_by` are
|
||||
|
||||
(TODO: generate automatically)
|
||||
|
||||
Finally, the configuration specifies the list of columns to display in the `columns` property.
|
||||
Each element has a `label` and a `property`:
|
||||
|
||||
```yaml
|
||||
reports:
|
||||
garden:
|
||||
columns:
|
||||
- label: Id
|
||||
property: id
|
||||
- label: Description
|
||||
property: description
|
||||
- label: Tags
|
||||
property: tags
|
||||
```
|
||||
|
||||
The avaliable properties are:
|
||||
|
||||
(TODO: generate automatically)
|
||||
8
docs/src/running-sync-server.md
Normal file
8
docs/src/running-sync-server.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
# Running the Sync Server
|
||||
|
||||
> NOTE: TaskChampion is still in development and not yet feature-complete.
|
||||
> The server is functional, but lacks any administrative features.
|
||||
|
||||
Run `taskchampion-sync-server` to start the sync server.
|
||||
Use `--port` to specify the port it should listen on, and `--data-dir` to specify the directory which it should store its data.
|
||||
It only serves HTTP; the expectation is that a frontend proxy will be used for HTTPS support.
|
||||
23
docs/src/task-sync.md
Normal file
23
docs/src/task-sync.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
# Synchronization
|
||||
|
||||
A single TaskChampion task database is known as a "replica".
|
||||
A replica "synchronizes" its local information with other replicas via a sync server.
|
||||
Many replicas can thus share the same task history.
|
||||
|
||||
This operation is triggered by running `task sync`.
|
||||
Typically this runs frequently in a cron task.
|
||||
Synchronization is quick, especially if no changes have occurred.
|
||||
|
||||
Each replica expects to be synchronized frequently, even if no server is involved.
|
||||
Without periodic syncs, the storage space used for the task database will grow quickly, and performance will suffer.
|
||||
|
||||
By default, TaskChampion syncs to a "local server", as specified by the `server_dir` configuration parameter.
|
||||
Every replica sharing a task history should have precisely the same configuration for `server_origin`, `server_client_key`, and `encryption_secret`.
|
||||
|
||||
Synchronizing a new replica to an existing task history is easy: begin with an empty replica, configured for the remote server, and run `task sync`.
|
||||
The replica will download the entire task history.
|
||||
|
||||
It is possible to switch a single replica to a remote server by simply configuring for the remote server and running `task sync`.
|
||||
The replica will upload the entire task history to the server.
|
||||
Once this is complete, additional replicas can be configured with the same settings in order to share the task history.
|
||||
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
# Usage
|
||||
|
||||
## `task`
|
||||
|
||||
The main interface to your tasks is the `task` command, which supports various subcommands.
|
||||
You can find a quick list of all subcommands with `task help`.
|
||||
|
||||
Note that the `task` interface does not match that of TaskWarrior.
|
||||
|
||||
### Configuration
|
||||
|
||||
The `task` command will work out-of-the-box with no configuration file, using default values.
|
||||
|
||||
Configuration is read from `taskchampion.yaml` in your config directory.
|
||||
On Linux systems, that directory is `~/.config`.
|
||||
On OS X, it's `~/Library/Preferences`.
|
||||
On Windows, it's `AppData/Roaming` in your home directory.
|
||||
The path can be overridden by setting `$TASKCHAMPION_CONFIG`.
|
||||
|
||||
Individual configuration parameters can be overridden by environment variables, converted to upper-case and prefixed with `TASKCHAMPION_`, e.g., `TASKCHAMPION_DATA_DIR`.
|
||||
Nested configuration parameters cannot be overridden by environment variables.
|
||||
|
||||
The following configuration parameters are available:
|
||||
|
||||
* `data_dir` - path to a directory containing the replica's task data (which will be created if necessary).
|
||||
Default: `taskchampion` in the local data directory.
|
||||
* `server_dir` - path to a directory containing the local server's data.
|
||||
This is only used if `server_origin` or `server_client_id` are not set.
|
||||
Default: `taskchampion-sync-server` in the local data directory.
|
||||
* `encryption_secret` - Secret value used to encrypt all data stored on the server.
|
||||
This should be a long random string.
|
||||
If you have `openssl` installed, a command like `openssl rand -hex 35` will generate a suitable value.
|
||||
This value is only used when synchronizing with a remote server -- local servers are unencrypted.
|
||||
Treat this value as a password.
|
||||
* `server_origin` - Origin of the TaskChampion sync server, e.g., `https://taskchampion.example.com`.
|
||||
If not set, then sync is done to a local server.
|
||||
* `server_client_id` - Client ID to identify this replica to the sync server (a UUID)
|
||||
If not set, then sync is done to a local server.
|
||||
|
||||
### Synchronization
|
||||
|
||||
A single TaskChampion task database is known as a "replica".
|
||||
A replica "synchronizes" its local information with other replicas via a sync server.
|
||||
Many replicas can thus share the same task history.
|
||||
|
||||
This operation is triggered by running `task sync`.
|
||||
Typically this runs frequently in a cron task.
|
||||
Synchronization is quick, especially if no changes have occurred.
|
||||
|
||||
Each replica expects to be synchronized frequently, even if no server is involved.
|
||||
Without periodic syncs, the storage space used for the task database will grow quickly, and performance will suffer.
|
||||
|
||||
By default, TaskChampion syncs to a "local server", as specified by the `server_dir` configuration parameter.
|
||||
Every replica sharing a task history should have precisely the same configuration for `server_origin`, `server_client_id`, and `encryption_secret`.
|
||||
|
||||
Synchronizing a new replica to an existing task history is easy: begin with an empty replica, configured for the remote server, and run `task sync`.
|
||||
The replica will download the entire task history.
|
||||
|
||||
It is possible to switch a single replica to a remote server by simply configuring for the remote server and running `task sync`.
|
||||
The replica will upload the entire task history to the server.
|
||||
Once this is complete, additional replicas can be configured with the same settings in order to share the task history.
|
||||
|
||||
## `taskchampion-sync-server`
|
||||
|
||||
Run `taskchampion-sync-server` to start the sync server.
|
||||
Use `--port` to specify the port it should listen on, and `--data-dir` to specify the directory which it should store its data.
|
||||
It only serves HTTP; the expectation is that a frontend proxy will be used for HTTPS support.
|
||||
|
||||
## Debugging
|
||||
|
||||
Both `task` and `taskchampio-sync-server` use [env-logger](https://docs.rs/env_logger) and can be configured to log at various levels with the `RUST_LOG` environment variable.
|
||||
For example:
|
||||
```shell
|
||||
$ RUST_LOG=taskchampion=trace task add foo
|
||||
```
|
||||
9
docs/src/using-task-command.md
Normal file
9
docs/src/using-task-command.md
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
# Using the Task Command
|
||||
|
||||
The main interface to your tasks is the `task` command, which supports various subcommands such as `add`, `modify`, `start`, and `done`.
|
||||
Customizable [reports](./reports.md) are also available as subcommands, such as `next`.
|
||||
The command reads a [configuration file](./config-file.md) for its settings, including where to find the task database.
|
||||
And the `sync` subcommand [synchronizes tasks with a sync server](./task-sync.md).
|
||||
You can find a list of all subcommands, as well as the built-in reports, with `task help`.
|
||||
|
||||
> NOTE: the `task` interface does not precisely match that of TaskWarrior.
|
||||
|
|
@ -3,7 +3,7 @@
|
|||
TaskChampion is a personal task-tracking tool.
|
||||
It works from the command line, with simple commands like `task add "fix the kitchen sink"`.
|
||||
It can synchronize tasks on multiple devices, and does so in an "offline" mode so you can update your tasks even when you can't reach the server.
|
||||
If you've heard of [TaskWarrior](https://taskwarrior.org/), this tool is very similar, but actively maintained and with a more reliable synchronization system.
|
||||
If you've heard of [TaskWarrior](https://taskwarrior.org/), this tool is very similar, but with some different design choices and greater reliability.
|
||||
|
||||
## Getting Started
|
||||
|
||||
|
|
@ -14,16 +14,16 @@ Once you've [installed TaskChampion](./installation.md), your interface will be
|
|||
Start by adding a task:
|
||||
|
||||
```shell
|
||||
$ task add "learn how to use taskchampion"
|
||||
$ task add learn how to use taskchampion
|
||||
added task ba57deaf-f97b-4e9c-b9ab-04bc1ecb22b8
|
||||
```
|
||||
|
||||
You can see all of your pending tasks with `task pending`, or just `task` for short:
|
||||
You can see all of your pending tasks with `task next`, or just `task` for short:
|
||||
|
||||
```shell
|
||||
$ task
|
||||
id act description
|
||||
1 learn how to use taskchampion
|
||||
Id Description Active Tags
|
||||
1 learn how to use taskchampion
|
||||
```
|
||||
|
||||
Tell TaskChampion you're working on the task, using the shorthand id:
|
||||
|
|
@ -49,13 +49,15 @@ $ task sync
|
|||
|
||||
Typically sync is run from a crontab, on whatever schedule fits your needs.
|
||||
|
||||
To synchronize multiple replicas of your tasks, you will need a sync server and a client ID on that server.
|
||||
To synchronize multiple replicas of your tasks, you will need a sync server and a client key for that server.
|
||||
Configure these in `~/.config/taskchampion.yml`, for example:
|
||||
|
||||
```yaml
|
||||
server_client_id: "f8d4d09d-f6c7-4dd2-ab50-634ed20a3ff2"
|
||||
server_client_key: "f8d4d09d-f6c7-4dd2-ab50-634ed20a3ff2"
|
||||
server_origin: "https://taskchampion.example.com"
|
||||
```
|
||||
|
||||
The next run of `task sync` will upload your task history to that server.
|
||||
Configuring another device identically and running `task sync` will download that task history, and continue to stay in sync with subsequent runs of the command.
|
||||
|
||||
See [Usage](./usage.md) for more detailed information on using TaskChampion.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue