Package: drtodo
DrToDoDrToDo, 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.Quick Startinstallation$pipinstalldrtodoinitialization$todoinitadd a todo to the global list$todoadd"clean up folder `pwd`"0: 11348e9 ⚫ clean up folder /Users/me/work/src/tmp/plist todo items$todolist0: 11348e9 ⚫ clean up folder /Users/me/work/src/tmp/pmark it as done$tododone00: 11348e9 🔘 clean up folder /Users/me/work/src/tmp/puse it inside a git repoTODO: document this better including the git repo used withtodo initContentsQuick Startinstallationinitializationadd a todo to the global listlist todo itemsmark it as doneuse it inside a git repoContentsMarkdown FilesSettingsAll OptionsStyleDetailed Style ConfigurationGlobal FolderLocal Folder (under any git repo)Environment variablesSample config file (TOML)DrToDoDrToDo addDrToDo backupDrToDo backup listDrToDo backup lsDrToDo backup restoreDrToDo dbgDrToDo debugDrToDo doneDrToDo initDrToDo listDrToDo lsDrToDo manDrToDo man allDrToDo man configDrToDo man mdDrToDo man mdfilesDrToDo man settingsDrToDo showDrToDo undoneMarkdown FilesBy 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 2Will produce the following output:$todolist~/work/src/DrToDo/TODO.md0: 56a01da 🔘 write a readme1: 5869ea7 ⚫ make it useful2: 7a787ec ⚫ bug 13: f237ece ⚫ bug 2All 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).SettingsDrToDo 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, usetodo initand start using DrToDo.TL;DRSimplest case is~/.drtodo/config.tomlwhich is the global config file created
bytodo init.
You can edit that file an example with defaults is providedbelow.
TODO items are saved in~/.drtodo/TODO.mdby 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 LocationsThere are two valid locations for config files,globalandlocal. Global
config files are located in
the~/.drtodofolder 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 inlocalmode
(unless the--globaloption is provided). Otherwise it will run inglobalmode.Global ModeIn global mode, the global config file at~/.drtodo/config.tomlis used. Every
user starts in this mode.
There aretwoconfig files that are loaded in global mode,~/.drtodo/config.tomland~/.drtodo/config.USER.toml(withUSERreplaced by the current user name). TheUSERconfig 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 themdfile=SOMENAME.mdoption.Local ModeIn local mode, the config file at the root of the current git repo is used. This
file is named.drtodo.tomland again
there are two files that are loaded,.drtodo.tomland.drtodo.USER.toml(withUSERreplaced by the current user name).
These files can be safely committed to git and shared with other users. TheUSERconfig 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--globaloption to change it.ExampleLet'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$todolist# run in global mode~/.drtodo/TODO.md0: 662b404 [ ] feed the dog$cdwork/myproject/somefolder# folder under git$todolist# run in local mode~/work/myproject/BUGS.md0: 7a787ec [ ] bug 11: f237ece [ ] bug 2$todo--globallist# run in global mode~/.drtodo/TODO.md0: 662b404 [ ] feed the dog$cd~/work/someproject# folder under git but not configured for DrToDo$todolist# run in global mode~/.drtodo/TODO.md0: 662b404 [ ] feed the dogAnywhere undermyprojectyou can runtodoand it will use the local config
files and local
todo files tagged with[1]above. If you use the--globaloption, 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 assomeproject).Config File FormatConfig files are written inTOMLformat. TOML is a simple
format that is easy to read and write.All OptionsThe 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 useverbose=false# verbose outputkeep_backups=3# number of old md file backups to keephide_hash=false# don't show hash (use index or RE instead)StyleStyle can be either configured at a high level by name or configured in detailed
individual settings.
High level configuration is easy, just set thestyleoption as follows:style='round'Valid options for style are:'round': 🔘/⚫'ascii': [x]/[ ]'bright': ✅/❌'check': ✓/✗'boxed': ☑/☐'dark': ✅/🔳'light': ✅/🔲Detailed Style ConfigurationIf 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 itemsunchecked='⚫'# emoji or symbols used for undone itemsstrike_done=False# strike through done itemsdim_done=False# dim done itemsindex='bright_black'# color of indexhash='italic dim yellow'# color of hashtext='white'# color of TODO textheader='bold cyan'# color of headerwarning='bold yellow'# color of warningserror='red'# color of errorsAll the colors above use the rich style and color names.
Seerich docsfor more
info.ReferenceGlobal Folder~/.drtodoglobal config folder~/.drtodo/config.tomlglobal config~/.drtodo/config.USER.tomluser specific config (in case this folder is
shared)~/.drtodo/TODO.mddefault location for todo list (configurable)~/.drtodo/.gitgit repo for todo list (can be shared)Local Folder (under any git repo)/somefolder/.gitroot folder for nearest .git repo (submodules
NOT supported)/somefolder/.drtodo.tomllocal config file for this git repo (safe to
commit)/somefolder/.drtodo.USER.tomllocal config file for this git repo (safe to
commit, ignored by other users)/somefolder/TODO.mddefault location for todo list for this git
repo (configurable)Environment variablesDRTODO_MDFILEdefault location for todo listDRTODO_VERBOSEverbose outputDRTODO_IGNORE_CONFIGignore all config files and use defaultsDRTODO_KEEP_BACKUPSnumber of old markdown file backups to keepSample config filemdfile='TODO.md'section=''reverse_order=falseverbose=truekeep_backups=3hide_hash=false[style]checked='🔘'unchecked='⚫'strike_done=falsedim_done=falseindex='bright_black'hash='italic dim yellow'text='white'header='bold cyan'warning='bold yellow'error='red'DrToDoDrToDo, 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'--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 (seetodo man config).Commands:add: Add a new todo item to the listbackup: Manage backups of markdown filesdbg: List configuration, settings, version and...debug: List configuration, settings, version and...done: Mark one or more todo items as doneinit: Initialize DrToDo folder and files (in...list: List todo items in the listls: List todo items in the listman: Show detailed help and context for...remove: Remove/delete todo items from the listrm: Remove/delete todo items from the listshow: Show markdown file(s) with rich rendering.undone: Mark one or more todo items as NOT done...DrToDo addAdd a new todo item to the listUsage:$DrToDoadd[OPTIONS]DESCRIPTIONArguments: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 backupManage backups of markdown filesUsage:$DrToDobackup[OPTIONS]COMMAND[ARGS]...Options:-f, --force: Force the operation to proceed--help: Show this message and exit.Commands:list: Lists any existing backup filesls: Lists any existing backup filesrestore: Rolls back backup files by one (3 levels...rollback: Rolls back backup files by one (3 levels...DrToDo backup listLists any existing backup filesUsage:$DrToDobackuplist[OPTIONS]Options:--help: Show this message and exit.DrToDo backup lsLists any existing backup filesUsage:$DrToDobackupls[OPTIONS]Options:--help: Show this message and exit.DrToDo backup restoreRolls back backup files by one (3 levels of backup are kept by default).Usage:$DrToDobackuprestore[OPTIONS]Options:--help: Show this message and exit.DrToDo backup rollbackRolls back backup files by one (3 levels of backup are kept by default).Usage:$DrToDobackuprollback[OPTIONS]Options:--help: Show this message and exit.DrToDo dbgList configuration, settings, version and other debug info.Usage:$DrToDodbg[OPTIONS]Options:--help: Show this message and exit.DrToDo debugList configuration, settings, version and other debug info.Usage:$DrToDodebug[OPTIONS]Options:--help: Show this message and exit.DrToDo doneMark one or more todo items as doneUsage:$DrToDodone[OPTIONS][SPEC]Arguments:[SPEC]: ID, index, range or regular expression to match item textOptions:-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 initInitialize DrToDo folder and files (in global location, use --local to override)Usage:$DrToDoinit[OPTIONS]Options:--help: Show this message and exit.DrToDo listList todo items in the listUsage:$DrToDolist[OPTIONS][SPEC]Arguments:[SPEC]: ID, index, range or regular expression to match item textOptions:-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 lsList todo items in the listUsage:$DrToDols[OPTIONS][SPEC]Arguments:[SPEC]: ID, index, range or regular expression to match item textOptions:-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 manShow detailed help and context for settings, file format and heuristicsUsage:$DrToDoman[OPTIONS]COMMAND[ARGS]...Options:--raw: Print the raw markdown man content--help: Show this message and exit.Commands:all: List all manual pagesconfig: 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 allList all manual pagesUsage:$DrToDomanall[OPTIONS]Options:--help: Show this message and exit.DrToDo man configWhere settings are stored and how to configure them.Usage:$DrToDomanconfig[OPTIONS]Options:--help: Show this message and exit.DrToDo man mdHow Markdown files are used to manage todo items.Usage:$DrToDomanmd[OPTIONS]Options:--help: Show this message and exit.DrToDo man mdfilesHow Markdown files are used to manage todo items.Usage:$DrToDomanmdfiles[OPTIONS]Options:--help: Show this message and exit.DrToDo man settingsWhere settings are stored and how to configure them.Usage:$DrToDomansettings[OPTIONS]Options:--help: Show this message and exit.DrToDo removeRemove/delete todo items from the listUsage:$DrToDoremove[OPTIONS][SPEC]Arguments:[SPEC]: ID, index, range or regular expression to match item textOptions:-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 rmRemove/delete todo items from the listUsage:$DrToDorm[OPTIONS][SPEC]Arguments:[SPEC]: ID, index, range or regular expression to match item textOptions:-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 showShow markdown file(s) with rich rendering. Defaults to the active, configured files.Usage:$DrToDoshow[OPTIONS][FILES]...Arguments:[FILES]...: override which markdown files to showOptions:--raw: Print the raw markdown man content--help: Show this message and exit.DrToDo undoneMark one or more todo items as NOT done (undone)Usage:$DrToDoundone[OPTIONS][SPEC]Arguments:[SPEC]: ID, index, range or regular expression to match item textOptions:-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.