.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.
.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 between
items. Arrow keys work too.
.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
Toggle the item between done and not done.
.TP
.B space
Cycle the item through todo, doing and done.
.TP
.B dd
Cut the item (also copies it for pasting).
.TP
.B D
Remove every done item.
.TP
.BR yy ", " p ", " P
Yank the item, paste it below, or paste it above.
.TP
.BR J ", " K
Move the item down or up. On a section heading this moves the whole section.
.SS Other
.TP
.BR / ", " n ", " N
Search for text, then jump to the next or previous match.
.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.
.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" ),
or an optional task
.RB ( "* name" ).
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>