| devtodo(1) | Programming utility | devtodo(1) |
todo - a reminder/task program aimed at developers
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.
Items can be prioritised and can also be displayed in a hierarchy, so that one item may depend on another.
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 ;).
Options can have both a long and a short form.
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.
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.
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:
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 output of todo can be changed to be more to your liking by defining your own formatting strings. These strings are similar to those used in printf(3) and strftime(3).
The following examples, which can be placed in ~/.todorc, will mimic the default behaviour:
# 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 latter two are used to format their respective text when --verbose is specified as an argument to todo.
In addition, users can create their own format strings by simply passing a different identifier to format. This can then be enabled by using --use-format. eg.
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
The various flags that are available are:
Please note that when indenting, you will typically want to use a prefix value of '+1' with %T. ie. %+1T. This forces the text to indent to one level deeper than the current level, making it sit away from any other formatting you may have used.
The display of items in the database can be sorted on a variety of keys. Given a series of keys todo sorts on each successive key, continuing to the next only if the previous key comparison was equal. For example:
todo --sort -done,text
This will sort firstly by whether an item is completed and secondly by their text. This effectively groups items into two blocks - those that are complete and those that aren't.
The keys that are available are created, completed, text, priority, duration, none and done. Each 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 are encountered the last one is used. This means that a 'sort' entry in ~/.todorc will be overridden by any on the command line.
Indicies are used as options to a variety of command line arguments. Multiple note indices are separated with commas (spaces are not allowed). Children are scoped using a '.'.
For example, given the following 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 '*' can be used to represent all children of a node. eg. 1.*
Ranges of notes can be specified by using '<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
Various items can be colourised. Items that can are veryhigh, high, medium, low, verylow, title and info. info is used for displaying 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 the optional + in this expression is used it will cause the item to become bold.
For example, a line in your ~/.todorc might look like:
colour medium=+white
Which would make medium text bold white.
todo can load options from a number of resource files. The order in which these are parsed is as follows:
1. The file specified in the environment variable TODORC
or, if that does not exist, /etc/todorc.
2. ~/.todorc
Options are cumulative in that 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. In addition, environment variables are expanded.
For example, the --filter command line argument accepts a parameter that is a filter expression. A default filter could be added to the ~/.todorc file like so:
# Don't display child items by default
filter -children
The only difference between options specified in the rc file and those on the command line is that options in the rc file are not prefixed by --.
In addition, there are two commands available in the RC file that are not available on the command line. They are:
The first command, on, is used to conditionally add specific commands. The format of this command is: on <event> <command> [<arguments>]. Valid events are add, remove, view, edit, generate, done, notdone, title, reparent, load, save, link, create and purge. Multiple commands can be passed to on by enclosing them in braces (whitespace is required between tokens). Full example below.
The second command is exec <shell command>. This command will execute the argument it is given in a shell. The environment variable $TODODB contains the filename of the current database. eg. exec chmod 600 $TODODB
There is an example rc file in the doc subdirectory of the source distribution.
To display 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)
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 is an example of how to 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
This example shows a nice use of the event triggers. When a new
database is created it will force its permissions to 0600.
on create {
verbose
exec chmod 600 .todo
}
Alec Thomas <alec@swapoff.org>
phpsat <http://sourceforge.net/projects/phpsat>
| 0.1.20 | Alec Thomas |