.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
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.
.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
.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.
.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 :
.TP
.B :w
Write the list to its file.
.TP
.B :q
Quit, discarding changes since the last write.
.TP
.BR :wq ", " :x
Write and quit.
.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.
.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 .
.SH ENVIRONMENT
.TP
.B TODO_FILE
Path to the list file, used instead of
.BR ~/.todo.txt .
.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>