.TH TODO 1 "2026-09-29" "todo 0.1.0" "User Commands"
.SH NAME
todo \- a little modal todo list
.SH SYNOPSIS
.B todo
.br
.B todo
.BR \-h | \-\-help
.br
.B todo
.BR \-v | \-\-version
.SH DESCRIPTION
.B todo
is an interactive todo list you drive like vim. It has modes: normal mode to
move around and act, insert mode to edit text, and a command line for
.BR : " and " /
commands. The list is stored as a plain text file you can also edit by hand or
from scripts.
.PP
The header shows the current date and time, localized through the environment.
Items sort so that unfinished ones stay above finished ones within each group,
and finished items are dimmed and struck through.
.PP
With the prose option enabled at build time (see
.IR config.h ),
item text is rewritten so its first letter is capitalized and it ends with a
period; sections and important
.RB ( ! )
items are capitalized but get no period. Text already capitalized or already
ending in
.BR . , " !" , " ?" , " ;" " or " :
is left as is. The change is to the text itself and is written to the file when
you save.
.PP
Nothing is written to disk until you save with
.BR :w .
.SH ITEMS
An item's kind is decided by how its text begins.
.TP
.I text
A plain task, shown with a checkbox and a number.
.TP
.BI = " name"
A section, shown as an uppercase roman heading
.RB ( I. ", " II. )
with its contents indented beneath it. Repeat the
.B =
for deeper levels
.RB ( == " is a subsection, shown as " i. ", " ii. ).
.TP
.BI \- " name"
A subtask of the task above it, indented further. A task is finished
automatically once all of its subtasks are done.
.TP
.BI * " name"
An optional task, shown with parentheses
.RB ( "( )" )
instead of a checkbox.
.TP
.BI > " text"
A note on the task above it: extra description, shown indented and dimmed with
no checkbox. Notes move with their task.
.TP
.BI ! " name"
An important task, shown bold and in capitals with the leading
.B !
kept and a trailing one added
.RB ( "!NAME!" ).
.PP
Within each section, items are grouped \(em required, then optional, then done
\(em with a blank line between the groups.
.PP
Each task carries one of three states, written in its checkbox:
.B [\ ]
todo,
.B [\-]
doing,
.B [x]
done.
.SH KEYS
.SS Movement
.TP
.BR h ", " j ", " k ", " l
Move: \fBh\fR/\fBl\fR move the cursor within the item, \fBj\fR/\fBk\fR by display
line, stepping through a wrapped item before moving to the next. Arrow keys work
too.
.TP
.BR 0 ", " $
Move the cursor to the start or end of the item.
.TP
.BR w ", " b
Move to the next or previous word.
.TP
.BR { ", " }
Jump to the previous or next section.
.TP
.BR gg ", " G
Jump to the top or bottom.
.TP
.I count
A leading number repeats the next motion or operator, e.g.\&
.BR 3j ", " 2dd .
.SS Editing
.TP
.B o
Add a new item below the cursor.
.TP
.B i
Enter insert mode at the cursor.
.TP
.B A
Append to the item's text.
.TP
.B R
Enter replace mode, overtyping characters from the cursor.
.TP
.B x
Delete the character under the cursor.
.TP
.BR cw ", " ce ", " cb ", " c0 ", " c$ ", " cc
Change over a motion: a word
.RB ( cw ", " ce ),
back a word
.RB ( cb ),
to the start
.RB ( c0 )
or end
.RB ( c$ )
of the line, or the whole line
.RB ( cc ).
A count applies, as in
.BR 2cw .
.TP
.BI ct c "\fR, \fP" cf c
Change the text up to the next
.IR c ,
then enter insert mode.
.B cf
deletes the
.I c
as well.
.TP
.BI ci d "\fR, \fP" ca d
Change the text inside
.RB ( ci )
or around
.RB ( ca )
the delimiter pair
.IR d ,
one of
.BR () ,
.BR [] ,
.BR {} ,
.BR <> ,
or a matching
.B \(dq
or
.BR ' .
If the cursor is before the pair, the next one on the line is used.
.TP
.B space
Cycle the item through todo, doing and done.
.TP
.B dd
Cut the item (also copies it for pasting). A task takes its subtasks and notes
with it.
.TP
.BR dw ", " de ", " db ", " d0 ", " d$ "\fR, etc.\fP"
Delete over a motion, leaving normal mode. The same motions and text objects as
.B c
apply
.RB ( dw ", " de ", " db ", " d0 ", " d$ ", " "dt\fIc\fP" ", " "df\fIc\fP" ", " "di\fId\fP" ", " "da\fId\fP" ),
with counts.
.TP
.B D
Remove every done item.
.TP
.BR yy ", " p ", " P
Yank the item, paste it below, or paste it above. A task carries its subtasks
and notes as one block.
.TP
.BR J ", " K
Move the item down or up. A task moves with its subtasks and notes; a section
heading moves the whole section.
.TP
.BR >> ", " <<
Demote or promote the item.
.B >>
turns a task into a subtask and deepens a section
.RB ( = " to " == );
.B <<
turns a subtask back into a task and shallows a section
.RB ( == " to " = ).
.TP
.B .
Repeat the last change, such as a
.BR dd ", " x ", " p ", " >> ", "
a state toggle, or an insert started with
.BR o ", " i ", " A ", or " c
through to the
.B escape
that ended it. The count is not repeated.
.SS "Visual mode"
.TP
.B V
Start a line-wise selection anchored at the cursor.
.B j
and
.B k
extend it. Then
.B d
cuts the selected items (also yanking them),
.B y
yanks them, and
.B space
cycles the state of each selected task.
.B escape
cancels.
.SS Folding
.TP
.BR za ", " zo ", " zc
Fold the section at the cursor:
.B za
toggles it,
.B zo
opens it, and
.B zc
closes it. A folded heading hides its contents and is marked as collapsed. Each heading
also shows a
.RB ( done / total )
count of the tasks within it.
.SS Other
.TP
.BR / ", " n ", " N
Search for text and jump to the match, placing the cursor on the word;
.B n
and
.B N
repeat forward and backward. Matches are highlighted as you type and stay
highlighted until the next search or until
.B escape
is pressed in normal mode.
.TP
.BR u ", " "ctrl-r"
Undo and redo.
.SH "INSERT MODE"
Type to insert at the cursor.
.B enter
commits the item and opens another below it;
.B escape
returns to normal mode, dropping the item if it is empty.
.B backspace
deletes, and the arrow keys move the cursor.
.SH COMMANDS
Press
.B :
to enter a command, then
.BR enter .
.B Tab
completes the command name, or the theme name after
.BR ":theme" .
.TP
.B :w
Write the list to its file.
.TP
.B :q
Quit. Refuses if there are unsaved changes.
.TP
.B :q!
Quit, discarding any unsaved changes.
.TP
.BR :wq ", " :x
Write and quit.
.TP
.BR :help ", " :?
Show the key bindings on screen; any key returns.
.TP
.B :reset
Set every item back to todo, clearing all done and doing states.
.TP
.B :clear
Remove every item, emptying the list.
.TP
.B :reorder
Re-sort the list, regrouping items (required, optional, done) within each
section. Useful after reordering or hand-editing.
.TP
.B :archive
Move every done item out of the list, appending it to the archive file. Unlike
.BR D ,
which discards them, this keeps a record you can revisit. The archive is itself
a valid list, so it can be opened with
.BR todo .
.TP
.BI :theme " name"
Switch the colour theme to
.I name
.RB ( default ", " gruvbox ", " nord ", " mono ", " light ", " custom );
with no name, cycle to the next.
.SH OPTIONS
.TP
.BR \-h ", " \-\-help
Print a usage summary and exit.
.TP
.BR \-v ", " \-\-version
Print the version and exit.
.SH FILES
.TP
.B ~/.todo.txt
The default list. Each line is a task
.RB ( "[ ] text" ", " "[-] text" ", " "[x] text" ),
a section
.RB ( "= name" ),
a subtask
.RB ( "- name" ),
an optional task
.RB ( "* name" ),
or a note
.RB ( "> text" ).
Override the location with
.BR $TODO_FILE .
.TP
.B ~/.todo.archive.txt
Where
.B :archive
appends done items. It is the list file's name with
.I .txt
replaced by
.IR .archive.txt ,
or the list file's name with
.I .archive
appended. Override it with
.BR $TODO_ARCHIVE .
.SH ENVIRONMENT
.TP
.B TODO_FILE
Path to the list file, used instead of
.BR ~/.todo.txt .
.TP
.B TODO_ARCHIVE
Path to the archive file for
.BR :archive ,
used instead of the name derived from the list file.
.TP
.B LC_TIME
Sets the locale for the date and time in the header.
.SH "EXIT STATUS"
.TP
.B 0
Success.
.TP
.B 1
The terminal could not be initialized, or memory ran out.
.SH AUTHOR
hachem <im@hachem.wtf>