todo.txt files as specified at
https://github.com/todotxt/todo.txt and displays them, grouped and
sorted as specified on the command line.
For example, the command
todoreport --group-by @ --sort-by pri,-crd /path/to/todo.txt
on the command line will print the file
(C) 2021-03-23 Fix faucet @home (C) 2021-03-25 Do laundry @home (A) 2021-03-22 Call boss @work (A) 2021-03-24 Work on +todoreport @home Read Racket Guide
@home (A) 2021-03-24 Work on +todoreport @home (C) 2021-03-25 Do laundry @home (C) 2021-03-23 Fix faucet @home @work (A) 2021-03-22 Call boss @work No context Read Racket Guide
Install Racket, if not already installed
https://download.racket-lang.org/ has up-to-date installation files, but you can also install Racket with a package manager if you're using Linux/Unix.
On the command line, type
raco pkg install todo-txt
To install the tool from the Git repository, use
raco pkg install git+https://git.sr.ht/~sschwarzer/todo-txt#v0.1
possibly with a different tag. The
git+https protocol requires
at least Racket 8.1.
Clone the Git repo and from inside the Git working directory run
raco pkg install
For an overview, see the
todoreport [ <option> ... ] [<args>] ... where <option> is one of --group-by <spec>, -g <spec> : Group spec --sort-by <specs>, -s <specs> : Sort specs --help, -h : Show this help -- : Do not treat any remaining argument as a switch (at this level) Multiple single-letter switches can be combined after one `-'; for example: `-h-' is the same as `-h --' Read todo.txt files, rearrange them and print them. Group and sort specs are of the form <order><field-abbreviation> . <order> is "+" or "-" for ascending or descending order, respectively. <order> can be omitted, in which case ascending order is assumed. <field-abbreviation> is one of the following task fields to group or sort by: x completed pri or prio priority cod completion date crd creation date desc description @ context + project <key>: tag key, say, "due:" The last three can only be used in a group spec. Group spec example: -+ group by projects, listing project names in descending order Sort specs example: pri,-crd,+desc sort first by priority in ascending order (that is, higher priorities first); within one priority sort by descending creation date; within one creation date sort by ascending description After the options, specify one or more paths of todo.txt-format files. As a special case, if no file path is given, todoreport tries to get the path from the environment variable TODO_FILE . Example: todoreport -g + -s pri,-crd,desc my_todo.txt another_todo.txt
todoreport will group the read tasks according to the
option, then inside each group, sort the tasks according to the
The so-called group specs and sort specs consist of an order indicator (for ascending or descending order) and a task field to group/sort by. The abbreviations for the task fields follow the todo.txt format, if possible. For example, the "context" field is specified with "@" because contexts for tasks are written as "@home" or "@work". See the help output for how the task fields are written.
Since a task can have multiple contexts, it may appear in multiple groups if grouping by context. The same applies to grouping by project.
You can group by tags. For example, to group by due date, use
--group-by due: (note the trailing colon).
Currently, only one group spec is supported, but you can specify more than one sort spec.
If more than one sort spec is provided, the tasks in the groups are sorted first according to the first sort spec, then, for the same field value in the first sort spec, sorted according to the second sort spec, and so on. Check the example at the beginning of this file. In case of a tie (say, you sort only by priority and some tasks have the same priority), the original order from the file is kept.
Note that if you specify multiple sort specs, separate them with a comma, but don't put a space after the comma.
--sort-by options are optional. If neither
option is used, the tasks will be displayed in the order they appear
in the input file(s).
You can specify more than one file path. In this case,
will read the files in the given order and treat all tasks as if they
came from the same file. Empty lines in the files are ignored.
As a special case, if you don't specify any paths,
try to take the path of a todo.txt file from the environment variable
TODO_FILE. This is the same environment variable that the CLI tool
at https://github.com/todotxt/todo.txt-cli uses to find a default
You can view and enter tickets at https://todo.sr.ht/~sschwarzer/todo-txt .
If you want to contribute patches, you can generate them with
git format-patch (see https://git-scm.com/docs/git-format-patch ) and
attach them to a ticket. I recommend you first discuss your planned
changes in a ticket before investing time in a patch.
MIT license, see https://opensource.org/licenses/MIT