Group and sort todo.txt tasks
Update tickets URL
Fix program name in help output
Use cleaner structure for installation



You can also use your local clone with git send-email.



The tool todoreport reads 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 /path/to/todo.txt,

(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


  (A) 2021-03-24 Work on +todoreport @home
  (C) 2021-03-25 Do laundry @home
  (C) 2021-03-23 Fix faucet @home
  (A) 2021-03-22 Call boss @work
No context
  Read Racket Guide


  1. 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 --help output:

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 .
   todoreport -g + -s pri,-crd,desc my_todo.txt another_todo.txt

#Grouping and sorting

todoreport will group the read tasks according to the --group-by option, then inside each group, sort the tasks according to the --sort-by option.

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.

The --group-by and/or --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).

#File paths

You can specify more than one file path. In this case, todoreport 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, todoreport will 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 file.


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


Stefan Schwarzer