devtodo(1)

📦
version 0.1.20+git20200830.0ad52b0 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

devtodo(1) — the todo(1) glow-up 💖

Programming utility ✨ devtodo(1)

okay bestie, this is the manual for todo and friends, straight from the Programming utility section of your local man pages. sit down, grab a strawberry 🍓, we're going through everything. no skips. no cap.

🌸 NAME 🌸

todo — a reminder/task program aimed at developers 💅

✨ SYNOPSIS ✨

todo [<options>]
       With no options, displays the items in the current directory.

tda [-p <priority>] [-g <index>] [<text>]
       Add a new item, optionally grafting it as a child of the given
       item.

tde <index>
       Edit the given item.

tdr <indices>
       Remove the given items.

tdd <indices>
       Mark the specified items as being done.

tdl [-g <index>] <database>
       Link the specified devtodo database into the current one,
       optionally grafting it as a child of the specified index.

so yeah, there's a whole little squad of commands: todo, tda, tde, tdr, tdd, and tdl. they're giving ✨friend group✨ energy, each with their own job. 🫶

🦋 DESCRIPTION 🦋

todo is a program aimed specifically at programmers (but usable by anybody at the terminal) to aid in day-to-day development. 👑

It maintains a list of items that have yet to be completed. This allows the programmer to track outstanding bugs or items that need to be completed with very little effort. literally the lowest-effort way to not forget your bug. 🐛

Items can be prioritised and can also be displayed in a hierarchy, so that one item may depend on another. it's giving family tree but make it tasks. 🌳

With the use of some small shell scripts (scripts.* in the doc directory of the source distribution), todo can also display the outstanding items in a directory as you change into it. So, for example, if you cd into the source directory for todo itself you should see a list of outstanding items...unless all of the bugs have been fixed ;). 😭 imagine. iconic behaviour.

💅 OPTIONS 💅

okay so options can have both a long and a short form. (iykyk ✨)

Short options can be combined into one argument by using a hyphen followed by a string of short options. Parameters of short options can also be appended to this string. so yes bestie you CAN smush them together, that's the whole vibe. 🎀

  • -v, --verbose — Display verbosely. 🗣️
  • -a, --add [<text>] — Add a note (will prompt for a note if one is not supplied). 🍓
  • -g, --graft <index> — In conjunction with --add or --link, graft the new item to the specified item. 🌱
  • -l, --link <database> — Link the specified todo file into the body of this one. If the linked database has a title set, this will be used as the body of the linking item otherwise the directory name of the linked database will be used. Use --remove (or tdr) to remove linked databases ‐ this does not remove the database itself, only the link. 🔗
  • -R,--reparent <index>[,<index>] — Change the parent of the first item index to the second item index. If no second index is given the item is reparented to the root of the tree. 🌲
  • -p, --priority <priority> — In conjunction with --add or --edit, set the priority (default | veryhigh | high | medium | low | verylow). ⭐
  • -e, --edit <index> — Edit the note that is indexed by the given number. ✏️
  • --remove <indices> — Remove the note indexed by the given numbers, including any children. 💀
  • -d, --done <indices> — Mark the specified notes (and their children) as done. ✅
  • -D, --not-done <indices> — Mark the specified notes (and all children) as not done. 🙈
  • --global-database <file> — Specify the database to use if either the -G or --global options are specified. 🌍
  • -G, --global — Force todo to use the database specified with --global-database. If this is placed in your ~/.todorc it will force todo to use that database to the exclusion of all others. 👑
  • --database <file> — Change the database from whatever the default is (typically '.todo') to the file specified. 🗂️
  • -T, --TODO — Generate a typical TODO output text file from a Todo DB. 📄
  • -A, --all — Shortcut for the filter '+done,+children' to show all notes. 🌈
  • -f, --filter <filter> — Display only those notes that pass the filter. Please refer the section FILTERS for more information. 🔍
  • --colour <colours> — Override default colours of todo items. Please refer to the section COLOUR for more information. 🎨
  • --force-colour — Force use of colour even when not outputting to a TTY. This is useful when piping to less(1) -R. 🌺
  • --mono — Remove all ANSI escape sequences from output - useful for colour impaired terminals. 🖤
  • --help — Display this help. 🫶
  • --version — Display version of ToDo. 🏷️
  • --title [<text>] — Set the title of this directory's todo notes. 📛
  • --date-format <format> — Format the display of time values. The format is that used by strftime(3). The default format is '%c'. This option is best specified in the ~/.todorc. 🕰️
  • --format <identifier>=<format> — Specify the formatting of output. Please refer to the section FORMATTING for more information. ✨
  • --use-format <builtin>=<identifier> — Use the format string identified by <identifier> (defined with --format) as the format string to use when formatting with the builtin format <builtin>. 🧚
  • --sort <expression> — Sort the database with the specified expression. Refer to the section SORTING for more detailed information. 🔤
  • --paranoid — Be paranoid about some settings, including permissions. 👀
  • --database-loaders <loader list> — Try the database formats in the given order. Valid formats are xml and binary. eg. todo --database-loaders binary,xml. The default format is XML. 🧳
  • --backup [<n>] — Backup the database up to <n> times, just before it is written to. If <n> is not specified, one backup will be made. The filenames used to store the backups are the default database name with their revision appended like so: .todo.1, .todo.2, etc. To actually use one of these backups, you can either mv it to .todo or use --database .todo.<n> to explicitly specify its use. 💾
  • -s, --summary — Toggle "summary" mode, where long items are truncated to one line. ✂️
  • -c, --comment — Edit or show comments respectively. 💬
  • --timeout [<time>] — If <time> is specified, the timeout between database displays is set to this number of seconds. If no <time> is specified, the behaviour is to display the database only if it has not been displayed for the number of seconds specified by --timeout with the <time> given. eg. todo --timeout 10 --timeout would only display the database at most once every 10 seconds. Putting a timeout 10 in your ~/.todorc is a good option, then the --timeout in the doc/scripts.* will mean that the database won't be displayed every time you cd into a directory. ⏳
  • --purge [<days-old>] — Purge all completed items older than <days-old>. If <days-old> is omitted, all completed records are purged. 🧹
ngl bestie, that's a lot of flags. but they're all important, so we listed every single one. periodt. 💅

⭐ PRIORITIES ⭐

Priorities can be specified symbolically using the words default, veryhigh, high, medium, low and verylow. 🌈

The default priority has special meaning in that it will use the default priority for any action. This means that when editing an existing item, its priority is preserved; when creating a new item, the priority will be set to medium; when grafting a new item, its priority will be that of its parent. DevTodo will not prompt for priority if this is specified, making it a handy feature for your todorc. As with all options, the priority can be overridden on the command line. 👑

so like, default is the chill one that just reads the room. 🫶

🔍 FILTERS 🔍

Filters are comprised of a list of expressions used to define the notes that are displayed. ✨

The general format of a filter expression is:

([-|=|+](all|children|done|<index>|<priority>)) | (/<search expression>)

Generally, if a filter expression is prefixed with a '-' it will not display items that match the expression, if prefixed with a '+' it will display items that match this expression in addition to others, or if prefixed with a '=' (or no prefix at all) it will display only those items that match the expression. Note that this will only search items not excluded by other filters, so to search the entire database you will have to do something like: todo --filter all,/some-search-string. 🔎

The second form of filter expression is used for searching for text in a database. <search expression> is a regular expression which is matched against the text body of each item. 🧵

Filter atoms are filtered in order by done state, priority, then search. So first items that do not match the "done" filter will be excluded, then those that do not match the priority filter, and so on. 📋

The expressions in detail:

  • all — Forces all items to be displayed. The various prefixes have no effect on this expression. 🌈
  • children — Collapse or expand child items. If the '-' prefix is present children are collapsed, otherwise children are displayed. 🧸
  • done — Filter on whether an item is completed or not. ✅
  • <index> — Note indices are specified as numbers. Ranges can be given ala '1.2.10-20'. 🔢
  • <priority> — Priorities are specified as described in the PRIORITIES section. A prefix of '-' will display all items with priorities less than or equal to the given priority. With a '+' prefix, all items with priorities greater than or equal to the given priority are shown. If '=' or no prefix is given, only items with the specified priority are displayed. ⭐

🍓 Examples 🍓

todo --filter done,-children,+low

This will display only those items that are done and have a priority of low or higher. In addition, children will be collapsed. 💅

todo /[Tt]he

Display only those items with the word 'the' in them, where the first letter can be lower or upper case. It may be necessary to quote the search expression to ensure the shell does not interpret them. 😭 the shell is always trying something. quote your regexes bestie.

💅 FORMATTING 💅

okay bestie so listen — you can totally change how todo spits out its output by writing your own format strings. They're like the ones you already know from printf(3) and strftime(3), so if you've met those, you're already fluent. iykyk.

These examples, which you can drop right into ~/.todorc, will give you the default behaviour back:

# Display in default format
format display=%i%[info]%f%2n.%[priority]%T

# Display in default format
format generated=%2i-%T%2i  (added %d, priority %p)\n\n

There are four separate format options: display, generated, verbose-display and verbose-generated. The last two are the ones that format their respective text when you pass --verbose to todo. slay.

And bestie, it gets better — you can make your own format strings from scratch by just handing format a different identifier. Then you turn it on with --use-format. for example:

format full-report=%i%[info]%f%2n.%[priority]%+1T%+1i%[info]Added: %[normal]%c  %[info]Completed: %[normal]%d\n%+1i%[info]Duration: %[normal]%D  %[info]Priority: %[normal]%p\n\n
# Override the display format to use "full-report".
use-format display=full-report

Now the flags you've got available, one by one, no skips:

  • %<n>> — the > flag sets how many spaces <n> to use for all future indenting.
  • %[+|-][<n>]i — indent to the depth of the current item. <n> says which depth to indent to. Leave <n> out and it uses the current level. Relative values work too! eg. %+1T would indent one level higher than the current indentation level.
  • %[+|-][<n>]T — shows the text of the item, wrapped at 80 characters and indented to the level you picked. <n> means the same thing as with %i. Heads up: wrapped text automatically adds a '0 at the end of the text, whereas %t will not.
  • %t — the unwrapped, unformatted text of the item.
  • %s — summary text (ie. one line only, equivalent to --summary).
  • %p — the priority level of the current item.
  • %c — the current item's creation date, formatted according to --date-format.
  • %d — the date when the item was marked as done, formatted according to --date-format.
  • %D — the duration of the item, formatted according to --date-format.
  • %[<n>]n — the index number of the current item. That optional numeric <n> says how many characters the number should occupy, and it gets padded out with spaces to fill exactly that many.
  • %f — the state flag of the current item. Displayed values: + means children, - means done, * means done with children.
  • %F — the human readable state flag of the current item. Displayed values: 'children', 'done' means done, 'done, children' and 'open'.
  • %[<colour>] — colours, babes! Valid values for <colour> are: verylow, low, medium, high, veryhigh, title, info, and priority. Pretty self explanatory, except priority changes to the current item's priority colour. eg. %[priority]
🫶 one thing though: when you're indenting, you'll typically want a prefix value of +1 with %T. ie. %+1T. That forces the text to indent one level deeper than the current level, so it sits all pretty and away from whatever other formatting you've got going on.

🔥 SORTING 🔥

The display of items in the database can be sorted on a variety of keys. Give todo a series of keys and it sorts on each successive one, only moving to the next if the previous comparison came out equal. like so:

todo --sort -done,text

This sorts first by whether an item is completed, and second by their text. Which effectively groups your items into two blocks — the complete ones and the not-complete ones. iconic.

The keys available are created, completed, text, priority, duration, none and done. Every key except none can be prefixed with a - to reverse its default order, and multiple keys must be separated with a ,.

If multiple --sort parameters show up, the last one wins. Which means a sort entry sitting in ~/.todorc will get overridden by anything on the command line. periodt.

🎀 INDICES 🎀

Indices get used as options to a bunch of command line arguments. Multiple note indices are separated with commas (spaces are not allowed, bestie, don't try it). Children are scoped using a ..

For example, given these notes:

1. Do man pages
   1. Make them more beautiful.
   2. Make HTML documentation as well.

The second sub-item would be represented like this: 1.2

The wildcard * represents all children of a node. eg. 1.*

Ranges of notes can be specified with <a>-<b>. For example, to mark notes 10.1.2, 10.1.3 and 10.3.4 as done, you could do:

todo --done 10.1.2-4

🌈 COLOUR 🌈

Various items can be colourised, and the ones that can are veryhigh, high, medium, low, verylow, title and info. (info is what shows item numbers and general information.)

These items can be set to one of eight colours. Those colours are black, red, green, yellow, blue, magenta, cyan, white and default. The colour default is used to specify the default foreground terminal colour.

Colours are specified like so:

<item>=[+]<colour>

If that optional + is in there, it makes the item bold.

For example, a line in your ~/.todorc might look like:

colour    medium=+white

Which would make medium text bold white. 💅

🦋 TODORC 🦋

todo can load options from a number of resource files. The order it parses them in is:

  1. The file specified in the environment variable TODORC or, if that does not exist, /etc/todorc.
  2. ~/.todorc

Options are cumulative, meaning those loaded from $TODORC will be overridden or added to by those in ~/.todorc.

These options are specified as key/value pairs, one per line. The key is the long name of a command line argument and the value is the parameter to that argument, if any. And yes, environment variables get expanded. 🌸

For example, the --filter command line argument accepts a parameter that's a filter expression. A default filter could be added to ~/.todorc like so:

# Don't display child items by default
filter -children

The only difference between options in the rc file and options on the command line is that rc file options are not prefixed by --.

Plus, there are two commands available in the RC file that you can't use on the command line:

The first command, on, is used to conditionally add specific commands. Its format is: on <event> <command> [<arguments>]. Valid events are add, remove, view, edit, generate, done, notdone, title, reparent, load, save, link, create and purge. You can pass multiple commands to on by enclosing them in braces (whitespace is required between tokens). Full example below. 👇

The second command is exec <shell command>. This will execute the argument it's given in a shell. The environment variable $TODODB contains the filename of the current database. eg. exec chmod 600 $TODODB

There's an example rc file in the doc subdirectory of the source distribution. go look, bestie.

✨ EXAMPLES ✨

Wanna see any outstanding items in the current directory? simply type:

todo

To remove notes 1, 2 and 4:

todo --remove 1,2,4

To display ALL items:

todo all

To display only the top-level items and not their children:

todo -children

(even though -children is not a valid argument, this works because todo interprets any command line arguments it doesn't recognise as being part of a filter expression. sneaky but it ate.)

A more complex example. This adds a new item, with the text of the item specified on the command line, with a priority of high, as a child of the third child of the second item (if that makes any sense):

todo -a "Fix the man page" -p high -g 2.3

This next one is how you use the TODO feature of todo. It makes todo generate a new TODO file from the information stored in the database. This particular example outputs all items to the TODO file, even those marked as done:

todo --filter all --TODO

And this one is a nice use of the event triggers. When a new database is created it'll force its permissions to 0600:

on create {
     verbose
     exec chmod 600 .todo
}

🍓 FILES 🍓

  • .todo — Items are stored as XML in this file.
  • /etc/todorc — Default options can be specified in this file. Please refer to the section TODORC for more information.
  • ~/.todorc — User-specific options are specified in this file. Please refer to the section TODORC for more information.

👑 AUTHORS 👑

Alec Thomas <alec@swapoff.org>

💜 SEE ALSO 💜

phpsat <http://sourceforge.net/projects/phpsat>

and that's the whole page, bestie!! 🫶 this one's from Alec Thomas, version 0.1.20, and it's the devtodo(1) man page — read it, love it, live it. no cap. 💖✨

📦 where this page comes from