


devtodo(1)             Programming utility             devtodo(1)


NNAAMMEE
       todo - a reminder/task program aimed at developers

SSYYNNPPOOSSIISS
       ttooddoo [[_<_o_p_t_i_o_n_s_>]]
              With no options, displays the items in the current directory.

       ttddaa [[--pp _<_p_r_i_o_r_i_t_y_>] [-g _<_i_n_d_e_x_>] [_<_t_e_x_t_>]
              Add  a  new item, optionally grafting it as a child of the given
              item.

       ttddee _<_i_n_d_e_x_>
              Edit the given item.

       ttddrr _<_i_n_d_i_c_e_s_>
              Remove the given items.

       ttdddd _<_i_n_d_i_c_e_s_>
              Mark the specified items as being done.

       ttddll [[--gg _<_i_n_d_e_x_>]] _<_d_a_t_a_b_a_s_e_>
              Link the  specified  devtodo  database  into  the  current  one,
              optionally grafting it as a child of the specified index.

DDEESSCCRRIIPPTTIIOONN
       ttooddoo is a program aimed specifically at programmers (but usable by any-
       body 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 com-
       pleted 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 direc-
       tory 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 out-
       standing items...unless all of the bugs have been fixed ;).

OOPPTTIIOONNSS
       Options can have both a long and a short form.

       Short  options can be combined into one argument by using a hyphen fol-
       lowed by a string of short options. Parameters  of  short  options  can
       also be appended to this string.


       --vv,, ----vveerrbboossee
              Display verbosely

       --aa,, ----aadddd [[_<_t_e_x_t_>]
              Add a note (will prompt for a note if one is not supplied).



Alec Thomas                   0.1.20                            1





devtodo(1)             Programming utility             devtodo(1)


       --gg,, ----ggrraafftt _<_i_n_d_e_x_>
              In  conjunction  with _-_-_a_d_d or _-_-_l_i_n_k, graft the new item to the
              specified item.

       --ll,, ----lliinnkk _<_d_a_t_a_b_a_s_e_>
              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 nnoott remove the database itself,  only  the
              link.

       --RR,,----rreeppaarreenntt _<_i_n_d_e_x_>_[_,_<_i_n_d_e_x_>_]
              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.

       --pp,, ----pprriioorriittyy _<_p_r_i_o_r_i_t_y_>
              In conjunction with --add or --edit, set the priority (default |
              veryhigh | high | medium | low | verylow)

       --ee,, ----eeddiitt _<_i_n_d_e_x_>
              Edit the note that is indexed by the given number.

       ----rreemmoovvee _<_i_n_d_i_c_e_s_>
              Remove the note indexed by  the  given  numbers,  including  any
              children.

       --dd,, ----ddoonnee _<_i_n_d_i_c_e_s_>
              Mark the specified notes (and their children) as done.

       --DD,, ----nnoott--ddoonnee _<_i_n_d_i_c_e_s_>
              Mark the specified notes (and all children) as not done.

       ----gglloobbaall--ddaattaabbaassee _<_f_i_l_e_>
              Specify the database to use if either the _-_G or _-_-_g_l_o_b_a_l options
              are specified.

       --GG,, ----gglloobbaall
              Force todo to use the database specified with _-_-_g_l_o_b_a_l_-_d_a_t_a_b_a_s_e.
              If  this  is  placed in your _~_/_._t_o_d_o_r_c it will force todo to use
              that database to the exclusion of all others.

       ----ddaattaabbaassee _<_f_i_l_e_>
              Change the database from  whatever  the  default  is  (typically
              '.todo') to the file specified.

       --TT,, ----TTOODDOO
              Generate a typical TODO output text file from a Todo DB.

       --AA,, ----aallll
              Shortcut for the filter '+done,+children' to show all notes.





Alec Thomas                   0.1.20                            2





devtodo(1)             Programming utility             devtodo(1)


       --ff,, ----ffiilltteerr _<_f_i_l_t_e_r_>
              Display  only those notes that pass the filter. Please refer the
              section _F_I_L_T_E_R_S for more information.

       ----ccoolloouurr _<_c_o_l_o_u_r_s_>
              Override default colours of todo items. Please refer to the sec-
              tion _C_O_L_O_U_R for more information.

       ----ffoorrccee--ccoolloouurr
              Force  use  of colour even when not outputting to a TTY. This is
              useful when piping to _l_e_s_s_(_1_) -R.

       ----mmoonnoo Remove all ANSI escape sequences from output - useful for colour
              impaired terminals.

       ----hheellpp Display this help.

       ----vveerrssiioonn
              Display version of ToDo.

       ----ttiittllee [[_<_t_e_x_t_>]
              Set the title of this directory's todo notes.

       ----ddaattee--ffoorrmmaatt _<_f_o_r_m_a_t_>
              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 _~_/_._t_o_d_o_r_c.

       ----ffoorrmmaatt _<_i_d_e_n_t_i_f_i_e_r_>_=_<_f_o_r_m_a_t_>
              Specify  the  formatting  of output. Please refer to the section
              FORMATTING for more information.

       ----uussee--ffoorrmmaatt _<_b_u_i_l_t_i_n_>_=_<_i_d_e_n_t_i_f_i_e_r_>
              Use the format string identified by _<_i_d_e_n_t_i_f_i_e_r_>  (defined  with
              --format)  as  the format string to use when formatting with the
              builtin format _<_b_u_i_l_t_i_n_>.

       ----ssoorrtt _<_e_x_p_r_e_s_s_i_o_n_>
              Sort the database with the specified expression.  Refer  to  the
              section _S_O_R_T_I_N_G for more detailed information.

       ----ppaarraannooiidd
              Be paranoid about some settings, including permissions.

       ----ddaattaabbaassee--llooaaddeerrss _<_l_o_a_d_e_r _l_i_s_t_>
              Try  the  database formats in the given order. Valid formats are
              _x_m_l and _b_i_n_a_r_y.  eg.  todo  --database-loaders  binary,xml.  The
              default format is XML.

       ----bbaacckkuupp [[_<_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  file-
              names  used  to  store the backups are the default database name
              with their revision appended like so: .todo.1, .todo.2, etc.  To



Alec Thomas                   0.1.20                            3





devtodo(1)             Programming utility             devtodo(1)


              actually use one of these backups, you can either mv it to .todo
              or use --database .todo.<n> to explicitly specify its use.

       --ss,, ----ssuummmmaarryy
              Toggle "summary" mode, where long items  are  truncated  to  one
              line.

       --cc,, ----ccoommmmeenntt
              Edit or show comments respectively.

       ----ttiimmeeoouutt [[_<_t_i_m_e_>]
              If _<_t_i_m_e_> is specified, the timeout between database displays is
              set to this number of seconds. If no _<_t_i_m_e_>  is  specified,  the
              behaviour  is  to  display  the database _o_n_l_y if it has not been
              displayed for the number of seconds specified by --timeout  _w_i_t_h
              the  _<_t_i_m_e_>  given.  eg.  _t_o_d_o _-_-_t_i_m_e_o_u_t _1_0 _-_-_t_i_m_e_o_u_t would only
              display the database at most once every 10  seconds.  Putting  a
              _t_i_m_e_o_u_t  _1_0 in your ~/.todorc is a good option, then the --time-
              out in the _d_o_c_/_s_c_r_i_p_t_s_._* will mean that the  database  won't  be
              displayed every time you cd into a directory.

       ----ppuurrggee [[_<_d_a_y_s_-_o_l_d_>]
              Purge  all  completed items older than _<_d_a_y_s_-_o_l_d_>. If _<_d_a_y_s_-_o_l_d_>
              is omitted, all completed records are purged.

PPRRIIOORRIITTIIEESS
       Priorities can be specified symbolically using the words _d_e_f_a_u_l_t, _v_e_r_y_-
       _h_i_g_h, _h_i_g_h, _m_e_d_i_u_m, _l_o_w and _v_e_r_y_l_o_w.

       The  _d_e_f_a_u_l_t  priority  has  special  meaning  in  that it will use the
       default priority for any action. This means that when editing an exist-
       ing item, its priority is preserved; when creating a new item, the pri-
       ority will be set to _m_e_d_i_u_m; 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.

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

       The general format of a filter expression is:

       (([[--||==||++]]((aallll||cchhiillddrreenn||ddoonnee||<<iinnddeexx>>||<<pprriioorriittyy>>))))  ||  ((//<<sseeaarrcchh   eexxpprreess--
       ssiioonn>>))

       Generally,  if  a  filter expression is prefixed with a '-' it will _n_o_t
       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  _o_n_l_y  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: _t_o_d_o _-_-_f_i_l_t_e_r _a_l_l_,_/_s_o_m_e_-_s_e_a_r_c_h_-_s_t_r_i_n_g.




Alec Thomas                   0.1.20                            4





devtodo(1)             Programming utility             devtodo(1)


       The second form of filter expression is used for searching for text  in
       a  database.  _<_s_e_a_r_c_h  _e_x_p_r_e_s_s_i_o_n_>  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:

       aallll    Forces  all  items to be displayed. The various prefixes have no
              effect on this expression.

       cchhiillddrreenn
              Collapse or expand child items. If the  '-'  prefix  is  present
              children are collapsed, otherwise children are displayed.

       ddoonnee   Filter on whether an item is completed or not.

       <<iinnddeexx>>
              Note  indices  are specified as numbers. Ranges can be given ala
              '1.2.10-20'.

       <<pprriioorriittyy>>
              Priorities are specified as described in the _P_R_I_O_R_I_T_I_E_S 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  speci-
              fied 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.

FFOORRMMAATTTTIINNGG
       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



Alec Thomas                   0.1.20                            5





devtodo(1)             Programming utility             devtodo(1)


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

       There  are  four  seperate  format  options:  _d_i_s_p_l_a_y,  _g_e_n_e_r_a_t_e_d, _v_e_r_-
       _b_o_s_e_-_d_i_s_p_l_a_y and _v_e_r_b_o_s_e_-_g_e_n_e_r_a_t_e_d. 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  pass-
       ing a different identifier to _f_o_r_m_a_t. This can then be enabled by using
       _-_-_u_s_e_-_f_o_r_m_a_t. eg.

       format      full-report=%i%[info]%f%2n.%[priority]%+1T%+1i%[info]Added:
       %[normal]%c  %[info]Completed: %[normal]%d\n%+1i%[info]Duration: %[nor-
       mal]%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:

       %%<<nn>>>>  The _> flag sets the number of spaces _<_n_> to use for  all  future
              indenting.

       %%[[++||--]][[<<nn>>]]ii
              Indent  to  depth  of  current  item. _<_n_> specifies the depth to
              indent to. If _<_n_> is ommitted, the current level is used.  Rela-
              tive  values  can  be used. eg. '%+1T' would indent to one level
              higher than the current indentation level.

       %%[[++||--]][[<<nn>>]]TT
              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.

       %%tt     Unwrapped, unformatted text of the item.

       %%ss     Summary text (ie. one line only, equivalent to _-_-_s_u_m_m_a_r_y).

       %%pp     The priority level of the current item.

       %%cc     The  current items creation date, formatted according to --date-
              format.

       %%dd     The date when the item was marked as done,  formatted  according
              to --date-format.

       %%DD     The  duration of the item, formatted according to --date-format.

       %%[[<<nn>>]]nn
              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.



Alec Thomas                   0.1.20                            6





devtodo(1)             Programming utility             devtodo(1)


       %%ff     The  state  flag  of  the current item. The displayed values for
              this flag are '+' means children, '-'  means  done',  '*'  means
              done with children.

       %%FF     The human readable state flag of the current item. The displayed
              values for this flag are 'children', 'done' means done',  'done,
              children' and 'open'.

       %%[[<<ccoolloouurr>>]]
              Colours  can  be  specified with this flag. The valid values for
              _<_c_o_l_o_u_r_> are: _v_e_r_y_l_o_w, _l_o_w, _m_e_d_i_u_m, _h_i_g_h, _v_e_r_y_h_i_g_h, _t_i_t_l_e, _i_n_f_o,
              and _p_r_i_o_r_i_t_y. These are fairly self explanatory, except _p_r_i_o_r_i_t_y
              changes to the current items priority colour. eg. %[priority]

       Please note that when indenting, you will _t_y_p_i_c_a_l_l_y want to use a  pre-
       fix  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.

SSOORRTTIINNGG
       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, contin-
       uing  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  _c_r_e_a_t_e_d,  _c_o_m_p_l_e_t_e_d,  _t_e_x_t,  _p_r_i_o_r_i_t_y,
       _d_u_r_a_t_i_o_n, _n_o_n_e and _d_o_n_e. Each key, except _n_o_n_e 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.

IINNDDIICCEESS
       Indicies  are  used  as options to a variety of command line arguments.
       Multiple note  indices  are  seperated  with  commas  (spaces  are  _n_o_t
       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.



Alec Thomas                   0.1.20                            7





devtodo(1)             Programming utility             devtodo(1)


       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

CCOOLLOOUURR
       Various items can be colourised. Items that  can  are  _v_e_r_y_h_i_g_h,  _h_i_g_h,
       _m_e_d_i_u_m,  _l_o_w, _v_e_r_y_l_o_w, _t_i_t_l_e and _i_n_f_o. _i_n_f_o is used for displaying item
       numbers and general information.

       These items can be set to one  of  eight  colours.  Those  colours  are
       _b_l_a_c_k,  _r_e_d, _g_r_e_e_n, _y_e_l_l_o_w, _b_l_u_e, _m_a_g_e_n_t_a, _c_y_a_n, _w_h_i_t_e and _d_e_f_a_u_l_t. The
       colour _d_e_f_a_u_l_t is used  to  specify  the  default  foreground  terminal
       colour.

       Colours are specified like so:

       _<_i_t_e_m_>=_[_+_]_<_c_o_l_o_u_r_>

       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 _m_e_d_i_u_m text _b_o_l_d _w_h_i_t_e.

TTOODDOORRCC
       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 TTOODDOORRCC or, if that
       does not exist, //eettcc//ttooddoorrcc.
       2. ~~//..ttooddoorrcc

       Options are cumulative in that those loaded from $TODORC will be  over-
       ridden 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



Alec Thomas                   0.1.20                            8





devtodo(1)             Programming utility             devtodo(1)


       --.

       In addition, there are two commands available in the RC file  that  are
       not available on the command line. They are:

       The  first command, _o_n, is used to conditionally add specific commands.
       The format of this command  is:  _o_n  _<_e_v_e_n_t_>  _<_c_o_m_m_a_n_d_>  _[_<_a_r_g_u_m_e_n_t_s_>_].
       Valid  events  are  _a_d_d,  _r_e_m_o_v_e,  _v_i_e_w, _e_d_i_t, _g_e_n_e_r_a_t_e, _d_o_n_e, _n_o_t_d_o_n_e,
       _t_i_t_l_e, _r_e_p_a_r_e_n_t, _l_o_a_d, _s_a_v_e, _l_i_n_k, _c_r_e_a_t_e and _p_u_r_g_e. Multiple  commands
       can be passed to _o_n by enclosing them in braces (whitespace is required
       between tokens). Full example below.

       The second command is _e_x_e_c _<_s_h_e_l_l _c_o_m_m_a_n_d_>. This command  will  execute
       the  argument  it is given in a shell. The environment variable _$_T_O_D_O_D_B
       contains the filename of the  current  database.  eg.  _e_x_e_c  _c_h_m_o_d  _6_0_0
       _$_T_O_D_O_D_B

       There  is an example rc file in the doc subdirectory of the source dis-
       tribution.


EEXXAAMMPPLLEESS
       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 _-_c_h_i_l_d_r_e_n 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 _h_i_g_h 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



Alec Thomas                   0.1.20                            9





devtodo(1)             Programming utility             devtodo(1)


       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
            }

FFIILLEESS
        ..ttooddoo Items are stored as XML in this file.

       //eettcc//ttooddoorrcc
              Default  options  can be specified in this file. Please refer to
              the section TTOODDOORRCC for more information.

       ~~//..ttooddoorrcc
              User-specific options are specified in this file.  Please  refer
              to the section TTOODDOORRCC for more information.

AAUUTTHHOORRSS
       Alec Thomas _<_a_l_e_c_@_s_w_a_p_o_f_f_._o_r_g_>

SSEEEE AALLSSOO
       phpsat _<_h_t_t_p_:_/_/_s_o_u_r_c_e_f_o_r_g_e_._n_e_t_/_p_r_o_j_e_c_t_s_/_p_h_p_s_a_t_>

































Alec Thomas                   0.1.20                           10


