NAME
todo - a reminder/task program aimed at developers
SYNPOSIS
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.
todo --link [-g <index>] <database>
Link the specified devtodo database into the current one,
optionally grafting it as a child of the specified index.
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.
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
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.
-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.
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.
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.
FORMATTING
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 seperate 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:
%<n>> The > flag sets the number of spaces <n> to use for all future
indenting.
%[+|-][<n>]i
Indent to depth of current item. <n> specifies the depth to
indent to. If <n> is ommitted, the current level is used.
Relative values can be used. eg. ’%+1T’ would indent to one
level higher than the current indentation level.
%[+|-][<n>]T
Display the text of the item, wrapped at 80 characters and
indented to the specified level. Semantics of <n> are as with
%i. Note that wrapped text automatically adds a ’0 at the end of
the text, whereas %t will not.
%t 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 items 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. The optional numeric value
<n> specifies the number of characters the number should occupy.
The number is padded out with spaces so as to fill this number
of characters.
%f The state flag of the current item. The displayed values for
this flag are ’+’ means children, ’-’ means done’, ’*’ means
done with children.
%F The human readable state flag of the current item. The displayed
values for this flag are ’children’, ’done’ means done’, ’done,
children’ and ’open’.
%[<colour>]
Colours can be specified with this flag. The valid values for
<colour> are: verylow, low, medium, high, veryhigh, title, info,
and priority. These are fairly self explanatory, except priority
changes to the current items priority colour. eg. %[priority]
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.
SORTING
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 seperated 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.
INDICES
Indicies are used as options to a variety of command line arguments.
Multiple note indices are seperated 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
COLOUR
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.
TODORC
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.
EXAMPLES
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
}
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>