TTDL (Terminal ToDo List)

A CLI tool to manage todo lists in (todo.txt format)[http://todotxt.org/]. A short demo of TTDL in action:

Configuration

TTDL is a standalone binary and it does not create any files in user's directory. But at start, it checks for a configuration file - please see example configuration (ttdl.toml)[./ttdl.toml] in user's configuration directory and loads it. Local configuration files are supported as well. Locations where TTDL looks for a configuration file:

• current working directory
• Linux: ~/.config/ttdl.toml
• Windows: c:\Users{username}\AppData\Roaming\ttdl.toml
• OSX: /Users/{username}/Library/Preferences/ttdl.toml

First, TTDL looks for a configuration file in the current working directory. And only if it does not contain ttdl.toml, the application looks for its configuration file in user's directory.

The configuration file contains options that cannot be set in command line:

• colors for special kinds of todos: overdue, due today, due soon, top priority, high priority, and completed
• ranges for cases "due soon" and "high priority". By default both option are disabled. To enable "due soon", set it to the number of days, so todos that are due in equal to or less than that number(except overdue and due today todos) will be displayed with soon color. To enable high priority highlight, set important to a priority - all todos with this priority or higher(except top priority ones) will be displayed with important color.
• filename - the path to global todo file (can point to directory, TTDL adds todo.txt automatically if filename is a directory). To override the option, you can set environment variable TTDL_FILENAME or use command line option --local if you need to load todo list from current working directory
• creation_date_auto The option defines TTDL behavior when a new todo is added. By default, TTDL adds a todo as is - a user must set manually creation date in the subject. Setting creation_date_auto to true makes TTDL to set today as creation date for all new todos if their subject does not include creation date.

How to use

Run TTDL with the command line:

ttdl [command] [ID range] [subject] [filter options] [extra options]

Options can be at any position. ID range and subject are optional but if you are going to use both, ID range must go first.

If a non-option starts with + or @, the option is considered as a filter by project or context respectively. Command line can contain as many projects and contexts as needed. In this case, all items of the same group are combined with OR. Example: if you execute ttdl list +myproj +demo @docs, it displays all todos that belongs to either myproj or demo, and have docs context.

If the first non-option word contains only digits and dash character, it is treated as a single ID(only digits) or ID range(digits with a dash). ID is 1-based: a number between 1 and the number of todos in the entire list. It is OK to use ID out of that range: IDs that greater than the number of todos or lower than 1 are skipped. So, e.g, if you want to remove all todos starting from 10th todo, you can run the command ttdl remove 10-999999 -a - -a to delete both completed and incomplete todos.

The second non-option(or the first one if ID range is not defined) is a subject. Subject's usage depends on command:

• add - it is an entire text for a new todo (including projects, contexts, due date, recurrence);
• edit - it is an entire new subject for the first selected todo;
• for the rest commands it can be either a substring(case-insensitive search) or a regular expression to search in the todo's subject, projects, and contexts - depends on the option --regex.

NOTES:

1. All dates are entered and displayed in format - YYYY-MM-DD(4 year digits - 2 month digits - 2 day digits)
2. Recurrence is defined in format 'the number of intervals' + 'interval type' without a space between them. Interval type is one of d - days, w - weeks, m - months, y - years. Example: to add a todo with your friend's birthday(;et's assume it is 10 of April) use the following command ttdl add "best friend birthday due:2019-04-10 rec:1y". After the birthday passes, just execute ttdl done <todo-ID> and it will change its due date to 2020-04-10
3. Recurrence special case: if you set due date to the last day of a month and interval is a month or longer then the next due date will always be the end of the months. Example: a todo pay credit due:2019-02-28 rec:1m after executing ttdl done ID turns into pay credit due:2019-03-31

Output example

# D P Created    Finished   Due        Threshold  Subject
----------------------------------------------------
1 x A 2016-04-30 2016-05-20                       measure space for +chapelShelving @chapel
2   C 2016-05-20                                  paint +chapelShelving @shelve
3 R                         2018-11-11            pay credit card rec:1m
----------------------------------------------------
3 todos (of 3 total)

Columns:

• # - order number of a todo
• D - 'Done', it is empty for an incomplete regular todo, 'x' for a completed todo, and 'R' for recurrent todo
• P - priority (from A to Z, empty value means no priority)

Archive

In the long run e a todo list gets full of completed tasks. They may slow down the todo list management. If you do not need to keep completed stuff, you can delete them using command remove. But if completed tasks must be kept for a while, you can archive them. Execute clean(or archive) command and completed tasks will be moved from the actual todo list to its archive.

Archiving completed todos makes the actual todo list loading faster. Though it has a few drawbacks:

• archived todos cannot be modified (e.g, if you want to delete some archived todos, you have to do it manually in any text editor)
• there is no way to show actual and archived todos at the same

How to show archived todos

To display archived todos, use option --done. The option enables "archive" mode: the only available command in this mode is list and TTDL loads done.txt instead of todo.txt. On entering this mode, the option -A is enabled automatically if neither -a nor -A is defined.

Supported commands

The list of available command is short but the commands are powerful. All commands support group operations and dry run mode. Except add command that adds a new todo one at a time. Please, refer to section "Examples", it provides a handful of useful examples of how to filter and modify todo list.

Commands:

• add - add a new todo;
• list - show list of todo items. By default it displays all incomplete todos;
• done - mark selected todos completed. If a todo is recurrent its due date moves to the next date but the todo remains incomplete;
• undone - remove finished mark from completed todos;
• remove - deletes the selected todos;
• clean - moves completed todos from main file to done.txt. The file done.txt is created(if it does not exist) in the same directory where main todo list file is located;
• edit - modify one or few properties for the selected todos. One exception: modifying todo's subject changes only the first selected todo, others are skipped.

Most of the commands can be abbreviated. Please refer to built-in TTDL help to get a list of full command names and their aliases.

NOTE: done moves a recurrent todo's due date to the next one, but it does not check if the new due date is in the future (it is by design). So, if a monthly task is 2 months overdue, you have to execute ttdl done ID two times to push it to the incoming month or manually set a new due date with the command ttdl edit ID --set-due=YYYY-MM-DD.

Tags

The orginal todo.txt format describes a user-defined tags that can be used by any application for special needs. The format of a tag is tag_name:tag_value. The original format does not specify any tag - all are considered custom ones.

TTDL supports a few custom tags (as of version 0.3):

• due - a todo's due date. The tag value is in format YYYY-MM-DD;
• t - a todo's theshold date. The tag value is in format YYYY-MM-DD;
• rec - makes a todo recurrent. It makes sense only when using along with due tag. The tag value is the number of time intervals and one-character time interval name: d - every few days, w every few weeks, m - every few months, y - every few years. Examples: 1w - a weekly todo, 5d - every 5 days.

Extra features

Each command that modifies todo list supports dry run mode. The mode is enabled with an option --dry-run. When executing ttdl with the option, it finds out which todos would be changed after the command completes, then displays existing todos and their new values.

By default TTDL outputs the todo list in long mode and uses colors. To disable colors, use an option --no-colors. To make the output shorter, use an option --short to show only a few the most important fields(ID, comlpetion mark, priority, and subject), or choose which fields to display with an option --fields: a comma-separated list of fields. NOTE: the option --fields defines only a field visibility, but not its order. So, --fields=pri,due and --fields=due,pri result in the same output.

For easier reading due date, there is an option --human that turns dates into relative dates. So, due date 2018-11-11 can turn into in 3d (if the current date is 2018-11-08) or into 3d overdue(if the current date is 2018-11-14). Using an option --compact makes the output even shorter: it removes all ins and overdues. To understand whether a todo is overdue or not, just check its color: overdue ones are drawn in red color(unless you used the option --no-colors or modified color in TTDL config).

Command line examples

List and filter

Add a new todo

Done (undone)

Clean up the list

Modify todo list