Todo.txt TUI

Todo.txt TUI is a highly customizable terminal-based application for managing your todo tasks. It follows the todo.txt format and offers a wide range of configuration options to suit your needs.

Installation

crates.io

You can install the application directly from crates.io using the following command:

cargo install todotxt-tui

Manual Installation

1. Clone the repository.

2. Build the application using Rust's package manager, Cargo:

cargo build --release

Copy the executable from the target directory to a directory included in your system's PATH:

cp target/release/todotxt-tui /usr/local/bin/

Initial Setup

To set up the basic configuration, create a directory named todotxt-tui in your configuration folder (the default is $HOME/.config). Then, export the default configuration to this directory:

todotxt-tui --export-default-config "$HOME/.config/todotxt-tui/todotxt-tui.toml"

If todotxt-tui does not find the configuration folder, it will prompt you to create one.

Next, open the configuration file and set the todo_path to the path of your todo.txt file. Environment variables or ~ will be expanded if the path is in UTF-8 format.

Autocomplete

You can generate an autocomplete script for Bash and source it:

todotxt-tui --export-autocomplete ./autocomplete-todotxt-tui.sh
source ./autocomplete-todotxt-tui.sh

Alternatively, if you prefer on-the-fly autocompletion, you can add this to your .bashrc:

source <(todotxt-tui --export-autocomplete /dev/stdout)

Usage

Todo.txt TUI is a powerful and flexible terminal-based interface designed to simplify task management. Its customization options allow you to tailor the tool to fit your workflow. Below, you'll find a comprehensive list of keybindings and actions, organized by category, to help you get started. All actions can be customized in the configuration file to suit your preferences.

Keybindings

Navigation:

• j: Move down to the next task in the list.
• k: Move up to the previous task in the list.
• g: Jump directly to the first task in the list.
• G: Jump directly to the last task in the list.

Managing Tasks:

• Enter: Show task in preview.
• U: Move the currently selected task up in the list.
• D: Move the currently selected task down in the list.
• x: Remove the selected task permanently from the list.
• d: Toggle a task's status between pending and done.
• I: Input a new task into the list.
• E: Edit the currently selected task to update its details.

Widget Navigation:

• J: Jump to the widget located below the current one.
• K: Jump to the widget located above the current one.
• H: Move to the widget on the left side of the current one.
• L: Move to the widget on the right side of the current one.

Filtering and Searching Tasks:

• Backspace: Apply a filter to display specific categories in the pending or done lists.
• /: Search for a keyword or phrase within the current list.
• n: Navigate to the next occurrence of the search term.
• N: Navigate to the previous occurrence of the search term.
• h: Clear the current search term and reset the list view.

File Operations:

• S: Save all current tasks to the todo.txt file.
• u: Reload tasks from the todo.txt file to update the list with external changes.

Quit:

• q: Quit Todo.txt TUI and save any unsaved changes.

Task Input Bar

The task input bar allows you to add or edit tasks. Press Enter to confirm the input and save the task, or press Esc to cancel. Additionally, common Bash/Emacs keybindings are supported:

• Ctrl+w: Delete the previous word.
• Ctrl+e: Move the cursor to the end of the line.
• Ctrl+a: Move the cursor to the beginning of the line.
• Ctrl+k: Delete from the cursor to the end of the line.
• Ctrl+u: Delete from the cursor to the beginning of the line.

It is also possible to use tab key to autocomplete existing projects, contexts or hashtags.

Configuration

Todo.txt TUI provides extensive customization options through a TOML configuration file located in the todotxt-tui/todotxt-tui.toml directory. Configuration settings can be overridden using flags or environment variables, with the following priority order:

1. Flags
2. Environment variables
3. Configuration file

For a complete list of available flags, use the help option (--help).

Configuration Folder Lookup

The application checks for the configuration folder in the following order:

1. $XDG_CONFIG_HOME
2. If $XDG_CONFIG_HOME is not set, $HOME/.config is used.

The default configuration folder can be changed using the --config-path <PATH> flag.

Relationship Between Flags, Environment Variables, and Configuration Keys

Flags, environment variables, and configuration keys share a consistent naming pattern:

• Flags use kebab-case (e.g., --pending-sort).
• Environment variables are in uppercase, use underscores instead of hyphens, and are prefixed with TODOTXT_TUI_ (e.g., $TODOTXT_TUI_PENDING_SORT).
• Configuration keys use snake_case (e.g., pending_sort).

Value Consistency

Most values are interchangeable between flags, environment variables, and configuration keys. However, when using the configuration file, values should be written in PascalCase instead of kebab-case.

Example

For alphanumeric-reverse:

• Flag: --alphanumeric-reverse
• Environment variable: $TODOTXT_TUI_ALPHANUMERIC_REVERSE
• Configuration key (in the TOML file): AlphanumericReverse

Keybindings

Keybindings follow a specific format and can be customized through configuration files or command-line arguments. Only events mentioned in their respective configuration sections are valid.

General Syntax

Keybindings are defined using the format:

"key_with_modifiers" = "Event"

• <key with modifiers>: Defines the key combination for triggering the event.
• Event: Specifies the action that will be performed when the keybinding is triggered.

Key Rules

1. Case Insensitivity: Keys are case-insensitive. For example, j and J are equivalent, as are enter and Enter.
2. Non-Character Keys: Special keys like enter, backspace, and escape must be explicitly named.
3. Special Characters: The characters +, ,, and : have special meanings and must be named explicitly as plus, comma, and doubledot, respectively.

Modifiers

Modifiers are optional and must be separated by a + symbol. Supported modifiers are:

• shift (or S)
• alt (or A)
• ctrl (or C)

Modifiers can be written in full or abbreviated to their first letter. For example:

• Shift+j = S+j = SHIFT+J

It is possible to use multiple modifiers in a single keybinding.

Examples

Basic Keybinding

j = "MoveDown"

Keybinding with Modifiers

"Shift+j" = "MoveDown"
"Ctrl+alt+k" = "MoveUp"
"Shift+Enter" = "Select" 

Remapping Keybindings

When remapping keybindings, you must explicitly unmap the current binding using the None event. For example:

Example Remapping

To remap Shift+j = MoveDown to Down = MoveDown:

"Shift+j" = "None"
Down = "MoveDown"

If you do not unmap the original keybinding, both keybindings will trigger the same action.

Command-Line Configuration

Keybindings can also be configured via the command line using a compact syntax. Use the format:

[<binding1>:<event1>,<binding2>:<event2>,...]

Example

To set keybindings directly from the command line:

[S+j:MoveDown,S+k:MoveUp]

This syntax is equivalent to setting:

"Shift+j" = "MoveDown"
"Shift+k" = "MoveUp"

UI

I  = "InsertMode"
L  = "MoveRight"
q  = "Quit"
K  = "MoveUp"
"/" = "SearchMode"
S  = "Save"
u  = "Load"
H  = "MoveLeft"
J  = "MoveDown"
E  = "EditMode"

[list_refresh_rate]
secs = 5
nanos = 0

[
    Direction: Horizontal,
    Size: 50%,
    [
        List: 50%,
        Preview,
    ],
    [ Direction: Vertical,
      Done,
      [
        Contexts,
        Projects,
      ],
    ],
]

To-do list

File worker

Widget

d = "MoveItem"
x = "RemoveItem"
D = "SwapDownItem"
n = "NextSearch"
U = "SwapUpItem"
Enter = "Select"
N = "PrevSearch"

Enter = "Select"
n = "NextSearch"
N = "PrevSearch"
Backspace = "Remove"

List

G = "ListLast"
h = "CleanSearch"
k = "ListUp"
g = "ListFirst"
j = "ListDown"

Preview

Defines the format string used to generate the preview pane, which provides a detailed view of the selected task. You can use placeholders to include dynamic content based on task attributes and apply text styling with the new format syntax.

Formatting Rules

Text Colors: Enclose text in [...] and specify the style in parentheses. As style you can use any color definition from Colors. Additionally, you can use skip_projects, skip_contexts, or skip_hashtags to remove projects, contexts, or hashtags from the content.

Examples:

• [some text](Red) sets the text to have a red foreground.
• [some text](^Red) sets the text to have a red background.
• [some text](Blue, Bold) sets the text to have a bold, blue foreground.
• [some text +project](Green, skip_projects) sets the text to have a green foreground and removes +project from it.

Dynamic Variables: Insert task-specific values using $name. You can use the following variables to represent task attributes:

It is also possible to use ! to enforce category colors.

Example format string:

[Pending: $pending](#ff0000) [Done: $done](^Green)
[Subject: $subject](! priority)
[Priority: $priority](priority:A)
[Created: $create_date](^Yellow)
[Link: $link](^9)

This example configures the preview pane with styled text for pending and completed tasks, task details, and dynamic values based on attributes.

Options

Pending: $pending Done: $done
Subject: $subject
Priority: $priority
Create date: $create_date
Link: $link"""

Colors

In Todo.txt TUI, you can customize the colors and text styles for various elements to suit your preferences. The customization options include setting foreground (fg) and background (bg) colors, as well as applying text modifiers to style the text.

Defining Colors

You can specify colors in the following formats:

• Named Colors: Use standard color names, e.g., "Black", "Red", etc.
• RGB Values: Use hexadecimal codes, e.g., "#ff0000" for red.
• Terminal Index: Use terminal color indices, e.g., "9" for bright red.

Applying Text Modifiers

Modifiers allow you to style text with additional visual effects. Available modifiers include:

• Bold: Makes the text bold.
• Italic: Applies italic styling.
• Underlined: Underlines the text.

Example Configuration

To configure custom colors and text modifiers for the project +todo-tui, update your Todo.txt TUI application's TOML configuration file as follows:

[custom_category_style."+todo-tui"]
fg = "#ff0000"      # Set foreground color to red (RGB value)
bg = "Black"        # Set background color to black (named color)
modifiers = "Italic"  # Apply italic styling

This configuration will style the text for +todo-tui with a red foreground, black background, and italicized text.

Options

bg = "LightRed"

Styles

A.fg = "Red"
B.fg = "Yellow"
C.fg = "Blue"

fg = "Green"

fg = "Red"

"+todo-tui".fg = "LightBlue"

bg = "Yellow"

Hooks