DrToDo 0.6.11

DrToDo, MD: todo list manager using markdown files and git

DrToDo

DrToDo, MD: a straightforward todo list manager for markdown files in git repos.

TODO items are listed in markdown (MD) files using standard markdown syntax understood by most environments including Github. You can add and modify these items easily from the command line. Markdown files are then just committed to git as you'd normally do and shared with others or as part of projects, or just kept locally in your computer.

Install

The simplest install is to use pip:

$ pip install drtodo

This will install todo in whichever python environment you are using. If you are using a virtual env manager like venv, pipenv, poetry, conda or any other, you can use that to install todo in the environment you want.

TODO: add instructions for pipx

Basic Example

Let's go through a simple example on how you might use DrToDo straight out of the proverbial box.

# create a new folder to hold your todo items
$ todo init
# add a todo to the global list
$ todo add "clean up folder `pwd`"
  0: 11348e9 ⚫ clean up folder /Users/me/work/src/tmp/p
# list todo items
$ todo list
  0: 11348e9 ⚫ clean up folder /Users/me/work/src/tmp/p
# mark item as done
$ todo done 0
  0: 11348e9 🔘 clean up folder /Users/me/work/src/tmp/p

There are many ways to reference todo items, you can use the index number, the partial hash, the text or a combination of those. For example, all of these would be equivalent in this example:

$ todo done 11348e9
  0: 11348e9 🔘 clean up folder /Users/me/work/src/tmp/p
$ todo done 'clean up'
  0: 11348e9 🔘 clean up folder /Users/me/work/src/tmp/p
$ todo done --all
  0: 11348e9 🔘 clean up folder /Users/me/work/src/tmp/p

There are more options which you can see with todo --help or todo <command> --help.

Once your items are done you can delete them with todo clean:

$ todo clean
~/.drtodo/TODO.md - removing done items:
  0: 11348e9 🔘 clean up folder /Users/me/work/src/tmp/p

Advanced Example

TODO

use it inside a git repo

TODO: document this better including the git repo used with todo init

Markdown Files

By default, DrToDo will look for any lists formatted as GitHub-style task lists in any Markdown files it reads.

For example a file containing this:

This is my cool project readme file.

## TODO
- [x] write a readme
- [ ] make it useful

## Bugs assigned to me
- [ ] bug 1
- [ ] bug 2

Will produce the following output:

$ todo list
~/work/src/DrToDo/TODO.md
  0: 56a01da 🔘 write a readme
  1: 5869ea7 ⚫ make it useful
  2: 7a787ec ⚫ bug 1
  3: f237ece ⚫ bug 2

All items will be logically combined into a single list and listed together.

In the future, it will be possible to specify which section in a Markdown file to use as a list, and then all other lists will be ignored.

Also, we will have options to add to the bottom or to the top (meaning right before or right after the last task list item).

Settings

DrToDo allows plenty of configuration options that can be specialized by folder or per user. There are many config files that can be used and are combined in specific ways detailed below.

The default configuration is fine for most people, so you can just use skip this section, use todo init and start using DrToDo.

TL;DR

Simplest case is ~/.drtodo/config.toml which is the global config file created by todo init. You can edit that file an example with defaults is provided below. TODO items are saved in ~/.drtodo/TODO.md by default. You can change file names and locations, where in the md file the TODO items go and the appearance of how TODO items are rendered.

Config File Locations

There are two valid locations for config files, global and local. Global config files are located in the ~/.drtodo folder and local config files are located in the root of any git repo.

If you are under a git repo, and the root of the git repo has a DrToDo config file, it will run in local mode (unless the --global option is provided). Otherwise it will run in global mode.

Global Mode

In global mode, the global config file at ~/.drtodo/config.toml is used. Every user starts in this mode. There are two config files that are loaded in global mode, ~/.drtodo/config.toml and ~/.drtodo/config.USER.toml (with USER replaced by the current user name). The USER config file is optional and is used to override the global config values per user. This is useful if you want to share the global config file but have some user specific settings (which you could also safely share as they wouldn't apply to anyone else).

The configuration is used to operate on the global todo file which by default is ~/.drtodo/TODO.md, but can be overridden in the config files with the mdfile=SOMENAME.md option.

Local Mode

In local mode, the config file at the root of the current git repo is used. This file is named .drtodo.toml and again there are two files that are loaded, .drtodo.toml and .drtodo.USER.toml (with USER replaced by the current user name). These files can be safely committed to git and shared with other users. The USER config file is optional and is only loaded for that user, so they can override the shared config file with their own settings.

NOTE: whenever you run under a git repo that is configured for DrToDo, you will be in local mode by default. Use the --global option to change it.

Example

Let's say you have this file structure:

~ (me)                      # home folder for user 'me'
├── .drtodo                 # global config folder
│   ├── config.toml         # [2] global config file
│   ├── TODO.md             # [2] global todo file
│   └── .git                # git repo for global todo file and config
└── work
    ├── someproject         # project under git
    │   ├── ...             # lots of files but no .drtodo files
    │   └── .git            # git repo for this project
    └── myproject           # project under git
        ├── .drtodo.toml    # [1] local config file for this project
        ├── .drtodo.me.toml # [1] personal config file for this project
        ├── BUGS.md         # [1] todo file configured in .drtodo.toml
        ├── ...             # lots of other files for myproject
        ├── somefolder      # some folder under myproject
        │   └── ...
        └── .git            # git repo for this project

$ cd ~                          # home folder
$ todo list                     # run in global mode
~/.drtodo/TODO.md
  0: 662b404 [ ] feed the dog
$ cd work/myproject/somefolder  # folder under git
$ todo list                     # run in local mode
~/work/myproject/BUGS.md
  0: 7a787ec [ ] bug 1
  1: f237ece [ ] bug 2
$ todo --global list            # run in global mode
~/.drtodo/TODO.md
  0: 662b404 [ ] feed the dog
$ cd ~/work/someproject         # folder under git but not configured for DrToDo
$ todo list                     # run in global mode
~/.drtodo/TODO.md
  0: 662b404 [ ] feed the dog

Anywhere under myproject you can run todo and it will use the local config files and local todo files tagged with [1] above. If you use the --global option, it will ignore the local files (tagged with [1]) and use the global files (tagged with [2]). The same global files will be used if you run anywhere else that is not under a git repo. Or if you run under a git repo that is not configured for DrToDo (such as someproject).

Config File Format

Config files are written in TOML format. TOML is a simple format that is easy to read and write.

All Options

The primary options are below with their default values. You can override any of these in a toml config file.

    mdfile = 'TODO.md'      # default markdown file to use
    verbose = false         # verbose output
    keep_backups = 3        # number of old md file backups to keep
    hide_hash = false       # don't show hash (use index or RE instead)

Style

Style can be either configured at a high level by name or configured in detailed individual settings. High level configuration is easy, just set the style option as follows:

style = 'round'

Valid options for style are:

• 'round': 🔘/⚫
• 'ascii': [x]/[ ]
• 'bright': ✅/❌
• 'check': ✓/✗
• 'boxed': ☑/☐
• 'dark': ✅/🔳
• 'light': ✅/🔲

Detailed Style Configuration

If you want to configure the style in more detail, you can do so with any of these options:

[style]
checked = '🔘'              # emoji or symbols used for done items
unchecked = '⚫'            # emoji or symbols used for undone items
strike_done = False         # strike through done items
dim_done = False            # dim done items
index = 'bright_black'      # color of index
hash = 'italic dim yellow'  # color of hash
text = 'white'              # color of TODO text
header = 'bold cyan'        # color of header
warning = 'bold yellow'     # color of warnings
error = 'red'               # color of errors

All the colors above use the rich style and color names. See rich docs for more info.

Reference

Global Folder

• ~/.drtodo global config folder
• ~/.drtodo/config.toml global config
• ~/.drtodo/config.USER.toml user specific config (in case this folder is shared)
• ~/.drtodo/TODO.md default location for todo list (configurable)
• ~/.drtodo/.git git repo for todo list (can be shared)

Local Folder (under any git repo)

• /somefolder/.git root folder for nearest .git repo (submodules NOT supported)
• /somefolder/.drtodo.toml local config file for this git repo (safe to commit)
• /somefolder/.drtodo.USER.toml local config file for this git repo (safe to commit, ignored by other users)
• /somefolder/TODO.md default location for todo list for this git repo (configurable)

Environment variables

• DRTODO_MDFILE default location for todo list
• DRTODO_VERBOSE verbose output
• DRTODO_IGNORE_CONFIG ignore all config files and use defaults
• DRTODO_KEEP_BACKUPS number of old markdown file backups to keep

Sample config file

mdfile = 'TODO.md'
section = ''
reverse_order = false
verbose = true
keep_backups = 3
hide_hash = false
[style]
checked = '🔘'
unchecked = '⚫'
strike_done = false
dim_done = false
index = 'bright_black'
hash = 'italic dim yellow'
text = 'white'
header = 'bold cyan'
warning = 'bold yellow'
error = 'red'
done_section = ''

DrToDo

DrToDo, MD: a straightforward todo list manager for markdown files in git repos.

Usage:

$ DrToDo [OPTIONS] COMMAND [ARGS]...

Options:

• -G, --global / -L, --local: Force operation on global or local todo list. Default is chosen smartly: local if folder is under a git repo initialized for DrToDo, global otherwise.
• --section TEXT: Section name in markdown file to use for todo list, with optional heading level, e.g. '## TODO'
• --done-section TEXT: Section name in markdown file to use for done items, with optional heading level, e.g. '## DONE'
• --reverse-order / --normal-order: Whether todo items should be in reverse order (latest first) [default: normal-order]
• --mdfile PATH: Markdown file to use for todo list
• -v, --verbose / -q, --quiet: Verbose or quiet output [default: verbose]
• -V, --version: Show version and exit
• --install-completion: Install completion for the current shell.
• --show-completion: Show completion for the current shell, to copy it or customize the installation.
• --help: Show this message and exit.

DrToDo can manage items in a global todo list (typically in ~/.drtodo) and in a local todo list (if the current folder is under a git repo configured for DrToDo). Settings are read from config files and env variables (see todo man config).

Commands:

• add: Add a new todo item to the list
• backup: Manage backups of markdown files
• clean: Cleans up the todo list, removing all done...
• dbg: List configuration, settings, version and...
• debug: List configuration, settings, version and...
• done: Mark one or more todo items as done
• init: Initialize DrToDo folder and files (in...
• list: List todo items in the list
• ls: List todo items in the list
• man: Show detailed help and context for...
• remove: Remove/delete todo items from the list
• rm: Remove/delete todo items from the list
• show: Show markdown file(s) with rich rendering.
• undone: Mark one or more todo items as NOT done...

DrToDo add

Add a new todo item to the list

Usage:

$ DrToDo add [OPTIONS] DESCRIPTION

Arguments:

• DESCRIPTION: [required]

Options:

• -p, --priority INTEGER
• -d, --due TEXT: Due date in any format
• -o, --owner TEXT: Owner userid or name
• -D, --done: Add item marked as done
• --help: Show this message and exit.

DrToDo backup

Manage backups of markdown files

Usage:

$ DrToDo backup [OPTIONS] COMMAND [ARGS]...

Options:

• -f, --force: Force the operation to proceed
• --help: Show this message and exit.

Commands:

• list: Lists any existing backup files
• ls: Lists any existing backup files
• restore: Rolls back backup files by one (3 levels...
• rollback: Rolls back backup files by one (3 levels...

DrToDo backup list

Lists any existing backup files

Usage:

$ DrToDo backup list [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo backup ls

Lists any existing backup files

Usage:

$ DrToDo backup ls [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo backup restore

Rolls back backup files by one (3 levels of backup are kept by default).

Usage:

$ DrToDo backup restore [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo backup rollback

Rolls back backup files by one (3 levels of backup are kept by default).

Usage:

$ DrToDo backup rollback [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo clean

Cleans up the todo list, removing all done items or moving them to a done section

Usage:

$ DrToDo clean [OPTIONS]

Options:

• -m, --move / -r, --remove: Cleanup method: either move to the done section or just remove items. Defaults remove unless a done section is set.
• --help: Show this message and exit.

DrToDo dbg

List configuration, settings, version and other debug info.

Usage:

$ DrToDo dbg [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo debug

List configuration, settings, version and other debug info.

Usage:

$ DrToDo debug [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo done

Mark one or more todo items as done

Usage:

$ DrToDo done [OPTIONS] [SPEC]

Arguments:

• [SPEC]: ID, index, range or regular expression to match item text

Options:

• -i, --id TEXT: ID of the item to mark
• -n, --index INTEGER: Index of the item to mark
• -r, --range TEXT: Range of item indices to mark, e.g, 2:5, 2:, :5
• -m, --match TEXT: Regular expression to match item text
• -a, --all: Mark all items
• --help: Show this message and exit.

DrToDo init

Initialize DrToDo folder and files (in global location, use --local to override)

Usage:

$ DrToDo init [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo list

List todo items in the list

Usage:

$ DrToDo list [OPTIONS] [SPEC]

Arguments:

• [SPEC]: ID, index, range or regular expression to match item text

Options:

• -i, --id TEXT: ID of the item to list
• -n, --index INTEGER: Index of the item to list
• -r, --range TEXT: Range of item indices to list, e.g, 2:5, 2:, :5
• -m, --match TEXT: Regular expression to match item text
• --help: Show this message and exit.

DrToDo ls

List todo items in the list

Usage:

$ DrToDo ls [OPTIONS] [SPEC]

Arguments:

• [SPEC]: ID, index, range or regular expression to match item text

Options:

• -i, --id TEXT: ID of the item to list
• -n, --index INTEGER: Index of the item to list
• -r, --range TEXT: Range of item indices to list, e.g, 2:5, 2:, :5
• -m, --match TEXT: Regular expression to match item text
• --help: Show this message and exit.

DrToDo man

Show detailed help and context for settings, file format and heuristics

Usage:

$ DrToDo man [OPTIONS] COMMAND [ARGS]...

Options:

• --raw: Print the raw markdown man content
• --help: Show this message and exit.

Commands:

• all: List all manual pages
• config: Where settings are stored and how to...
• md: How Markdown files are used to manage todo...
• mdfiles: How Markdown files are used to manage todo...
• settings: Where settings are stored and how to...

DrToDo man all

List all manual pages

Usage:

$ DrToDo man all [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo man config

Where settings are stored and how to configure them.

Usage:

$ DrToDo man config [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo man md

How Markdown files are used to manage todo items.

Usage:

$ DrToDo man md [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo man mdfiles

How Markdown files are used to manage todo items.

Usage:

$ DrToDo man mdfiles [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo man settings

Where settings are stored and how to configure them.

Usage:

$ DrToDo man settings [OPTIONS]

Options:

• --help: Show this message and exit.

DrToDo remove

Remove/delete todo items from the list

Usage:

$ DrToDo remove [OPTIONS] [SPEC]

Arguments:

• [SPEC]: ID, index, range or regular expression to match item text

Options:

• -i, --id TEXT: ID of the item to remove
• -n, --index INTEGER: Index of the item to remove
• -r, --range TEXT: Range of item indices to remove, e.g, 2:5, 2:, :5
• -m, --match TEXT: Regular expression to match item text
• --help: Show this message and exit.

DrToDo rm

Remove/delete todo items from the list

Usage:

$ DrToDo rm [OPTIONS] [SPEC]

Arguments:

• [SPEC]: ID, index, range or regular expression to match item text

Options:

• -i, --id TEXT: ID of the item to remove
• -n, --index INTEGER: Index of the item to remove
• -r, --range TEXT: Range of item indices to remove, e.g, 2:5, 2:, :5
• -m, --match TEXT: Regular expression to match item text
• --help: Show this message and exit.

DrToDo show

Show markdown file(s) with rich rendering. Defaults to the active, configured files.

Usage:

$ DrToDo show [OPTIONS] [FILES]...

Arguments:

• [FILES]...: override which markdown files to show

Options:

• --raw: Print the raw markdown man content
• --help: Show this message and exit.

DrToDo undone

Mark one or more todo items as NOT done (undone)

Usage:

$ DrToDo undone [OPTIONS] [SPEC]

Arguments:

• [SPEC]: ID, index, range or regular expression to match item text

Options:

• -i, --id TEXT: ID of the item to mark
• -n, --index INTEGER: Index of the item to mark
• -r, --range TEXT: Range of item indices to mark,e.g, 2:5, 2:, :5
• -m, --match TEXT: Regular expression to match item text
• -a, --all: Mark all items
• --help: Show this message and exit.