1devtodo(1) Programming utility devtodo(1)
2
6 todo - a reminder/task program aimed at developers
7
9 todo [<options>]
10 With no options, displays the items in the current directory.
11 tda [-p <priority>] [-g <index>] [<text>]
13 Add a new item, optionally grafting it as a child of the given
14 item.
15 tde <index>
17 Edit the given item.
18 tdr <indices>
20 Remove the given items.
21 tdd <indices>
23 Mark the specified items as being done.
24 tdl [-g <index>] <database>
26 Link the specified devtodo database into the current one,
27 optionally grafting it as a child of the specified index.
28
30 todo is a program aimed specifically at programmers (but usable by any‐
31 body at the terminal) to aid in day-to-day development.
32 It maintains a list of items that have yet to be completed. This allows
34 the programmer to track outstanding bugs or items that need to be com‐
35 pleted with very little effort.
36 Items can be prioritised and can also be displayed in a hierarchy, so
38 that one item may depend on another.
39 With the use of some small shell scripts (scripts.* in the doc direc‐
41 tory of the source distribution), todo can also display the outstanding
42 items in a directory as you change into it. So, for example, if you cd
43 into the source directory for todo itself you should see a list of out‐
44 standing items...unless all of the bugs have been fixed ;).
45
47 Options can have both a long and a short form.
48 Short options can be combined into one argument by using a hyphen fol‐
50 lowed by a string of short options. Parameters of short options can
51 also be appended to this string.
52 -v, --verbose
54 Display verbosely
55 -a, --add [<text>]
57 Add a note (will prompt for a note if one is not supplied).
58 -g, --graft <index>
60 In conjunction with --add or --link, graft the new item to the
61 specified item.
62 -l, --link <database>
64 Link the specified todo file into the body of this one. If the
65 linked database has a title set, this will be used as the body
66 of the linking item otherwise the directory name of the linked
67 database will be used. Use --remove (or tdr) to remove linked
68 databases - this does not remove the database itself, only the
69 link.
70 -R,--reparent <index>[,<index>]
72 Change the parent of the first item index to the second item
73 index. If no second index is given the item is reparented to the
74 root of the tree.
75 -p, --priority <priority>
77 In conjunction with --add or --edit, set the priority (default |
78 veryhigh | high | medium | low | verylow)
79 -e, --edit <index>
81 Edit the note that is indexed by the given number.
82 --remove <indices>
84 Remove the note indexed by the given numbers, including any
85 children.
86 -d, --done <indices>
88 Mark the specified notes (and their children) as done.
89 -D, --not-done <indices>
91 Mark the specified notes (and all children) as not done.
92 --global-database <file>
94 Specify the database to use if either the -G or --global options
95 are specified.
96 -G, --global
98 Force todo to use the database specified with --global-database.
99 If this is placed in your ~/.todorc it will force todo to use
100 that database to the exclusion of all others.
101 --database <file>
103 Change the database from whatever the default is (typically
104 '.todo') to the file specified.
105 -T, --TODO
107 Generate a typical TODO output text file from a Todo DB.
108 -A, --all
110 Shortcut for the filter '+done,+children' to show all notes.
111 -f, --filter <filter>
113 Display only those notes that pass the filter. Please refer the
114 section FILTERS for more information.
115 --colour <colours>
117 Override default colours of todo items. Please refer to the sec‐
118 tion COLOUR for more information.
119 --force-colour
121 Force use of colour even when not outputting to a TTY. This is
122 useful when piping to less(1) -R.
123 --mono Remove all ANSI escape sequences from output - useful for colour
125 impaired terminals.
126 --help Display this help.
128 --version
130 Display version of ToDo.
131 --title [<text>]
133 Set the title of this directory's todo notes.
134 --date-format <format>
136 Format the display of time values. The format is that used by
137 strftime(3). The default format is '%c'. This option is best
138 specified in the ~/.todorc.
139 --format <identifier>=<format>
141 Specify the formatting of output. Please refer to the section
142 FORMATTING for more information.
143 --use-format <builtin>=<identifier>
145 Use the format string identified by <identifier> (defined with
146 --format) as the format string to use when formatting with the
147 builtin format <builtin>.
148 --sort <expression>
150 Sort the database with the specified expression. Refer to the
151 section SORTING for more detailed information.
152 --paranoid
154 Be paranoid about some settings, including permissions.
155 --database-loaders <loader list>
157 Try the database formats in the given order. Valid formats are
158 xml and binary. eg. todo --database-loaders binary,xml. The
159 default format is XML.
160 --backup [<n>]
162 Backup the database up to <n> times, just before it is written
163 to. If <n> is not specified, one backup will be made. The file‐
164 names used to store the backups are the default database name
165 with their revision appended like so: .todo.1, .todo.2, etc. To
166 actually use one of these backups, you can either mv it to .todo
167 or use --database .todo.<n> to explicitly specify its use.
168 -s, --summary
170 Toggle "summary" mode, where long items are truncated to one
171 line.
172 -c, --comment
174 Edit or show comments respectively.
175 --timeout [<time>]
177 If <time> is specified, the timeout between database displays is
178 set to this number of seconds. If no <time> is specified, the
179 behaviour is to display the database only if it has not been
180 displayed for the number of seconds specified by --timeout with
181 the <time> given. eg. todo --timeout 10 --timeout would only
182 display the database at most once every 10 seconds. Putting a
183 timeout 10 in your ~/.todorc is a good option, then the --time‐
184 out in the doc/scripts.* will mean that the database won't be
185 displayed every time you cd into a directory.
186 --purge [<days-old>]
188 Purge all completed items older than <days-old>. If <days-old>
189 is omitted, all completed records are purged.
190
192 Priorities can be specified symbolically using the words default, very‐
193 high, high, medium, low and verylow.
194 The default priority has special meaning in that it will use the
196 default priority for any action. This means that when editing an exist‐
197 ing item, its priority is preserved; when creating a new item, the pri‐
198 ority will be set to medium; when grafting a new item, its priority
199 will be that of its parent. DevTodo will not prompt for priority if
200 this is specified, making it a handy feature for your todorc. As with
201 all options, the priority can be overridden on the command line.
202
204 Filters are comprised of a list of expressions used to define the notes
205 that are displayed.
206 The general format of a filter expression is:
208 ([-|=|+](all|children|done|<index>|<priority>)) | (/<search expres‐
210 sion>)
211 Generally, if a filter expression is prefixed with a '-' it will not
213 display items that match the expression, if prefixed with a '+' it will
214 display items that match this expression in addition to others, or if
215 prefixed with a '=' (or no prefix at all) it will display only those
216 items that match the expression. Note that this will only search items
217 not excluded by other filters, so to search the entire database you
218 will have to do something like: todo --filter all,/some-search-string.
219 The second form of filter expression is used for searching for text in
221 a database. <search expression> is a regular expression which is
222 matched against the text body of each item.
223 Filter atoms are filtered in order by done state, priority, then
225 search. So first items that do not match the "done" filter will be
226 excluded, then those that do not match the priority filter, and so on.
227 The expressions in detail:
229 all Forces all items to be displayed. The various prefixes have no
231 effect on this expression.
232 children
234 Collapse or expand child items. If the '-' prefix is present
235 children are collapsed, otherwise children are displayed.
236 done Filter on whether an item is completed or not.
238 <index>
240 Note indices are specified as numbers. Ranges can be given ala
241 '1.2.10-20'.
242 <priority>
244 Priorities are specified as described in the PRIORITIES section.
245 A prefix of '-' will display all items with priorities less than
246 or equal to the given priority. With a '+' prefix, all items
247 with priorities greater than or equal to the given priority are
248 shown. If '=' or no prefix is given, only items with the speci‐
249 fied priority are displayed.
250 Examples:
252 todo --filter done,-children,+low
254 This will display only those items that are done and have a priority of
256 low or higher. In addition, children will be collapsed.
257 todo /[Tt]he
259 Display only those items with the word 'the' in them, where the first
261 letter can be lower or upper case. It may be necessary to quote the
262 search expression to ensure the shell does not interpret them.
263
265 The output of todo can be changed to be more to your liking by defining
266 your own formatting strings. These strings are similar to those used in
267 printf(3) and strftime(3).
268 The following examples, which can be placed in ~/.todorc, will mimic
270 the default behaviour:
271 # Display in default format
273 format display=%i%[info]%f%2n.%[priority]%T
274 # Display in default format
276 format generated=%2i-%T%2i (added %d, priority %p)\n\n
277 There are four seperate format options: display, generated, ver‐
279 bose-display and verbose-generated. The latter two are used to format
280 their respective text when --verbose is specified as an argument to
281 todo.
282 In addition, users can create their own format strings by simply pass‐
284 ing a different identifier to format. This can then be enabled by using
285 --use-format. eg.
286 format full-report=%i%[info]%f%2n.%[priority]%+1T%+1i%[info]Added:
288 %[normal]%c %[info]Completed: %[normal]%d\n%+1i%[info]Duration: %[nor‐
289 mal]%D %[info]Priority: %[normal]%p\n\n
290 # Override the display format to use "full-report".
291 use-format display=full-report
292 The various flags that are available are:
294 %<n>> The > flag sets the number of spaces <n> to use for all future
296 indenting.
297 %[+|-][<n>]i
299 Indent to depth of current item. <n> specifies the depth to
300 indent to. If <n> is ommitted, the current level is used. Rela‐
301 tive values can be used. eg. '%+1T' would indent to one level
302 higher than the current indentation level.
303 %[+|-][<n>]T
305 Display the text of the item, wrapped at 80 characters and
306 indented to the specified level. Semantics of <n> are as with
307 %i. Note that wrapped text automatically adds a '0 at the end of
308 the text, whereas %t will not.
309 %t Unwrapped, unformatted text of the item.
311 %s Summary text (ie. one line only, equivalent to --summary).
313 %p The priority level of the current item.
315 %c The current items creation date, formatted according to --date-
317 format.
318 %d The date when the item was marked as done, formatted according
320 to --date-format.
321 %D The duration of the item, formatted according to --date-format.
323 %[<n>]n
325 The index number of the current item. The optional numeric value
326 <n> specifies the number of characters the number should occupy.
327 The number is padded out with spaces so as to fill this number
328 of characters.
329 %f The state flag of the current item. The displayed values for
331 this flag are '+' means children, '-' means done', '*' means
332 done with children.
333 %F The human readable state flag of the current item. The displayed
335 values for this flag are 'children', 'done' means done', 'done,
336 children' and 'open'.
337 %[<colour>]
339 Colours can be specified with this flag. The valid values for
340 <colour> are: verylow, low, medium, high, veryhigh, title, info,
341 and priority. These are fairly self explanatory, except priority
342 changes to the current items priority colour. eg. %[priority]
343 Please note that when indenting, you will typically want to use a pre‐
345 fix value of '+1' with %T. ie. %+1T. This forces the text to indent to
346 one level deeper than the current level, making it sit away from any
347 other formatting you may have used.
348
350 The display of items in the database can be sorted on a variety of
351 keys. Given a series of keys todo sorts on each successive key, contin‐
352 uing to the next only if the previous key comparison was equal. For
353 example:
354 todo --sort -done,text
356 This will sort firstly by whether an item is completed and secondly by
358 their text. This effectively groups items into two blocks - those that
359 are complete and those that aren't.
360 The keys that are available are created, completed, text, priority,
362 duration, none and done. Each key, except none can be prefixed with a -
363 to reverse its default order and multiple keys must be seperated with a
364 ,.
365 If multiple --sort parameters are encountered the last one is used.
367 This means that a 'sort' entry in ~/.todorc will be overridden by any
368 on the command line.
369
371 Indicies are used as options to a variety of command line arguments.
372 Multiple note indices are seperated with commas (spaces are not
373 allowed). Children are scoped using a '.'.
374 For example, given the following notes:
376 1. Do man pages
378 1. Make them more beautiful.
379 2. Make HTML documentation as well.
380 The second sub-item would be represented like this: 1.2
382 The wildcard '*' can be used to represent all children of a node. eg.
384 1.*
385 Ranges of notes can be specified by using '<a>-<b>'. For example, to
387 mark notes 10.1.2, 10.1.3 and 10.3.4 as done, you could do: todo --done
388 10.1.2-4
389
391 Various items can be colourised. Items that can are veryhigh, high,
392 medium, low, verylow, title and info. info is used for displaying item
393 numbers and general information.
394 These items can be set to one of eight colours. Those colours are
396 black, red, green, yellow, blue, magenta, cyan, white and default. The
397 colour default is used to specify the default foreground terminal
398 colour.
399 Colours are specified like so:
401 <item>=[+]<colour>
403 If the optional + in this expression is used it will cause the item to
405 become bold.
406 For example, a line in your ~/.todorc might look like:
408 colour medium=+white
410 Which would make medium text bold white.
412
414 todo can load options from a number of resource files. The order in
415 which these are parsed is as follows:
416 1. The file specified in the environment variable TODORC or, if that
418 does not exist, /etc/todorc.
419 2. ~/.todorc
420 Options are cumulative in that those loaded from $TODORC will be over‐
422 ridden or added to by those in ~/.todorc.
423 These options are specified as key/value pairs, one per line The key is
425 the long name of a command line argument and the value is the parameter
426 to that argument,if any. In addition, environment variables are
427 expanded.
428 For example, the --filter command line argument accepts a parameter
430 that is a filter expression. A default filter could be added to the
431 ~/.todorc file like so:
432 # Don't display child items by default
434 filter -children
435 The only difference between options specified in the rc file and those
437 on the command line is that options in the rc file are not prefixed by
438 --.
439 In addition, there are two commands available in the RC file that are
441 not available on the command line. They are:
442 The first command, on, is used to conditionally add specific commands.
444 The format of this command is: on <event> <command> [<arguments>].
445 Valid events are add, remove, view, edit, generate, done, notdone,
446 title, reparent, load, save, link, create and purge. Multiple commands
447 can be passed to on by enclosing them in braces (whitespace is required
448 between tokens). Full example below.
449 The second command is exec <shell command>. This command will execute
451 the argument it is given in a shell. The environment variable $TODODB
452 contains the filename of the current database. eg. exec chmod 600
453 $TODODB
454 There is an example rc file in the doc subdirectory of the source dis‐
456 tribution.
457
459 To display any outstanding items in the current directory, simply type:
460 todo
462 To remove notes 1, 2 and 4:
464 todo --remove 1,2,4
466 To display ALL items:
468 todo all
470 To display only the top-level items and not their children:
472 todo -children
474 (even though -children is not a valid argument, this works because todo
476 interprets any command line arguments it doesn't recognise as being
477 part of a filter expression)
478 A more complex example. This adds a new item, with the text of the item
480 specified on the command line, with a priority of high as a child of
481 the third child of the second item (if that makes any sense):
482 todo -a "Fix the man page" -p high -g 2.3
484 This is an example of how to use the TODO feature of todo. It makes
486 todo generate a new TODO file from the information stored in the data‐
487 base. This particular example outputs all items to the TODO file, even
488 those marked as done.
489 todo --filter all --TODO
491 This example shows a nice use of the event triggers. When a new data‐
493 base is created it will force its permissions to 0600.
494 on create {
496 verbose
497 exec chmod 600 .todo
498 }
499
501 .todo Items are stored as XML in this file.
502 /etc/todorc
504 Default options can be specified in this file. Please refer to
505 the section TODORC for more information.
506 ~/.todorc
508 User-specific options are specified in this file. Please refer
509 to the section TODORC for more information.
510
512 Alec Thomas <alec@swapoff.org>
513
515 phpsat <http://sourceforge.net/projects/phpsat>
516Alec Thomas 0.1.20 devtodo(1)