# 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.
## Quick Start
### installation
```console
$ pip install drtodo
```
### initialization
```console
$ todo init
```
### add a todo to the global list
```console
$ todo add "clean up folder `pwd`"
0: 11348e9 ⚫ clean up folder /Users/me/work/src/tmp/p
```
### list todo items
```console
$ todo list
0: 11348e9 ⚫ clean up folder /Users/me/work/src/tmp/p
```
### mark it as done
```console
$ todo done 0
0: 11348e9 🔘 clean up folder /Users/me/work/src/tmp/p
```
### use it inside a git repo
> TODO: document this better including the git repo used with `todo init`
## Contents
- [Quick Start](#quick-start)
- [installation](#installation)
- [initialization](#initialization)
- [add a todo to the global list](#add-a-todo-to-the-global-list)
- [list todo items](#list-todo-items)
- [mark it as done](#mark-it-as-done)
- [use it inside a git repo](#use-it-inside-a-git-repo)
- [Contents](#contents)
- [Markdown Files](#markdown-files)
- [Settings](#settings)
- [All Options](#all-options)
- [Style](#style)
- [Detailed Style Configuration](#detailed-style-configuration)
- [Global Folder](#global-folder)
- [Local Folder (under any git repo)](#local-folder-under-any-git-repo)
- [Environment variables](#environment-variables)
- [Sample config file (TOML)](#sample-config-file-toml)
- [`DrToDo`](#drtodo-1)
- [`DrToDo add`](#drtodo-add)
- [`DrToDo backup`](#drtodo-backup)
- [`DrToDo backup list`](#drtodo-backup-list)
- [`DrToDo backup ls`](#drtodo-backup-ls)
- [`DrToDo backup restore`](#drtodo-backup-restore)
- [`DrToDo dbg`](#drtodo-dbg)
- [`DrToDo debug`](#drtodo-debug)
- [`DrToDo done`](#drtodo-done)
- [`DrToDo init`](#drtodo-init)
- [`DrToDo list`](#drtodo-list)
- [`DrToDo ls`](#drtodo-ls)
- [`DrToDo man`](#drtodo-man)
- [`DrToDo man all`](#drtodo-man-all)
- [`DrToDo man config`](#drtodo-man-config)
- [`DrToDo man md`](#drtodo-man-md)
- [`DrToDo man mdfiles`](#drtodo-man-mdfiles)
- [`DrToDo man settings`](#drtodo-man-settings)
- [`DrToDo show`](#drtodo-show)
- [`DrToDo undone`](#drtodo-undone)
# 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:
```markdown
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:
```console
$ 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](#sample-config-file).
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:
```shell
~ (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
```
```console
$ 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](http://toml.io/) 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.
```toml
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:
```toml
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:
```toml
[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](https://rich.readthedocs.io/en/latest/style.html#style) 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
```toml
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'
```
# `DrToDo`
**DrToDo, MD**: *a straightforward todo list manager for markdown files in git repos.*
**Usage**:
```console
$ 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 (see *todo man config*).
**Commands**:
* `add`: Add a new todo item to the list
* `backup`: Manage backups of markdown files
* `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**:
```console
$ 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**:
```console
$ 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**:
```console
$ DrToDo backup list [OPTIONS]
```
**Options**:
* `--help`: Show this message and exit.
### `DrToDo backup ls`
Lists any existing backup files
**Usage**:
```console
$ 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**:
```console
$ 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**:
```console
$ DrToDo backup rollback [OPTIONS]
```
**Options**:
* `--help`: Show this message and exit.
## `DrToDo dbg`
List configuration, settings, version and other debug info.
**Usage**:
```console
$ DrToDo dbg [OPTIONS]
```
**Options**:
* `--help`: Show this message and exit.
## `DrToDo debug`
List configuration, settings, version and other debug info.
**Usage**:
```console
$ DrToDo debug [OPTIONS]
```
**Options**:
* `--help`: Show this message and exit.
## `DrToDo done`
Mark one or more todo items as done
**Usage**:
```console
$ 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**:
```console
$ DrToDo init [OPTIONS]
```
**Options**:
* `--help`: Show this message and exit.
## `DrToDo list`
List todo items in the list
**Usage**:
```console
$ 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**:
```console
$ 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**:
```console
$ 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**:
```console
$ DrToDo man all [OPTIONS]
```
**Options**:
* `--help`: Show this message and exit.
### `DrToDo man config`
Where settings are stored and how to configure them.
**Usage**:
```console
$ DrToDo man config [OPTIONS]
```
**Options**:
* `--help`: Show this message and exit.
### `DrToDo man md`
How Markdown files are used to manage todo items.
**Usage**:
```console
$ DrToDo man md [OPTIONS]
```
**Options**:
* `--help`: Show this message and exit.
### `DrToDo man mdfiles`
How Markdown files are used to manage todo items.
**Usage**:
```console
$ DrToDo man mdfiles [OPTIONS]
```
**Options**:
* `--help`: Show this message and exit.
### `DrToDo man settings`
Where settings are stored and how to configure them.
**Usage**:
```console
$ DrToDo man settings [OPTIONS]
```
**Options**:
* `--help`: Show this message and exit.
## `DrToDo remove`
Remove/delete todo items from the list
**Usage**:
```console
$ 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**:
```console
$ 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**:
```console
$ 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**:
```console
$ 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/exilium-com/DrTodo",
"name": "drtodo",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "utilities,todo,markdown",
"author": "exilium",
"author_email": "info@exilium.com",
"download_url": "https://files.pythonhosted.org/packages/21/0d/97e3f9b7643c3e82534197ead5dc38f281ffdd0d7cac3832f11d4e8187ab/drtodo-0.6.9.tar.gz",
"platform": null,
"description": "# DrToDo\n\n**DrToDo, MD**: *a straightforward todo list manager for markdown files in git \nrepos.*\n\nTODO items are listed in markdown (*MD*) files using standard markdown syntax \nunderstood by most\nenvironments including Github. You can add and modify these items easily from \nthe command line.\nMarkdown files are then just committed to git as you'd normally do and shared \nwith others or as\npart of projects, or just kept locally in your computer.\n\n## Quick Start\n\n### installation\n\n```console\n$ pip install drtodo\n```\n\n### initialization\n\n```console\n$ todo init\n```\n\n### add a todo to the global list\n\n```console\n$ todo add \"clean up folder `pwd`\"\n 0: 11348e9 \u26ab clean up folder /Users/me/work/src/tmp/p\n```\n\n### list todo items\n\n```console\n$ todo list\n 0: 11348e9 \u26ab clean up folder /Users/me/work/src/tmp/p\n```\n\n### mark it as done\n\n```console\n$ todo done 0\n 0: 11348e9 \ud83d\udd18 clean up folder /Users/me/work/src/tmp/p\n```\n\n### use it inside a git repo\n\n> TODO: document this better including the git repo used with `todo init`\n\n## Contents\n\n - [Quick Start](#quick-start)\n - [installation](#installation)\n - [initialization](#initialization)\n - [add a todo to the global list](#add-a-todo-to-the-global-list)\n - [list todo items](#list-todo-items)\n - [mark it as done](#mark-it-as-done)\n - [use it inside a git repo](#use-it-inside-a-git-repo)\n - [Contents](#contents)\n- [Markdown Files](#markdown-files)\n- [Settings](#settings)\n - [All Options](#all-options)\n - [Style](#style)\n - [Detailed Style Configuration](#detailed-style-configuration)\n - [Global Folder](#global-folder)\n - [Local Folder (under any git repo)](#local-folder-under-any-git-repo)\n - [Environment variables](#environment-variables)\n - [Sample config file (TOML)](#sample-config-file-toml)\n- [`DrToDo`](#drtodo-1)\n - [`DrToDo add`](#drtodo-add)\n - [`DrToDo backup`](#drtodo-backup)\n - [`DrToDo backup list`](#drtodo-backup-list)\n - [`DrToDo backup ls`](#drtodo-backup-ls)\n - [`DrToDo backup restore`](#drtodo-backup-restore)\n - [`DrToDo dbg`](#drtodo-dbg)\n - [`DrToDo debug`](#drtodo-debug)\n - [`DrToDo done`](#drtodo-done)\n - [`DrToDo init`](#drtodo-init)\n - [`DrToDo list`](#drtodo-list)\n - [`DrToDo ls`](#drtodo-ls)\n - [`DrToDo man`](#drtodo-man)\n - [`DrToDo man all`](#drtodo-man-all)\n - [`DrToDo man config`](#drtodo-man-config)\n - [`DrToDo man md`](#drtodo-man-md)\n - [`DrToDo man mdfiles`](#drtodo-man-mdfiles)\n - [`DrToDo man settings`](#drtodo-man-settings)\n - [`DrToDo show`](#drtodo-show)\n - [`DrToDo undone`](#drtodo-undone)\n\n\n# Markdown Files\n\nBy default, DrToDo will look for any lists formatted as GitHub-style task lists \nin\nany Markdown files it reads.\n\nFor example a file containing this:\n```markdown\nThis is my cool project readme file.\n\n## TODO\n- [x] write a readme\n- [ ] make it useful\n\n## Bugs assigned to me\n- [ ] bug 1\n- [ ] bug 2\n```\n\nWill produce the following output:\n```console\n$ todo list\n~/work/src/DrToDo/TODO.md\n 0: 56a01da \ud83d\udd18 write a readme\n 1: 5869ea7 \u26ab make it useful\n 2: 7a787ec \u26ab bug 1\n 3: f237ece \u26ab bug 2\n```\n\nAll items will be logically combined into a single list and listed together.\n\n> In the future, it will be possible to specify which section in a Markdown file\nto use as a list,\n> and then all other lists will be ignored.\n\n> Also, we will have options to add to the bottom or to the top (meaning right \nbefore or right after the\n> last task list item).\n\n\n# Settings\n\nDrToDo allows plenty of configuration options that can be specialized by folder \nor per user.\nThere are many config files that can be used and are combined in specific ways \ndetailed below.\n\n> The default configuration is fine for most people, so you can just use skip \nthis section, use `todo init` and start using DrToDo.\n\n## TL;DR\n\nSimplest case is `~/.drtodo/config.toml` which is the global config file created\nby `todo init`.\nYou can edit that file an example with defaults is provided \n[below](#sample-config-file).\nTODO items are saved in `~/.drtodo/TODO.md` by default. You can change file \nnames and locations,\nwhere in the md file the TODO items go and the appearance of how TODO items are \nrendered.\n\n## Config File Locations\n\nThere are two valid locations for config files, *global* and *local*. Global \nconfig files are located in\nthe `~/.drtodo` folder and local config files are located in the root of any git\nrepo.\n\nIf you are under a git repo, and the root of the git repo has a DrToDo config \nfile, it will run in *local* mode\n(unless the `--global` option is provided). Otherwise it will run in *global* \nmode.\n\n### Global Mode\n\nIn global mode, the global config file at `~/.drtodo/config.toml` is used. Every\nuser starts in this mode.\nThere are *two* config files that are loaded in global mode, \n`~/.drtodo/config.toml` and `~/.drtodo/config.USER.toml`\n(with `USER` replaced by the current user name). The `USER` config file is \noptional and is used to override the global\nconfig values per user. This is useful if you want to share the global config \nfile but have some user specific settings\n(which you could also safely share as they wouldn't apply to anyone else).\n\nThe configuration is used to operate on the global todo file which by default is\n`~/.drtodo/TODO.md`, but can be overridden\nin the config files with the `mdfile=SOMENAME.md` option.\n\n### Local Mode\n\nIn local mode, the config file at the root of the current git repo is used. This\nfile is named `.drtodo.toml` and again\nthere are two files that are loaded, `.drtodo.toml` and `.drtodo.USER.toml` \n(with `USER` replaced by the current user name).\nThese files can be safely committed to git and shared with other users. The \n`USER` config file is optional and is only loaded\nfor that user, so they can override the shared config file with their own \nsettings.\n\n> NOTE: whenever you run under a git repo that is configured for DrToDo, you \nwill be in local mode by default.\n> Use the `--global` option to change it.\n\n### Example\n\nLet's say you have this file structure:\n\n```shell\n~ (me) # home folder for user 'me'\n\u251c\u2500\u2500 .drtodo # global config folder\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 config.toml # [2] global config file\n\u2502 \u251c\u2500\u2500 TODO.md # [2] global todo file\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 .git # git repo for global todo file and config\n\u2514\u2500\u2500 work\n \u00a0\u00a0 \u251c\u2500\u2500 someproject # project under git\n \u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 ... # lots of files but no .drtodo files\n \u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 .git # git repo for this project\n \u00a0\u00a0 \u2514\u2500\u2500 myproject # project under git\n \u00a0\u00a0 \u00a0\u00a0 \u251c\u2500\u2500 .drtodo.toml # [1] local config file for this project\n \u00a0\u00a0 \u00a0\u00a0 \u251c\u2500\u2500 .drtodo.me.toml # [1] personal config file for this project\n \u00a0\u00a0 \u00a0\u00a0 \u251c\u2500\u2500 BUGS.md # [1] todo file configured in .drtodo.toml\n \u00a0\u00a0 \u00a0\u00a0 \u251c\u2500\u2500 ... # lots of other files for myproject\n \u00a0\u00a0 \u00a0\u00a0 \u251c\u2500\u2500 somefolder # some folder under myproject\n \u00a0\u00a0 \u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 ...\n \u00a0\u00a0 \u00a0\u00a0 \u2514\u2500\u2500 .git # git repo for this project\n```\n\n```console\n$ cd ~ # home folder\n$ todo list # run in global mode\n~/.drtodo/TODO.md\n 0: 662b404 [ ] feed the dog\n$ cd work/myproject/somefolder # folder under git\n$ todo list # run in local mode\n~/work/myproject/BUGS.md\n 0: 7a787ec [ ] bug 1\n 1: f237ece [ ] bug 2\n$ todo --global list # run in global mode\n~/.drtodo/TODO.md\n 0: 662b404 [ ] feed the dog\n$ cd ~/work/someproject # folder under git but not configured for DrToDo\n$ todo list # run in global mode\n~/.drtodo/TODO.md\n 0: 662b404 [ ] feed the dog\n```\n\nAnywhere under `myproject` you can run `todo` and it will use the local config \nfiles and local\ntodo files tagged with `[1]` above. If you use the `--global` option, it will \nignore the local\nfiles (tagged with `[1]`) and use the global files (tagged with `[2]`). The same\nglobal files\nwill be used if you run anywhere else that is not under a git repo. Or if you \nrun under a git\nrepo that is not configured for DrToDo (such as `someproject`).\n\n# Config File Format\n\nConfig files are written in [TOML](http://toml.io/) format. TOML is a simple \nformat that is easy to read and write.\n\n## All Options\n\nThe primary options are below with their default values. You can override any of\nthese in a toml config file.\n\n```toml\n mdfile = 'TODO.md' # default markdown file to use\n verbose = false # verbose output\n keep_backups = 3 # number of old md file backups to keep\n hide_hash = false # don't show hash (use index or RE instead)\n```\n\n\n### Style\n\nStyle can be either configured at a high level by name or configured in detailed\nindividual settings.\nHigh level configuration is easy, just set the `style` option as follows:\n\n```toml\nstyle = 'round'\n```\n\nValid options for style are:\n\n- 'round': \ud83d\udd18/\u26ab\n- 'ascii': [x]/[ ]\n- 'bright': \u2705/\u274c\n- 'check': \u2713/\u2717\n- 'boxed': \u2611/\u2610\n- 'dark': \u2705/\ud83d\udd33\n- 'light': \u2705/\ud83d\udd32\n\n#### Detailed Style Configuration\n\nIf you want to configure the style in more detail, you can do so with any of \nthese options:\n\n```toml\n[style]\nchecked = '\ud83d\udd18' # emoji or symbols used for done items\nunchecked = '\u26ab' # emoji or symbols used for undone items\nstrike_done = False # strike through done items\ndim_done = False # dim done items\nindex = 'bright_black' # color of index\nhash = 'italic dim yellow' # color of hash\ntext = 'white' # color of TODO text\nheader = 'bold cyan' # color of header\nwarning = 'bold yellow' # color of warnings\nerror = 'red' # color of errors\n```\n\nAll the colors above use the rich style and color names.\nSee [rich docs](https://rich.readthedocs.io/en/latest/style.html#style) for more\ninfo.\n\n# Reference\n\n## Global Folder\n- `~/.drtodo` global config folder\n- `~/.drtodo/config.toml` global config\n- `~/.drtodo/config.USER.toml` user specific config (in case this folder is \nshared)\n- `~/.drtodo/TODO.md` default location for todo list (configurable)\n- `~/.drtodo/.git` git repo for todo list (can be shared)\n\n## Local Folder (under any git repo)\n- `/somefolder/.git` root folder for nearest .git repo (submodules \nNOT supported)\n- `/somefolder/.drtodo.toml` local config file for this git repo (safe to \ncommit)\n- `/somefolder/.drtodo.USER.toml` local config file for this git repo (safe to \ncommit, ignored by other users)\n- `/somefolder/TODO.md` default location for todo list for this git \nrepo (configurable)\n\n## Environment variables\n\n- `DRTODO_MDFILE` default location for todo list\n- `DRTODO_VERBOSE` verbose output\n- `DRTODO_IGNORE_CONFIG` ignore all config files and use defaults\n- `DRTODO_KEEP_BACKUPS` number of old markdown file backups to keep\n\n## Sample config file\n```toml\nmdfile = 'TODO.md'\nsection = ''\nreverse_order = false\nverbose = true\nkeep_backups = 3\nhide_hash = false\n[style]\nchecked = '\ud83d\udd18'\nunchecked = '\u26ab'\nstrike_done = false\ndim_done = false\nindex = 'bright_black'\nhash = 'italic dim yellow'\ntext = 'white'\nheader = 'bold cyan'\nwarning = 'bold yellow'\nerror = 'red'\n\n```\n\n# `DrToDo`\n\n**DrToDo, MD**: *a straightforward todo list manager for markdown files in git repos.*\n\n**Usage**:\n\n```console\n$ DrToDo [OPTIONS] COMMAND [ARGS]...\n```\n\n**Options**:\n\n* `-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.\n* `--section TEXT`: Section name in markdown file to use for todo list, with optional heading level, e.g. '## TODO'\n* `--reverse-order / --normal-order`: Whether todo items should be in reverse order (latest first) [default: normal-order]\n* `--mdfile PATH`: Markdown file to use for todo list\n* `-v, --verbose / -q, --quiet`: Verbose or quiet output [default: verbose]\n* `-V, --version`: Show version and exit\n* `--install-completion`: Install completion for the current shell.\n* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.\n* `--help`: Show this message and exit.\n\nDrToDo 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*).\n\n**Commands**:\n\n* `add`: Add a new todo item to the list\n* `backup`: Manage backups of markdown files\n* `dbg`: List configuration, settings, version and...\n* `debug`: List configuration, settings, version and...\n* `done`: Mark one or more todo items as done\n* `init`: Initialize DrToDo folder and files (in...\n* `list`: List todo items in the list\n* `ls`: List todo items in the list\n* `man`: Show detailed help and context for...\n* `remove`: Remove/delete todo items from the list\n* `rm`: Remove/delete todo items from the list\n* `show`: Show markdown file(s) with rich rendering.\n* `undone`: Mark one or more todo items as NOT done...\n\n## `DrToDo add`\n\nAdd a new todo item to the list\n\n**Usage**:\n\n```console\n$ DrToDo add [OPTIONS] DESCRIPTION\n```\n\n**Arguments**:\n\n* `DESCRIPTION`: [required]\n\n**Options**:\n\n* `-p, --priority INTEGER`\n* `-d, --due TEXT`: Due date in any format\n* `-o, --owner TEXT`: Owner userid or name\n* `-D, --done`: Add item marked as done\n* `--help`: Show this message and exit.\n\n## `DrToDo backup`\n\nManage backups of markdown files\n\n**Usage**:\n\n```console\n$ DrToDo backup [OPTIONS] COMMAND [ARGS]...\n```\n\n**Options**:\n\n* `-f, --force`: Force the operation to proceed\n* `--help`: Show this message and exit.\n\n**Commands**:\n\n* `list`: Lists any existing backup files\n* `ls`: Lists any existing backup files\n* `restore`: Rolls back backup files by one (3 levels...\n* `rollback`: Rolls back backup files by one (3 levels...\n\n### `DrToDo backup list`\n\nLists any existing backup files\n\n**Usage**:\n\n```console\n$ DrToDo backup list [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n### `DrToDo backup ls`\n\nLists any existing backup files\n\n**Usage**:\n\n```console\n$ DrToDo backup ls [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n### `DrToDo backup restore`\n\nRolls back backup files by one (3 levels of backup are kept by default).\n\n**Usage**:\n\n```console\n$ DrToDo backup restore [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n### `DrToDo backup rollback`\n\nRolls back backup files by one (3 levels of backup are kept by default).\n\n**Usage**:\n\n```console\n$ DrToDo backup rollback [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n## `DrToDo dbg`\n\nList configuration, settings, version and other debug info.\n\n**Usage**:\n\n```console\n$ DrToDo dbg [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n## `DrToDo debug`\n\nList configuration, settings, version and other debug info.\n\n**Usage**:\n\n```console\n$ DrToDo debug [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n## `DrToDo done`\n\nMark one or more todo items as done\n\n**Usage**:\n\n```console\n$ DrToDo done [OPTIONS] [SPEC]\n```\n\n**Arguments**:\n\n* `[SPEC]`: ID, index, range or regular expression to match item text\n\n**Options**:\n\n* `-i, --id TEXT`: ID of the item to mark\n* `-n, --index INTEGER`: Index of the item to mark\n* `-r, --range TEXT`: Range of item indices to mark, e.g, 2:5, 2:, :5\n* `-m, --match TEXT`: Regular expression to match item text\n* `-a, --all`: Mark all items\n* `--help`: Show this message and exit.\n\n## `DrToDo init`\n\nInitialize DrToDo folder and files (in global location, use --local to override)\n\n**Usage**:\n\n```console\n$ DrToDo init [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n## `DrToDo list`\n\nList todo items in the list\n\n**Usage**:\n\n```console\n$ DrToDo list [OPTIONS] [SPEC]\n```\n\n**Arguments**:\n\n* `[SPEC]`: ID, index, range or regular expression to match item text\n\n**Options**:\n\n* `-i, --id TEXT`: ID of the item to list\n* `-n, --index INTEGER`: Index of the item to list\n* `-r, --range TEXT`: Range of item indices to list, e.g, 2:5, 2:, :5\n* `-m, --match TEXT`: Regular expression to match item text\n* `--help`: Show this message and exit.\n\n## `DrToDo ls`\n\nList todo items in the list\n\n**Usage**:\n\n```console\n$ DrToDo ls [OPTIONS] [SPEC]\n```\n\n**Arguments**:\n\n* `[SPEC]`: ID, index, range or regular expression to match item text\n\n**Options**:\n\n* `-i, --id TEXT`: ID of the item to list\n* `-n, --index INTEGER`: Index of the item to list\n* `-r, --range TEXT`: Range of item indices to list, e.g, 2:5, 2:, :5\n* `-m, --match TEXT`: Regular expression to match item text\n* `--help`: Show this message and exit.\n\n## `DrToDo man`\n\nShow detailed help and context for settings, file format and heuristics\n\n**Usage**:\n\n```console\n$ DrToDo man [OPTIONS] COMMAND [ARGS]...\n```\n\n**Options**:\n\n* `--raw`: Print the raw markdown man content\n* `--help`: Show this message and exit.\n\n**Commands**:\n\n* `all`: List all manual pages\n* `config`: Where settings are stored and how to...\n* `md`: How Markdown files are used to manage todo...\n* `mdfiles`: How Markdown files are used to manage todo...\n* `settings`: Where settings are stored and how to...\n\n### `DrToDo man all`\n\nList all manual pages\n\n**Usage**:\n\n```console\n$ DrToDo man all [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n### `DrToDo man config`\n\nWhere settings are stored and how to configure them.\n\n**Usage**:\n\n```console\n$ DrToDo man config [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n### `DrToDo man md`\n\nHow Markdown files are used to manage todo items.\n\n**Usage**:\n\n```console\n$ DrToDo man md [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n### `DrToDo man mdfiles`\n\nHow Markdown files are used to manage todo items.\n\n**Usage**:\n\n```console\n$ DrToDo man mdfiles [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n### `DrToDo man settings`\n\nWhere settings are stored and how to configure them.\n\n**Usage**:\n\n```console\n$ DrToDo man settings [OPTIONS]\n```\n\n**Options**:\n\n* `--help`: Show this message and exit.\n\n## `DrToDo remove`\n\nRemove/delete todo items from the list\n\n**Usage**:\n\n```console\n$ DrToDo remove [OPTIONS] [SPEC]\n```\n\n**Arguments**:\n\n* `[SPEC]`: ID, index, range or regular expression to match item text\n\n**Options**:\n\n* `-i, --id TEXT`: ID of the item to remove\n* `-n, --index INTEGER`: Index of the item to remove\n* `-r, --range TEXT`: Range of item indices to remove, e.g, 2:5, 2:, :5\n* `-m, --match TEXT`: Regular expression to match item text\n* `--help`: Show this message and exit.\n\n## `DrToDo rm`\n\nRemove/delete todo items from the list\n\n**Usage**:\n\n```console\n$ DrToDo rm [OPTIONS] [SPEC]\n```\n\n**Arguments**:\n\n* `[SPEC]`: ID, index, range or regular expression to match item text\n\n**Options**:\n\n* `-i, --id TEXT`: ID of the item to remove\n* `-n, --index INTEGER`: Index of the item to remove\n* `-r, --range TEXT`: Range of item indices to remove, e.g, 2:5, 2:, :5\n* `-m, --match TEXT`: Regular expression to match item text\n* `--help`: Show this message and exit.\n\n## `DrToDo show`\n\nShow markdown file(s) with rich rendering. Defaults to the active, configured files.\n\n**Usage**:\n\n```console\n$ DrToDo show [OPTIONS] [FILES]...\n```\n\n**Arguments**:\n\n* `[FILES]...`: override which markdown files to show\n\n**Options**:\n\n* `--raw`: Print the raw markdown man content\n* `--help`: Show this message and exit.\n\n## `DrToDo undone`\n\nMark one or more todo items as NOT done (undone)\n\n**Usage**:\n\n```console\n$ DrToDo undone [OPTIONS] [SPEC]\n```\n\n**Arguments**:\n\n* `[SPEC]`: ID, index, range or regular expression to match item text\n\n**Options**:\n\n* `-i, --id TEXT`: ID of the item to mark\n* `-n, --index INTEGER`: Index of the item to mark\n* `-r, --range TEXT`: Range of item indices to mark,e.g, 2:5, 2:, :5\n* `-m, --match TEXT`: Regular expression to match item text\n* `-a, --all`: Mark all items\n* `--help`: Show this message and exit.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "DrToDo, MD: todo list manager using markdown files and git",
"version": "0.6.9",
"project_urls": {
"Homepage": "https://github.com/exilium-com/DrTodo",
"Repository": "https://github.com/exilium-com/DrTodo"
},
"split_keywords": [
"utilities",
"todo",
"markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bb6c6b6f652231b60cc13430e1ff0b6ff8fa88ce9436f1fc3cdcbf4157668a49",
"md5": "da48bbc79408da1f23f56a340b1a6d7b",
"sha256": "76eb72328c516f8ddff387f2e12f783fe725782c0228e31e3a0d6ad9683498a5"
},
"downloads": -1,
"filename": "drtodo-0.6.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "da48bbc79408da1f23f56a340b1a6d7b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 33101,
"upload_time": "2023-06-28T19:29:31",
"upload_time_iso_8601": "2023-06-28T19:29:31.785399Z",
"url": "https://files.pythonhosted.org/packages/bb/6c/6b6f652231b60cc13430e1ff0b6ff8fa88ce9436f1fc3cdcbf4157668a49/drtodo-0.6.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "210d97e3f9b7643c3e82534197ead5dc38f281ffdd0d7cac3832f11d4e8187ab",
"md5": "36836b5c07c9c793e1e38e96bd02aed9",
"sha256": "ccb61c37d03f5f8d4c041ef0845e8dbbfb79f5750e7f5804339d8f3faa50fba2"
},
"downloads": -1,
"filename": "drtodo-0.6.9.tar.gz",
"has_sig": false,
"md5_digest": "36836b5c07c9c793e1e38e96bd02aed9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 27714,
"upload_time": "2023-06-28T19:29:34",
"upload_time_iso_8601": "2023-06-28T19:29:34.262303Z",
"url": "https://files.pythonhosted.org/packages/21/0d/97e3f9b7643c3e82534197ead5dc38f281ffdd0d7cac3832f11d4e8187ab/drtodo-0.6.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-28 19:29:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "exilium-com",
"github_project": "DrTodo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "drtodo"
}
JSON
