Man Linux: Main Page and Category List

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>