Update `.build.yml`
Use `v0.5.0` for example repo tag
Swap installation sections in `README.md`
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
as
@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
Nested grouping is supported, too:
todoreport --group-by @,pri --sort-by -crd -o pri /path/to/todo.txt
gives
@home
A
2021-03-24 Work on +todoreport @home
C
2021-03-25 Do laundry @home
2021-03-23 Fix faucet @home
@work
A
2021-03-22 Call boss @work
No context
No priority
Read Racket Guide
todoreport
toolIf you don't need the todo-txt
library (see below) and just want the
todoreport
tool (introduced above and described in more detail below),
download binaries from https://releases.sschwarzer.net/todo-txt.
todo-txt
Racket libraryInstall Racket, if not already installed
https://download.racket-lang.org/ has up-to-date installation files. Linux distribution packages for Racket are often outdated.
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.5.0
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. 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://sr.ht/~sschwarzer/todo-txt
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 --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.
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).
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 --group-by
.
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 --group-by
, --sort-by
and --omit-fields
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
priority.
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