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
       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 ;).

OOPPTTIIOONNSS
       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.

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

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

       --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.

       --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
              section _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
              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.

       --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
              --timeout 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
       existing item, its priority is preserved; when creating a new item, the
       priority 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
       eexxpprreessssiioonn>>))

       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.

       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
              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.

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

       # 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
       passing 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:
       %[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:

       %%<<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.
              Relative 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.

       %%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
       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.

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,
       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 _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.
       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
       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, _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
       distribution.

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

       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                          devtodo(1)
