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.
Then use any of these three methods:
- 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 ```
If you don't need the
todo-txt library and just want the
(introduced above and described in more detail below), download binaries from
For an overview, see the
--help following output. You can find more
information about the options in the next section.
usage: todoreport [ <option> ... ] [<args>] ... <option> is one of -g <specs>, --group-by <specs> Group specs -s <specs>, --sort-by <specs> Sort specs -o <specs>, --omit-fields <specs> Field omission 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. See https://github.com/todotxt/todo.txt/blob/master/README.md for the todo.txt format description. The "specs" arguments use a subset of the following field abbreviations: x completed pri or prio priority cod completion date ("co" for completion, "d" for date) crd creation date ("cr" for creation, "d" for date) desc description @ context (contexts are marked with @) + project (projects are marked with +) <key>: tag key, say, "due:" (tags are marked as key:value) Group and sort specs are of the form <order><field-abbreviation> , where <order> is "+" or "-" for ascending or descending order, respectively. <order> can be omitted, in which case ascending order is assumed. Several field abbreviations can be combined by separating them with commas (but NOT spaces after the commas), for example "x,pri". The valid field abbreviation subsets for the different specs are: Sort specs: x, pri, prio, cod, crd, desc Group specs: x, pri, prio, cod, crd, desc, @, +, <key>: Field omission specs: x, pri, prio, cod, crd, auto ("auto" means that field omissions are added from the group specs). The idea is that if you group by, say, priority, listing the priority for each task is redundant. Group specs example: pri,+ Group by ascending priority. Within each such group, group by ascending project name. Sort specs example: -due:,desc Sort first by descending due date. Sort tasks with the same due date by description in ascending order. Field omission specs example: x,crd For each task in the output, omit the completion status (the "x" prefix) and the creation date. As a special rule, omitting the creation date also omits the completion date. This is because only omitting the creation date might leave a completion date, but if there's a single date on a line, it's supposed to be the creation date! 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 +,due: -s pri,-crd,desc -o auto my_todo.txt another_todo.txt See the project website for more: https://git.sr.ht/~sschwarzer/todo-txt
todoreport will group the read tasks according to the
option, then inside each group, sort the tasks according to the
--sort-by option. The
--omit-fields option can exclude fields
from the task lines in the output.
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 also group by tags. For example, to group by due date, use
--group-by due: (note the trailing colon).
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 group specs and/or 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 use
--omit-fields to omit certain data from the output of
each task line. You can omit only simple fields, not fields like
projects or tags. That would be more complicated and may give odd
results. For example, imagine a task description "Fix bug in
+todo-txt", which would be turned into "Fix bug in".
Note that if you specify
crd (for the creation date), the completion
date will also be omitted. The reason is that if a task has both a
completion date and a creation date, removing only the creation date
would make the completion date appear as the creation date.
As a special case, you can use "auto" for
--omit-fields. The effect
is as if you had specified all the simple fields from
For example, if you use
--group-by pri,@ --omit-fields auto, the
task lines will omit the priority field.
If the above explanations still sound confusing, experiment with
different values for the
options. To see the effects of the options more clearly, your task
file should contain different data for the properties you group or
sort by. For example, to see the effect of grouping by priority, your
tasks should have different priorities. It's also helpful to have
tasks without the property, in the previous example tasks without a
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