1devtodo(1)                    Programming utility                   devtodo(1)
2
3
4

NAME

6       todo - a reminder/task program aimed at developers
7

SYNPOSIS

9       todo [<options>]
10              With no options, displays the items in the current directory.
11
12       tda [-p <priority>] [-g <index>] [<text>]
13              Add  a  new item, optionally grafting it as a child of the given
14              item.
15
16       tde <index>
17              Edit the given item.
18
19       tdr <indices>
20              Remove the given items.
21
22       tdd <indices>
23              Mark the specified items as being done.
24
25       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

DESCRIPTION

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
33       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
37       Items can be prioritised and can also be displayed in a  hierarchy,  so
38       that one item may depend on another.
39
40       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

OPTIONS

47       Options can have both a long and a short form.
48
49       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
53       -v, --verbose
54              Display verbosely
55
56       -a, --add [<text>]
57              Add a note (will prompt for a note if one is not supplied).
58
59       -g, --graft <index>
60              In  conjunction  with --add or --link, graft the new item to the
61              specified item.
62
63       -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
71       -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
76       -p, --priority <priority>
77              In conjunction with --add or --edit, set the priority (default |
78              veryhigh | high | medium | low | verylow)
79
80       -e, --edit <index>
81              Edit the note that is indexed by the given number.
82
83       --remove <indices>
84              Remove the note indexed by  the  given  numbers,  including  any
85              children.
86
87       -d, --done <indices>
88              Mark the specified notes (and their children) as done.
89
90       -D, --not-done <indices>
91              Mark the specified notes (and all children) as not done.
92
93       --global-database <file>
94              Specify the database to use if either the -G or --global options
95              are specified.
96
97       -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
102       --database <file>
103              Change the database from  whatever  the  default  is  (typically
104              '.todo') to the file specified.
105
106       -T, --TODO
107              Generate a typical TODO output text file from a Todo DB.
108
109       -A, --all
110              Shortcut for the filter '+done,+children' to show all notes.
111
112       -f, --filter <filter>
113              Display  only those notes that pass the filter. Please refer the
114              section FILTERS for more information.
115
116       --colour <colours>
117              Override default colours of todo items. Please refer to the sec‐
118              tion COLOUR for more information.
119
120       --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
124       --mono Remove all ANSI escape sequences from output - useful for colour
125              impaired terminals.
126
127       --help Display this help.
128
129       --version
130              Display version of ToDo.
131
132       --title [<text>]
133              Set the title of this directory's todo notes.
134
135       --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
140       --format <identifier>=<format>
141              Specify  the  formatting  of output. Please refer to the section
142              FORMATTING for more information.
143
144       --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
149       --sort <expression>
150              Sort the database with the specified expression.  Refer  to  the
151              section SORTING for more detailed information.
152
153       --paranoid
154              Be paranoid about some settings, including permissions.
155
156       --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
161       --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
169       -s, --summary
170              Toggle "summary" mode, where long items  are  truncated  to  one
171              line.
172
173       -c, --comment
174              Edit or show comments respectively.
175
176       --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
187       --purge [<days-old>]
188              Purge  all  completed items older than <days-old>. If <days-old>
189              is omitted, all completed records are purged.
190

PRIORITIES

192       Priorities can be specified symbolically using the words default, very‐
193       high, high, medium, low and verylow.
194
195       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

FILTERS

204       Filters are comprised of a list of expressions used to define the notes
205       that are displayed.
206
207       The general format of a filter expression is:
208
209       ([-|=|+](all|children|done|<index>|<priority>))  |  (/<search   expres‐
210       sion>)
211
212       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
220       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
224       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
228       The expressions in detail:
229
230       all    Forces  all  items to be displayed. The various prefixes have no
231              effect on this expression.
232
233       children
234              Collapse or expand child items. If the  '-'  prefix  is  present
235              children are collapsed, otherwise children are displayed.
236
237       done   Filter on whether an item is completed or not.
238
239       <index>
240              Note  indices  are specified as numbers. Ranges can be given ala
241              '1.2.10-20'.
242
243       <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
251       Examples:
252
253       todo --filter done,-children,+low
254
255       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
258       todo /[Tt]he
259
260       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

FORMATTING

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
269       The following examples, which can be placed in  ~/.todorc,  will  mimic
270       the default behaviour:
271
272       # Display in default format
273       format display=%i%[info]%f%2n.%[priority]%T
274
275       # Display in default format
276       format generated=%2i-%T%2i  (added %d, priority %p)\n\n
277
278       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
283       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
287       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
293       The various flags that are available are:
294
295       %<n>>  The > flag sets the number of spaces <n> to use for  all  future
296              indenting.
297
298       %[+|-][<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
304       %[+|-][<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
310       %t     Unwrapped, unformatted text of the item.
311
312       %s     Summary text (ie. one line only, equivalent to --summary).
313
314       %p     The priority level of the current item.
315
316       %c     The  current items creation date, formatted according to --date-
317              format.
318
319       %d     The date when the item was marked as done,  formatted  according
320              to --date-format.
321
322       %D     The duration of the item, formatted according to --date-format.
323
324       %[<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
330       %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
334       %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
338       %[<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
344       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

SORTING

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
355       todo --sort -done,text
356
357       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
361       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
366       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

INDICES

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
375       For example, given the following notes:
376
377       1. Do man pages
378          1. Make them more beautiful.
379          2. Make HTML documentation as well.
380
381       The second sub-item would be represented like this: 1.2
382
383       The wildcard '*' can be used to represent all children of a  node.  eg.
384       1.*
385
386       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

COLOUR

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
395       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
400       Colours are specified like so:
401
402       <item>=[+]<colour>
403
404       If the optional + in this expression is used it will cause the item  to
405       become bold.
406
407       For example, a line in your ~/.todorc might look like:
408
409       colour    medium=+white
410
411       Which would make medium text bold white.
412

TODORC

414       todo  can  load  options  from a number of resource files. The order in
415       which these are parsed is as follows:
416
417       1. The file specified in the environment variable TODORC  or,  if  that
418       does not exist, /etc/todorc.
419       2. ~/.todorc
420
421       Options  are cumulative in that those loaded from $TODORC will be over‐
422       ridden or added to by those in ~/.todorc.
423
424       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
429       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
433       # Don't display child items by default
434       filter -children
435
436       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
440       In  addition,  there are two commands available in the RC file that are
441       not available on the command line. They are:
442
443       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
450       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
455       There is an example rc file in the doc subdirectory of the source  dis‐
456       tribution.
457

EXAMPLES

459       To display any outstanding items in the current directory, simply type:
460
461            todo
462
463       To remove notes 1, 2 and 4:
464
465            todo --remove 1,2,4
466
467       To display ALL items:
468
469            todo all
470
471       To display only the top-level items and not their children:
472
473            todo -children
474
475       (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
479       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
483            todo -a "Fix the man page" -p high -g 2.3
484
485       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
490            todo --filter all --TODO
491
492       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
495            on create {
496                 verbose
497                 exec chmod 600 .todo
498            }
499

FILES

501        .todo Items are stored as XML in this file.
502
503       /etc/todorc
504              Default  options  can be specified in this file. Please refer to
505              the section TODORC for more information.
506
507       ~/.todorc
508              User-specific options are specified in this file.  Please  refer
509              to the section TODORC for more information.
510

AUTHORS

512       Alec Thomas <alec@swapoff.org>
513

SEE ALSO

515       phpsat <http://sourceforge.net/projects/phpsat>
516
517
518
519Alec Thomas                         0.1.20                          devtodo(1)
Impressum