(T)O (D)O → td

td is a simple, fully POSIX-compliant shell script to manage simple markdown-based todo files directly from your terminal

• Goals: Keep it short, simple, and POSIX-compliant
• Non-Goals: Adding extensive features

Installation

To use td, you only need to set the environment variable TD to a writable directory. This directory will store your markdown-formatted todo files.

You should also add the td script to your executable path (e.g., /usr/local/bin or ~/.local/bin) to conveniently call it from anywhere.

For nicer todo rendering, td optionally supports mdcat.

Anatomy of a todo file

Each todo file includes a header with a timestamp (YYMMDD) and a markdown-styled task list, e.g.:

Todos                                                                     250430
================================================================================

- [x] Summer time -> Fetch balcony table from basement
- [ ] 12:00 Reserve dinner table for dinner with friends
- [ ] Go shopping
    - [x] Baby stuff
    - [ ] Groceries
    - Don't forget to buy milk!
- [w] Complete the report
    - [ ] Add explanation for the financial usage
    - [w] Supervisor to review and refine

Task states:

• [ ] Open
• [x] Done
• [w] Waiting

Usage

• td -T or simply td: Displays the current day's todo file (using mdcat if installed, otherwise cat)
• td -eT: Creates a new todo file for the current day or opens the existing one for editing ($EDITOR or default vi).
• td -t YYMMDD: Displays a specific todo file identified by date.
• td -et YYMMDD: Creates a new todo file for the specified day or opens the existing one for editing.

Todo Migration

An important feature of td is the migration of incomplete tasks. When moving to a new todo file, td prompts you on each top-level task marked as open [ ] or waiting [w] and all their subtasks & notes.

Options during migration prompts

• y: Migrate task to the new todo file
• n: Leave the task in the old todo file
• x: Mark task as done in the old todo file
• r: Remove task from the old todo file

Example Migration:

- [ ] 12:00 Reserve dinner table for dinner with friends
- [ ] Go shopping
    - [x] Baby stuff
    - [ ] Groceries
    - Don't forget to buy milk!
- [w] Complete the report
    - [ ] Add explanation for the financial usage
    - [w] Let supervisor review and refine