Provided by: task_1.9.4-0ubuntu4_i386 bug

NAME

       task-tutorial - A tutorial for the task(1) command line todo manager.

DESCRIPTION

       This  tutorial  contains a narrative and a series of commands that lead
       you through different scenarios  and  illustrate  the  capabilities  of
       taskwarrior.   We will begin with basic usage, and progress to the more
       powerful features.  It is  recommended  that  you  work  through  these
       examples alongside this tutorial.

       Make  your  terminal  window  as  wide  as you can, to properly see the
       formatted output of this page.

       Taskwarrior has many features and you will probably not use  them  all,
       but  there  are  likely  to be several capabilities that work well with
       your style of managing tasks.  Everyone has different  usage  patterns.
       This  is  therefore  a  complete  list  of capabilities, and you should
       choose accordingly.

BASIC USAGE

       Let's get started.  We're planning a party, and there is a lot of  work
       to do, so let's capture these tasks, by using the 'add' command.

              $ task add Select a free weekend in November
              Created task 1.
              $ task add Select and book a venue
              Created task 2.
              $ task add Come up with a guest list
              Created task 3.
              $ task add Mail invitations
              Created task 4.
              $ task add Select a caterer
              Created task 5.

       The  '$'  prompt  shows  that  these  are commands that you type (don't
       include the $ symbol yourself), and lines without the prompt are  those
       displayed by taskwarrior.  Let's take a look at our tasks so far.

              $ task list

              ID Project Pri Due Active Age     Description
              --        -------       ---       ---       ------       -------
              ---------------------------------
               1                          1  min  Select  a  free  weekend  in
              November
               2                        55 secs Select and book a venue
               3                        49 secs Come up with a guest list
               4                        40 secs Mail invitations
               5                        33 secs Select a caterer

              5 tasks

       Now  I've  already ordered a cake, so rather than 'add' this, I'm going
       to 'log' it.  This just means that I want to keep track  of  the  task,
       but I've already done it.  It saves me a step.

              $ task log Order a special cake
              Logged task.

       As  for those invitations, I'm going to need to design them first.  And
       I'm also going to need print them.  Here we are duplicating a task  and
       making  a  substitution.   Notice  how the commands can be abbreviated,
       provided they are still unique.

              $ task 4 duplicate /Mail/Design/
              Duplicated 4 'Mail invitations'.
              Duplicated 1 task.
              Created task 7.
              $ task 4 dup /Mail/Print/
              Duplicated 4 'Mail invitations'.
              Duplicated 1 task.
              Created task 8.
              $ task list

       That looks good - but now I think of it, I already have my guest  list,
       so I can mark that one as done.

              $ task 3 done
              Completed 3 'Come up with a guest list'.
              Marked 1 task as done.
              $ task list

              ID Project Pri Due Active Age    Description
              --        -------        ---       ---       ------       ------
              ---------------------------------
               1                         8  mins  Select  a  free  weekend  in
              November
               2                        7 mins Select and book a venue
               3                        6 mins Mail invitations
               4                        6 mins Select a caterer
               5                        4 mins Design invitations
               6                        4 mins Print invitations

              6 tasks

       And  that's  basic  usage, and you already know enough to be productive
       using taskwarrior.  If you stopped here, you would be perfectly able to
       manage your task list.

       But if you want to see what it can really do, keep reading...

PROJECTS

       Remember to pay the rent at the end of the month.

              $ task add Pay teh rent on teh 31st
              Created task 7.

       Oh,  that  was  sloppy, but it can be fixed with a global substitution,
       represented by the 'g' at the end.  You could  omit  the  'g',  and  it
       would only make the first substitution.

              $ task 7 /teh/the/g
              Modified 1 task.
              $ task list

              ID Project Pri Due Active Age     Description
              --        -------       ---       ---       ------       -------
              ---------------------------------
               1                        12  mins  Select  a  free  weekend  in
              November
               2                        12 mins Select and book a venue
               3                        11 mins Mail invitations
               4                        11 mins Select a caterer
               5                         9 mins Design invitations
               6                         9 mins Print invitations
               7                        37 secs Pay the rent on the 31st

              7 tasks

       We  can  now  use  projects  to  separate  home  chores  from the party
       preparation.  Let's assign that last task to the 'home' project.   Note
       that a task may only belong to one project.

              $ task 7 project:home
              The  scope  of project 'home' has changed.  Project 'home' is 0%
              complete (1 of 1 tasks remaining).
              Modified 1 task.

       And we will put those first six tasks in the 'party' project.  See  how
       we  specify  a  range  of tasks?  Taskwarrior will want to confirm bulk
       changes like this, but we'll accept all changes here.

              $ task 1-6 project:party

              Task 1 "Select a free weekend in November"
                - project will be set to 'party'.
              Proceed with change? (Yes/no/All/quit) A

              The scope of project 'party' has changed.  Project 'party' is 0%
              complete (1 of 1 tasks remaining).
              The scope of project 'party' has changed.  Project 'party' is 0%
              complete (2 of 2 tasks remaining).
              The scope of project 'party' has changed.  Project 'party' is 0%
              complete (3 of 3 tasks remaining).
              The scope of project 'party' has changed.  Project 'party' is 0%
              complete (4 of 4 tasks remaining).
              The scope of project 'party' has changed.  Project 'party' is 0%
              complete (5 of 5 tasks remaining).
              The scope of project 'party' has changed.  Project 'party' is 0%
              complete (6 of 6 tasks remaining).
              Modified 6 tasks.

       Now that we have multiple projects, as shown here, we can  use  project
       as  a  filter  for  the  list  report.   You  can see again that we can
       abbreviate 'list' and 'project', but when we abbreviate 'party', we are
       filtering all the projects that begin with 'par'.

              $ task projects

              Project Tasks Pri:None Pri:L Pri:M Pri:H
              ------- ----- -------- ----- ----- -----
              home        1        1     0     0     0
              party       6        6     0     0     0

              2 projects (7 tasks)
              $ task list project:home

              ID Project Pri Due Active Age    Description
              -- ------- --- --- ------ ------ ------------------------
               7 home                   5 mins Pay the rent on the 31st

              1 task
              $ task li pro:par

              ID Project Pri Due Active Age     Description
              --        -------       ---       ---       ------       -------
              ---------------------------------
               1 party                  18  mins  Select  a  free  weekend  in
              November
               2 party                  17 mins Select and book a venue
               3 party                  17 mins Mail invitations
               4 party                  17 mins Select a caterer
               5 party                  15 mins Design invitations
               6 party                  15 mins Print invitations

              6 tasks

PRIORITIES

       Priorities  are  another  way  to organize tasks.  You can use priority
       values of high, medium and low, and taskwarrior knows these as H, M  or
       L.

              $ task 1-3,5 priority:H

              Task 1 "Select a free weekend in November"
                - priority will be set to 'H'.
              Proceed with change? (Yes/no/All/quit) A

              Modified 4 tasks.

              $ task list

              ID Project Pri Due Active Age     Description
              --        -------       ---       ---       ------       -------
              ---------------------------------
               1 party   H              24  mins  Select  a  free  weekend  in
              November
               2 party   H              23 mins Select and book a venue
               3 party   H              23 mins Mail invitations
               5 party   H              21 mins Design invitations
               7 home                   12 mins Pay the rent on the 31st
               4 party                  23 mins Select a caterer
               6 party                  21 mins Print invitations

              7 tasks

       You can remove priorities by specifying a blank value.

              $ task 3 pri:
              Modified 1 task.

TAGS

       A  task  may only have one project, but it may have any number of tags,
       which are just single words associated with the task.  I can go to  the
       print  shop  at the mall, and do all the invitation tasks, so let's tag
       them all.

              $ task 3,5,6 +mall

              Task 3 "Mail invitations"
                - tags will be set to 'mall'.
              Proceed with change? (Yes/no/All/quit) A

              Modified 3 tasks.

       The long report shows tags, too,

              $ task long

              ID Project  Pri  Added       Started  Due  Recur  Countdown  Age
              Deps Tags Description
              --  -------  ---  ---------- ------- --- ----- --------- -------
              ---- ---- ---------------------------------
               1 party   H    10/16/2010                              27  mins
              Select a free weekend in November
               2  party    H    10/16/2010                             26 mins
              Select and book a venue
               5 party   H    10/16/2010                              23  mins
              mall Design invitations
               7  home         10/16/2010                              14 mins
              Pay the rent on the 31st
               3 party        10/16/2010                              25  mins
              mall Mail invitations
               4  party        10/16/2010                              25 mins
              Select a caterer
               6 party        10/16/2010                              23  mins
              mall Print invitations

              7 tasks

       and I can use tags as a filter to any report too.

              $ task list +mall

              ID Project Pri Due Active Age     Description
              -- ------- --- --- ------ ------- ------------------
               5 party   H              24 mins Design invitations
               3 party                  26 mins Mail invitations
               6 party                  24 mins Print invitations

              3 tasks

       I  made  a  mistake  - I can't mail out the invitations at the mall, so
       let's remove that tag.

              $ task 3 -mall
              Modified 1 task.

MODIFICATIONS

       Task 7 is not worded correctly, so I can modify that  by  specifying  a
       task  ID and a new description.  This is also considered a bulk change,
       and so requires confirmation.

              $ task 7 Pay rent at the end of the month

              Task 7 "Pay the rent on the 31st"
                - description will be changed from 'Pay the rent on the  31st'
              to 'Pay rent at the end of the month'.
              Proceed with change? (Yes/no/All/quit) Y

              Modified 1 task.

       We'll need music.  I can prepend, and I can append to a task.

              $ task add music
              $ task 8 prepend Select some
              $ task 8 append for after dinner
              $ task list dinner

              ID Project Pri Due Active Age     Description
              --        -------       ---       ---       ------       -------
              ----------------------------------
               8                        34 secs Select some  Music  for  after
              dinner

              1 task

       I can also go straight into an editor and modify anything.  The task is
       formatted and you can edit anything you like, and the changes  will  be
       detected and made to the task.

              $ task 5 edit
              [Your $EDITOR is invoked]

       Sometimes  the command line will confuse the shell.  In this case, what
       would happen  if  there  was  a  file  named  'bands'  in  the  current
       directory?

              $ task add Hire a band?

       The shell might expand that wild-card, so to avoid that, you can escape
       the wild-card, or quote the whole description.

              $ task add Hire a band\?
              $ task add "Hire a band?"

       You can also use the minus minus operator which  tells  taskwarrior  to
       stop  being  clever  and  interpret the rest of the arguments as a task
       description.  Otherwise, that +dj would be interpreted as a tag.

              $ task add -- Hire a band\? +dj
              Created task 9.

       We don't really need a band, so the easiest way to get rid of that task
       is  to undo the last change.  Taskwarrior has a complete undo stack, so
       you can undo all the way back to the beginning.

              $ task undo

              The last modification was made 10/16/2010

                           Prior Values  Current Values
                           ------------  ------------------------------------
              description                Hire a band? +dj
              entry                      10/16/2010
              status                     pending
              uuid                       599c7598-069d-4598-8d94-0c919c4213ec

              The undo command is not reversible.  Are you sure  you  want  to
              revert to the previous state? (y/n) y
              Task removed.

       The  undo  operation  gets rid of the task completely, but I could also
       have just deleted the task, then the deletion itself would be  tracked,
       and also undo-able.

              $ task 1 delete
              Permanently  delete  task 1 'Select a free weekend in November'?
              (y/n) y
              Deleting task 1 'Select a free weekend in November'.
              The scope of project 'party' has changed.  Project 'party' is 0%
              complete (5 of 5 tasks remaining).
              $ task undo

              The last modification was made 10/16/2010

                           Prior    Values                             Current
              Values
                           ------------------------------------
              ------------------------------------
              description  Select a free weekend in November     Select a free
              weekend in November
              entry        10/16/2010                            10/16/2010
              priority     H                                     H
              project      party                                 party
              status       pending                               deleted
              uuid                        3a6881bb-628b-4f90-93d7-4da563b83d54
              3a6881bb-628b-4f90-93d7-4da563b83d54
              end                                                10/16/2010

              The  undo  command  is not reversible.  Are you sure you want to
              revert to the previous state? (y/n) y
              Modified task reverted.

INFO

       During that undo operation,  taskwarrior  displayed  metadata  that  is
       associated  with the task.  You can display this with the info command,
       and its shortcut.

              $ task 1 info

              Name        Value
              ----------- ------------------------------------
              ID          1
              Description Select a free weekend in November
              Status      Pending
              Project     party
              Priority    H
              UUID        3a6881bb-628b-4f90-93d7-4da563b83d54
              Entered     10/16/2010 (44 mins)

              $ task 1

              Name        Value
              ----------- ------------------------------------
              ID          1
              Description Select a free weekend in November
              Status      Pending
              Project     party
              Priority    H
              UUID        3a6881bb-628b-4f90-93d7-4da563b83d54
              Entered     10/16/2010 (44 mins)

       There are  also  statistics  that  taskwarrior  gathers,  which  I  can
       display.

              $ task stats

              Category              Data
              --------------------  -------------
              Pending               8
              Waiting               0
              Recurring             0
              Completed             2
              Deleted               0
              Total                 10
              Annotations           0
              Unique tags           1
              Projects              2
              Data size             9.3 KiB
              Undo transactions     32
              Tasks tagged          20%
              Oldest task           10/16/2010
              Newest task           10/16/2010
              Task used for         29 mins
              Task added every      2 mins
              Task completed every  14 mins
              Average time pending  31 mins
              Average desc length   23 characters

ANNOTATIONS

       Annotations are little notes that can be added to a task.  There can be
       any number, and each has a time stamp.

              $ task 1 annotate the 13th looks good
              Annotated 1 with 'the 13th looks good'.
              $ task 1 annotate or the 14th Annotated 1 with 'or the 14th'
              $ task list

              ID Project Pri Due Active Age     Description
              --       -------       ---       ---       ------        -------
              ----------------------------------
               1  party    H               48  mins  Select  a free weekend in
              November
                                                10/16/2010 the 13th looks good
                                                10/16/2010 or the 14th
               2 party   H              47 mins Select and book a venue
               5 party   H              44 mins Design invitations
               8                        19 mins Select some  Music  for  after
              dinner
               7  home                    35  mins  Pay rent at the end of the
              month
               3 party                  47 mins Mail invitations
               4 party                  47 mins Select a caterer
               6 party                  44 mins Print invitations

              8 tasks

       You can choose to display annotations in different ways.

              $ task list rc.annotations:full

              ID Project Pri Due Active Age     Description
              --       -------       ---       ---       ------        -------
              ---------------------------------
               1  party    H               49  mins  Select  a free weekend in
              November
                                                10/16/2010 the 13th looks good
                                                10/16/2010 or the 14th

              1 task
              Configuration override annotations:full
              $ task list rc.annotations:sparse

              ID Project Pri Due Active Age     Description
              --       -------       ---       ---       ------        -------
              ----------------------------------
               1  party    H               49  mins  +Select a free weekend in
              November
                                                10/16/2010 or the 14th

              1 task
              Configuration override annotations:sparse
              $ task list rc.annotations:none

              ID Project Pri Due Active Age     Description
              --       -------       ---       ---       ------        -------
              ----------------------------------
               1  party    H               49  mins  +Select a free weekend in
              November

              1 task
              Configuration override annotations:none

       Annotations can be removed by providing a matching pattern.

              $ task 1 denotate 14th
              Found annotation 'or the 14th' and deleted it.

CONFIGURATION

       There is  a  'show'  command,  that  is  used  to  display  the  active
       configuration.  There are hundreds of settings that can be changed, and
       every one has a sensible default.

              $ task show

              Config variable                 Value
              ------------------------------- ----------------
              _forcecolor                     no
              active.indicator                *
              alias.export                    export.yaml
              alias.export.vcalendar          export.ical
              alias.ghistory                  ghistory.monthly
              alias.history                   history.monthly
              alias.rm                        delete
              annotations                     full
               ...
              weekstart                       Sunday

       If you want a complete list of all the  settings  and  their  meanings,
       read the man page.

              $ man taskrc

       The  'config'  command is used to modify the settings, and in this case
       the configuration variable 'answer' is given the value of forty-two.

              $ task config answer forty-two
              Are you sure you want to add 'answer' with a  value  of  'forty-
              two'? (y/n) y
              Config file .taskrc modified.

       The  'show' command indicates that the value was changed, and also that
       the variable is unrecognized.  The show  command  performs  a  detailed
       check  on  your  configuration,  and  alerts  you  to  several kinds of
       problem.  The config command can also remove a value.

              $ task show answer

              Config variable Value
              --------------- ---------
              answer          forty-two

              Your .taskrc file contains these unrecognized variables:
                answer

              $ task config answer
              Are you sure you want to remove 'answer'? (y/n) y
              Config file .taskrc modified.

       A very powerful feature is the ability to  override  the  configuration
       variables  temporarily.   Here I am requesting an ascending sort on the
       description field only.

              $ task rc.report.list.sort=description+ list

              ID Project Pri Due Active Age     Description
              --       -------       ---       ---       ------        -------
              ----------------------------------
               5 party   H              51 mins Design invitations
               3 party                  53 mins Mail invitations
               7  home                    42  mins  Pay rent at the end of the
              month
               6 party                  51 mins Print invitations
               4 party                  53 mins Select a caterer
               1 party   H              54  mins  Select  a  free  weekend  in
              November
                                                10/16/2010 the 13th looks good
               2 party   H              53 mins Select and book a venue
               8                         25  mins  Select some Music for after
              dinner

              8 tasks
              Configuration override report.list.sort=description+

       The value in the configuration file is prefixed with 'rc.' to  identify
       its namespace.

DEFAULTS

       There  is a default command, which can be set to anything, in this case
       it is set to the 'list'  report.   Then  running  taskwarrior  with  no
       command name runs the default command.

              $ task config default.command list
              Are  you  sure you want to add 'default.command' with a value of
              'list'? (y/n) y
              Config file .taskrc modified.
              $ task

              ID Project Pri Due Active Age     Description
              --       -------       ---       ---       ------        -------
              ----------------------------------
               1  party    H               55  mins  Select  a free weekend in
              November
                                                10/16/2010 the 13th looks good
               2 party   H              54 mins Select and book a venue
               5 party   H              52 mins Design invitations
               8                        26 mins Select some  Music  for  after
              dinner
               7  home                    43  mins  Pay rent at the end of the
              month
               3 party                  54 mins Mail invitations
               4 party                  54 mins Select a caterer
               6 party                  52 mins Print invitations

              8 tasks

       I can also specify a default priority and project, which means that any
       tasks added will use them, unless an alternative is provided.

              $ task config default.priority H
              Are  you sure you want to add 'default.priority' with a value of
              'H'? (y/n) y
              Config file .taskrc modified.
              $ task config default.project work
              Are you sure you want to add 'default.project' with a  value  of
              'work'? (y/n) y
              Config file .taskrc modified.
              $ task add New task
              Created task 9.
              $ task list New task

              ID Project Pri Due Active Age     Description
              -- ------- --- --- ------ ------- -----------
               9 work    H              12 secs New task

              1 task

       Let's just revert those changes, to clean up.

              $ task undo

              The last modification was made 10/16/2010

                           Prior Values  Current Values
                           ------------  ------------------------------------
              description                New task
              entry                      10/16/2010
              priority                   H
              project                    work
              status                     pending
              uuid                       0f44f9dd-79db-4098-b95b-4c3aa97d575a

              The  undo  command  is not reversible.  Are you sure you want to
              revert to the previous state? (y/n) y
              Task removed.
              $ task config default.priority
              Are you sure you want to remove 'default.priority'? (y/n) y
              Config file .taskrc modified.
              $ task config default.project
              Are you sure you want to remove 'default.project'? (y/n) y
              Config file .taskrc modified.

ALIASES

       You can create aliases to effectively rename commands.

              $ task config alias.zzz list
              Are you sure you want to add 'alias.zzz' with a value of 'list'?
              (y/n) y
              Config file .taskrc modified.
              $ task zzz

              ID Project Pri Due Active Age     Description
              --        -------       ---       ---       ------       -------
              ----------------------------------
               1 party   H                 1  hr  Select  a  free  weekend  in
              November
                                                10/16/2010 the 13th looks good
               2 party   H              59 mins Select and book a venue
               5 party   H              56 mins Design invitations
               8                         30  mins  Select some Music for after
              dinner
               7 home                   47 mins Pay rent at  the  end  of  the
              month
               3 party                  59 mins Mail invitations
               4 party                  58 mins Select a caterer
               6 party                  56 mins Print invitations

              8 tasks

       You can abbreviate those, too.

              $ task z

              ID Project Pri Due Active Age     Description
              --        -------       ---       ---       ------       -------
              ----------------------------------
               1 party   H                 1  hr  Select  a  free  weekend  in
              November
                                                10/16/2010 the 13th looks good
               2 party   H              59 mins Select and book a venue
               5 party   H              56 mins Design invitations
               8                         30  mins  Select some Music for after
              dinner
               7 home                   47 mins Pay rent at  the  end  of  the
              month
               3 party                  59 mins Mail invitations
               4 party                  58 mins Select a caterer
               6 party                  56 mins Print invitations

              8 tasks

COLOR

       [Note that you will see color in your terminal as you work through this
       tutorial, but you will not see the color in the man page.   This  is  a
       limitation  of man pages in general.  The text shown (without color) is
       included here.]

       All the examples so far have been shown with  color  turned  off.   How
       about some color?

              $ task config color on
              Are  you sure you want to change the value of 'color' from 'off'
              to 'on'? (y/n) y
              Config file .taskrc modified.
              $ task list

              ID Project Pri Due Active Age     Description
              --       -------       ---       ---       ------        -------
              ----------------------------------
               1  party    H                  1  hr  Select  a free weekend in
              November
                                                10/16/2010 the 13th looks good
               2 party   H                 1 hr Select and book a venue
               5 party   H              59 mins Design invitations
               8                        33 mins Select some  Music  for  after
              dinner
               7  home                    50  mins  Pay rent at the end of the
              month
               3 party                     1 hr Mail invitations
               4 party                     1 hr Select a caterer
               6 party                  59 mins Print invitations

              8 tasks

       What you see is the result of a set of color rules being applied to the
       tasks.   There is a hierarchy of color rules that colorize a task based
       on the metadata.

       Here is an example of an explicit override to the color rules  where  a
       specific task is given a red background.

              $ task 1 bg:on_red
              modified 1 task.
              $ task list

              ID Project Pri Due Active Age     Description
              --        -------       ---       ---       ------       -------
              ----------------------------------
               1 party   H                 1  hr  Select  a  free  weekend  in
              November
                                                10/16/2010 the 13th looks good
               2 party   H                 1 hr Select and book a venue
               5 party   H              59 mins Design invitations
               8                         33  mins  Select some Music for after
              dinner
               7 home                   50 mins Pay rent at  the  end  of  the
              month
               3 party                     1 hr Mail invitations
               4 party                     1 hr Select a caterer
               6 party                  59 mins Print invitations

              8 tasks
              $ task 1 bg:
              Modified 1 task.

       Taskwarrior supports 256 colors on certain terminal emulators, and this
       shows the range of colors available.  Note that your terminal may  show
       fewer colors.

              $ task color

              Basic colors
                black   red   blue   green   magenta   cyan   yellow   white
                black   red   blue   green   magenta   cyan   yellow   white

              Effects
                red    bold  red    underline  on  blue   on green   on bright
              green

              color0 - color15
                0 1 2 . . .

                        . . . 15

              Color cube rgb000 - rgb555 (also color16 - color231)
                0              1              2              3               4
              5
                0  1 2 3 4 5  0 1 2 3 4 5  0 1 2 3 4 5  0 1 2 3 4 5  0 1 2 3 4
              5  0 1 2 3 4 5
               0
               1
               2
               3
               4
               5

              Gray ramp gray0 - gray23 (also color232 - color255)
                0 1 2 . . .                             . . . 23

              Try running 'task color white on red'.

       This is how to show a color sample.

              $ task color white on red

              Use this command  to  see  how  colors  are  displayed  by  your
              terminal.

              16-color   usage   (supports   underline,   bold   text,  bright
              background):
                task color black on bright yellow
                task color underline cyan on bright blue

              256-color usage (supports underline):
                task color color214 on color202
                task color rgb150 on rgb020
                task color underline grey10 on grey3
                task color red on color173

              Your sample:
                task color white on red

       Or samples of all the active color settings.

              $ task color legend

              Here are the colors currently in use:

              Color                     Definition
              ------------------------- -------------------------
              color.active              black on bright green
              color.alternate
              color.blocked             black on white
              color.calendar.due        white on red
              color.calendar.due.today  bold white on red
              color.calendar.holiday    black on bright yellow
              color.calendar.overdue    black on bright red
              color.calendar.today      bold white on bright blue
              color.calendar.weekend    white on bright black
              color.calendar.weeknumber bold blue
              color.debug               yellow
              color.due                 red
              color.due.today           red
              color.footnote            yellow
              color.header              yellow
              color.history.add         black on red
              color.history.delete      black on yellow
              color.history.done        black on green
              color.overdue             bold red
              color.pri.H               bold white
              color.pri.L
              color.pri.M               white
              color.pri.none
              color.recurring           magenta
              color.summary.background  on gray3
              color.summary.bar         on green
              color.sync.added          green
              color.sync.changed        yellow
              color.sync.rejected       red
              color.tagged              green
              color.undo.after          green
              color.undo.before         red

       Themes are a  simple  way  to  use  coordinated  color  schemes  so  by
       including  a  color theme into the configuration file, you can see some
       striking effects.  For a blue theme, add  this  line  to  your  .taskrc
       file:

              include /usr/local/share/doc/task/rc/dark-blue-256.theme

       For a red theme:

              include /usr/local/share/doc/task/rc/dark-red-256.theme

       For a general dark theme:

              include /usr/local/share/doc/task/rc/dark-256.theme

       Here  are  two  color rules that specify a dark blue background for all
       tasks that are part of the 'party' project, and uses bold  to  identify
       any tasks with the keyword 'invitations' in the description.

              $         task         "rc.color.project.party=on        rgb001"
              rc.color.keyword.invit=bold list
               ...

       There is a man page with a writeup of all the color capabilities.

              $ man task-color

ACTIVE TASKS

       I'm selecting a venue, so let's indicate  that  task  2  is  active  by
       starting it.  See how active tasks are affected by the color rules.

              $ task 2 start
              Started 2 'Select and book a venue'.

       There  is  an  active  report that shows only active tasks, and you can
       mark any active task as inactive, by stopping it.

              $ task active

              ID Project Pri Due Active Age  Description
              -- ------- --- --- ------ ---- -----------------------
               2 party   H       *      1 hr Select and book a venue

              1 task
              $ task 2 stop
              Stopped 2 'Select and book a venue'.

       There is a journalling feature that records the start and stop times as
       annotations.

              $ task config journal.time on
              Are  you  sure  you  want  to add 'journal.time' with a value of
              'on'? (y/n) y
              Config file .taskrc modified.
              $ task config dateformat.annotation 'Y/m/d H:N'
              Are you sure you want  to  add  'dateformat.annotation'  with  a
              value of 'Y/m/d H:N'? (y/n) y
              Config file .taskrc modified.
              $ task 2 start
              Started 2 'Select and book a venue'.
              $ task list venue

              ID Project Pri Due Active Age  Description
              -- ------- --- --- ------ ---- -----------------------------
               2 party   H       *      1 hr Select and book a venue
                                             2010/10/16 11:20 Started task

              1 task
              $ task 2 stop
              Stopped 2 'Select and book a venue'.
              $ task list venue

              ID Project Pri Due Active Age  Description
              -- ------- --- --- ------ ---- -----------------------------
               2 party   H       *      1 hr Select and book a venue
                                             2010/10/16 11:20 Started task
                                             2010/10/16 11:21 Stopped task

              1 task

DUE DATES

       Due dates can be specified as dates, durations into the future or past,
       mnemonic, ordinal or day of week.

              $ task 1 due:7/31/2010
              Modified 1 task.
              $ task 1 due:2wks
              Modified 1 task.
              $ task 1 due:-2wks
              Modified 1 task.
              $ task 1 due:eom
              Modified 1 task.
              $ task 2 due:8th
              Modified 1 task.
              $ task 2 due:sunday
              Modified 1 task.
              $ task 5 due:eow
              Modified 1 task.

       Some of these dates are in the past, so now you see there  are  overdue
       tasks.   Due  dates  have different colors for due, imminent, today and
       overdue values.  You can also choose the format - for input and output.

              $ task rc.dateformat.report:Y-M-DTH:N:SZ list

              ID Project Pri Due                  Active Age  Description
              --    -------    ---    --------------------     ------     ----
              ------------------------------------
               2  party   H   2010-10-17T00:00:00Z        1 hr Select and book
              a venue
                                                              2010/10/16 11:20
              Started task
                                                              2010/10/16 11:21
              Stopped task
               5  party    H     2010-10-22T00:00:00Z          1   hr   Design
              invitations
               1  party    H    2010-10-31T00:00:00Z        1 hr Select a free
              weekend in November
                                                              2010/10/16 00:00
              the 13th looks good
               8                                           1  hr  Select  some
              Music for after dinner
               7 home                                    1 hr Pay rent at  the
              end of the month
               3 party                                   1 hr Mail invitations
               4 party                                   1 hr Select a caterer
               6    party                                      1    hr   Print
              invitations

              8 tasks
              Configuration override dateformat.report:Y-M-DTH:N:SZ

CALENDAR

       When tasks have due dates, you can see them on the calendar.

              $ task calendar

       Taskwarrior  provides  sample  holiday  files   for   countries   where
       taskwarrior  is  used most.  You can create your own, or use one of the
       samples to show holidays on the calendar.  Try adding this line to your
       ~/.taskrc file:

              include /usr/local/share/doc/task/rc/holidays-US.rc

       Then:

              $ task calendar

                     October       2010                    November       2010
              December 2010

                   Su Mo Tu We Th Fr Sa      Su Mo Tu We Th Fr Sa       Su  Mo
              Tu We Th Fr Sa
                40                  1   2    45      1   2   3   4   5  6   49
              1  2  3  4
                41  3  4  5  6  7  8  9   46  7  8  9 10 11 12 13   50   5   6
              7  8  9 10 11
                42  10  11 12 13 14 15 16   47 14 15 16 17 18 19 20   51 12 13
              14 15 16 17 18
                43 17 18 19 20 21 22 23   48 21 22 23 24 25 26 27   52  19  20
              21 22 23 24 25
                44  24  25 26 27 28 29 30   49 28 29 30               53 26 27
              28 29 30 31
                45 31

              Legend:  today,  due,  due-today,  overdue,  weekend,   holiday,
              weeknumber.

       There are holiday files for CA, DE, ES, FR, NL, SE, UK and US.

       You  can  see  the  whole  year,  see  due  tasks  as well, and see the
       holidays:

              $ task cal 2010

                     January       2010                    February       2010
              March 2010                April 2010

                   Su  Mo  Tu We Th Fr Sa      Su Mo Tu We Th Fr Sa      Su Mo
              Tu We Th Fr Sa      Su Mo Tu We Th Fr Sa
                 1                 1  2    6     1  2  3  4  5  6    10      1
              2  3  4  5  6   14              1  2  3
                 2   3   4  5  6  7  8  9    7  7  8  9 10 11 12 13   11  7  8
              9 10 11 12 13   15  4  5  6  7  8  9 10
                 3 10 11 12 13 14 15 16    8 14 15 16 17 18 19 20   12  14  15
              16 17 18 19 20   16 11 12 13 14 15 16 17
                 4  17  18 19 20 21 22 23    9 21 22 23 24 25 26 27   13 21 22
              23 24 25 26 27   17 18 19 20 21 22 23 24
                 5 24 25 26 27 28 29 30   10 28                     14  28  29
              30 31            18 25 26 27 28 29 30
                 6 31

                       May        2010                         June       2010
              July 2010                August 2010

                   Su Mo Tu We Th Fr Sa      Su Mo Tu We Th Fr Sa       Su  Mo
              Tu We Th Fr Sa      Su Mo Tu We Th Fr Sa
                18                     1    23         1   2   3   4   5    27
              1  2  3   32  1  2  3  4  5  6  7
                19  2  3  4  5  6  7  8   24  6  7  8  9 10 11 12   28   4   5
              6  7  8  9 10   33  8  9 10 11 12 13 14
                20   9  10 11 12 13 14 15   25 13 14 15 16 17 18 19   29 11 12
              13 14 15 16 17   34 15 16 17 18 19 20 21
                21 16 17 18 19 20 21 22   26 20 21 22 23 24 25 26   30  18  19
              20 21 22 23 24   35 22 23 24 25 26 27 28
                22  23  24 25 26 27 28 29   27 27 28 29 30            31 25 26
              27 28 29 30 31   36 29 30 31
                23 30 31

                    September       2010                   October        2010
              November 2010             December 2010

                   Su  Mo  Tu We Th Fr Sa      Su Mo Tu We Th Fr Sa      Su Mo
              Tu We Th Fr Sa      Su Mo Tu We Th Fr Sa
                36           1  2  3  4   40                 1  2    45      1
              2  3  4  5  6   49           1  2  3  4
                37   5   6  7  8  9 10 11   41  3  4  5  6  7  8  9   46  7  8
              9 10 11 12 13   50  5  6  7  8  9 10 11
                38 12 13 14 15 16 17 18   42 10 11 12 13 14 15 16   47  14  15
              16 17 18 19 20   51 12 13 14 15 16 17 18
                39  19  20 21 22 23 24 25   43 17 18 19 20 21 22 23   48 21 22
              23 24 25 26 27   52 19 20 21 22 23 24 25
                40 26 27 28 29 30         44 24 25 26 27 28 29 30   49  28  29
              30               53 26 27 28 29 30 31
                                          45 31

              Legend:   today,  due,  due-today,  overdue,  weekend,  holiday,
              weeknumber.

              $ task rc.calendar.details:full cal

                     October       2010                    November       2010
              December 2010             January 2011

                   Su  Mo  Tu We Th Fr Sa      Su Mo Tu We Th Fr Sa      Su Mo
              Tu We Th Fr Sa      Su Mo Tu We Th Fr Sa
                40                 1  2    45      1   2   3   4   5   6    49
              1  2  3  4    1                    1
                41   3   4  5  6  7  8  9   46  7  8  9 10 11 12 13   50  5  6
              7  8  9 10 11    2  2  3  4  5  6  7  8
                42 10 11 12 13 14 15 16   47 14 15 16 17 18 19 20   51  12  13
              14 15 16 17 18    3  9 10 11 12 13 14 15
                43  17  18 19 20 21 22 23   48 21 22 23 24 25 26 27   52 19 20
              21 22 23 24 25    4 16 17 18 19 20 21 22
                44 24 25 26 27 28 29 30   49 28 29 30               53  26  27
              28 29 30 31       5 23 24 25 26 27 28 29
                45                                                          31
              6 30 31

              Legend:  today,  due,  due-today,  overdue,  weekend,   holiday,
              weeknumber.

              ID Project Pri Due        Active Age  Description
              --       -------       ---      ----------      ------      ----
              ------------------------------------
               2 party   H   10/17/2010        1 hr Select and book a venue
                                                    2010/10/16  11:20  Started
              task
                                                    2010/10/16  11:21  Stopped
              task
               5 party   H   10/22/2010        1 hr Design invitations
               1 party   H   10/31/2010        1 hr Select a free  weekend  in
              November
                                                    2010/10/16  00:00 the 13th
              looks good

              3 tasks
              Configuration override calendar.details:full
              $ task rc.calendar.holidays:full cal

                     October       2010                    November       2010
              December 2010

                   Su  Mo  Tu We Th Fr Sa      Su Mo Tu We Th Fr Sa      Su Mo
              Tu We Th Fr Sa
                40                 1  2    45      1   2   3   4   5   6    49
              1  2  3  4
                41   3   4  5  6  7  8  9   46  7  8  9 10 11 12 13   50  5  6
              7  8  9 10 11
                42 10 11 12 13 14 15 16   47 14 15 16 17 18 19 20   51  12  13
              14 15 16 17 18
                43  17  18 19 20 21 22 23   48 21 22 23 24 25 26 27   52 19 20
              21 22 23 24 25
                44 24 25 26 27 28 29 30   49 28 29 30               53  26  27
              28 29 30 31
                45 31

              Legend:   today,  due,  due-today,  overdue,  weekend,  holiday,
              weeknumber.

              Date       Holiday
              ---------- -----------------------------------
              10/11/2010 Columbus Day
              11/11/2010 Veterans Day
              11/25/2010 Thanksgiving Day
              12/25/2010 Christmas Day
              12/31/2010 New Year's Eve
              1/1/2011   New Year's Day
              1/17/2011  Birthday of Martin Luther King, Jr.
              2/21/2011  Washington's Birthday

              Configuration override calendar.holidays:full

RECURRENCE

       Remember the task we added to pay the rent?  We're going to need to  do
       that  every  month.   Recurring  tasks allow us to set up a single task
       that keeps coming back, just as you'd expect.

              $ task 7 due:eom recur:monthly
              Task 7 is now a recurring task.
              Modified 1 task.
              $ task 7

              Name        Value
              ----------- ------------------------------------
              ID          7
              Description Pay rent at the end of the month
              Status      Recurring
              Project     home
              Recurrence  monthly
              Mask
              Due         10/31/2010
              UUID        f79123aa-3377-43fd-8f50-d14ab3c1577b
              Entered     10/16/2010 (1 hr)

       You can also limit the extent of the recurrence.  Let's make  sure  the
       task doesn't recur after the lease ends.

              $ task 7 until:eoy
              Modified 1 task.

       And  there  is  a  recurring  report  that shows you only the recurring
       tasks.

              $ task recurring

              ID Project Pri Due        Recur   Active Age  Description
              --    -------    ---    ----------    -------    ------     ----
              --------------------------------
               9  home         10/31/2010  monthly        1 hr Pay rent at the
              end of the month

              1 task

       To illustrate a point, let's set  up  a  recurring  annual  task  as  a
       reminder  to  pay  taxes,  and put the due date in the past.  This will
       cause task to fill in the gaps, and create a series of severely overdue
       tasks.

              $ task add Pay taxes due:4/15/2007 recur:yearly
              Created task 10.
              $ task long

              ID  Project  Pri Added      Started Due        Recur   Countdown
              Age    Deps Tags Description
              -- ------- --- ---------- ------- ----------  -------  ---------
              ------ ---- ---- ------------------------------------
              11             10/16/2010         4/15/2007   yearly   3.5 yrs 2
              secs           Pay taxes
              12             10/16/2010         4/15/2008   yearly   2.5 yrs 2
              secs           Pay taxes
              13             10/16/2010         4/15/2009   yearly   1.5 yrs 2
              secs           Pay taxes
              14             10/16/2010         4/15/2010   yearly    6 mths 2
              secs           Pay taxes
               2  party    H   10/16/2010         10/17/2010           -11 hrs
              2 hrs           Select and book a venue
                                                                                              2010/10/16
              11:20 Started task
                                                                                              2010/10/16
              11:21 Stopped task
               5 party   H   10/16/2010         10/22/2010            -5  days
              2 hrs      mall Design invitations
               1  party    H   10/16/2010         10/31/2010            -2 wks
              2 hrs           Select a free weekend in November
                                                                                              2010/10/16
              00:00 the 13th looks good
               9  home         10/16/2010         10/31/2010 monthly    -2 wks
              1 hr           Pay rent at the end of the month
              15             10/16/2010         4/15/2011   yearly   -5 mths 2
              secs           Pay taxes
               8                                                    10/16/2010
              1 hr           Select some Music for after dinner
               3                    party                           10/16/2010
              2 hrs           Mail invitations
               4                     party                          10/16/2010
              2 hrs           Select a caterer
               6                    party                           10/16/2010
              2 hrs      mall Print invitations

              13 tasks

       Deletions  to  recurring  tasks  can  be  escalated  to include all the
       recurrences of a task.

              $ task 11 delete
              Permanently delete task 11 'Pay taxes'? (y/n) y
              This is a recurring task.  Do you want  to  delete  all  pending
              recurrences of this same task? (y/n) y
              Deleting recurring task 10 'Pay taxes'.
              Deleting recurring task 11 'Pay taxes'.
              Deleting recurring task 12 'Pay taxes'.
              Deleting recurring task 13 'Pay taxes'.
              Deleting recurring task 14 'Pay taxes'.
              Deleting recurring task 15 'Pay taxes'.

SHELL

       You  can  use the shell command to create a more immersive environment.
       Any task command you run outside the shell can also be run  inside  the
       shell, without the need to prefix every command with "task".

              $ task shell
              task 1.9.4 shell

              Enter any task command (such as 'list'), or hit 'Enter'.
              There is no need to include the 'task' command itself.
              Enter 'quit' to end the session.

              task>
              task> projects

              Project Tasks Pri:None Pri:L Pri:M Pri:H
              ------- ----- -------- ----- ----- -----
                          7        7     0     0     0
              home        2        2     0     0     0
              party       6        3     0     0     3

              3 projects (15 tasks)
              task> tags

              Tag  Count
              mall     2

              1 tag (15 tasks)
              task> list

              ID Project Pri Due        Active Age   Description
              --       -------      ---      ----------      ------      -----
              ------------------------------------
               2 party   H   10/17/2010        2 hrs Select and book a venue
                                                     2010/10/16 11:20  Started
              task
                                                     2010/10/16  11:21 Stopped
              task
               5 party   H   10/22/2010        2 hrs Design invitations
               1 party   H   10/31/2010        2 hrs Select a free weekend  in
              November
                                                     2010/10/16 00:00 the 13th
              looks good
               9 home        10/31/2010         1 hr Pay rent at  the  end  of
              the month
               8                                 1  hr  Select  some Music for
              after dinner
               3 party                         2 hrs Mail invitations
               4 party                         2 hrs Select a caterer
               6 party                         2 hrs Print invitations

              8 tasks
              task> quit

SPECIAL TAGS

       You've seen tags, but there are also 'special tags' that  have  effects
       on  individual tasks.  The 'nocolor' special tag causes the color rules
       to be bypassed.

              $ task 6 +nocolor
              Modified 1 task.

       Special tags are highlighted by the 'tags' command.

              $ task tags

              Tag     Count
              ------- -----
              mall        2
              nocolor     1

              2 tags (9 tasks)

       There are others - the 'nonag' special tag prevents the  generation  of
       nag  messages  when  you work on low priority tasks when there are more
       important ones.

              $ task 6 -nocolor
              Modified 1 task.

       The 'nocal' special tag will prevent  a  task  from  appearing  on  the
       calendar.

WAITING

       When  you  have a task with a due date that is far out into the future,
       you may want to hide that task for a while.

              $ task add Look for new apartment due:eoy
              Created task 10.

       You can provide a wait date for a task, and it will remain hidden until
       that  date.   It will no longer be cluttering your task list, but it is
       still there, and visible using the 'waiting'  report.   When  the  wait
       date comes, the task will just reappear in the list.

              $ task 10 wait:12/1/2010
              Modified 1 task.
              $ task list

              ID Project Pri Due        Active Age   Description
              --       -------      ---      ----------      ------      -----
              ------------------------------------
               2 party   H   10/17/2010        2 hrs Select and book a venue
                                                     2010/10/16 11:20  Started
              task
                                                     2010/10/16  11:21 Stopped
              task
               5 party   H   10/22/2010        2 hrs Design invitations
               1 party   H   10/31/2010        2 hrs Select a free weekend  in
              November
                                                     2010/10/16 00:00 the 13th
              looks good
               9 home        10/31/2010        2 hrs Pay rent at  the  end  of
              the month
               8                                 1  hr  Select  some Music for
              after dinner
               3 party                         2 hrs Mail invitations
               4 party                         2 hrs Select a caterer
               6 party                         2 hrs Print invitations

              8 tasks
              $ task waiting

              ID Project Pri Wait      Age   Description
              -- ------- --- --------- ----- ----------------------
              10             12/1/2010 1 min Look for new apartment

              1 task

       To illustrate this, let's set up a task with a very short wait time  of
       five seconds.

              $ task add Do something in a few seconds
              Created task 11.
              $ task 11 wait:5s
              Modified 1 task.
              $ task list

              ID Project Pri Due        Active Age   Description
              --       -------      ---      ----------      ------      -----
              ------------------------------------
               2 party   H   10/17/2010        2 hrs Select and book a venue
                                                     2010/10/16 11:20  Started
              task
                                                     2010/10/16  11:21 Stopped
              task
               5 party   H   10/22/2010        2 hrs Design invitations
               1 party   H   10/31/2010        2 hrs Select a free weekend  in
              November
                                                     2010/10/16 00:00 the 13th
              looks good
               9 home        10/31/2010        2 hrs Pay rent at  the  end  of
              the month
               8                                 1  hr  Select  some Music for
              after dinner
               3 party                         2 hrs Mail invitations
               4 party                         2 hrs Select a caterer
               6 party                         2 hrs Print invitations

              8 tasks

       It's gone.  Now we wait five seconds, then:

              $ task list

              ID Project Pri Due        Active Age     Description
              --     -------      ---      ----------      ------      -------
              ------------------------------------
               2 party   H   10/17/2010          2 hrs Select and book a venue
                                                       2010/10/16        11:20
              Started task
                                                       2010/10/16        11:21
              Stopped task
               5 party   H   10/22/2010          2 hrs Design invitations
               1  party    H   10/31/2010          2 hrs Select a free weekend
              in November
                                                       2010/10/16  00:00   the
              13th looks good
               9  home        10/31/2010          2 hrs Pay rent at the end of
              the month
               8                                  1 hr Select some  Music  for
              after dinner
              11                                18  secs Do something in a few
              seconds
               3 party                           2 hrs Mail invitations
               4 party                           2 hrs Select a caterer
               6 party                           2 hrs Print invitations

              9 tasks

       And it's back.  Now we delete it.

              $ task 11 rc.confirmation:no delete
              Deleting task 11 'Do something in a few seconds'.

DEPENDENCIES

       Taskwarrior supports dependencies.  Let's take  a  look  at  the  party
       planning tasks, and assign dependencies.

              $ task list pro:party

              ID Project Pri Due        Active Age   Description
              --       -------      ---      ----------      ------      -----
              ------------------------------------
               2 party   H   10/17/2010        3 hrs Select and book a venue
                                                     2010/10/16 11:20  Started
              task
                                                     2010/10/16  11:21 Stopped
              task
               5 party   H   10/22/2010        3 hrs Design invitations
               1 party   H   10/31/2010        3 hrs Select a free weekend  in
              November
                                                     2010/10/16 00:00 the 13th
              looks good
               3 party                         3 hrs Mail invitations
               4 party                         3 hrs Select a caterer
               6 party                         3 hrs Print invitations

              6 tasks

       Let's see.  I can't mail invitations until they are printed.

              $ task 3 depends:6
              Modified 1 task.

       I can't print them until I design them.

              $ task 6 dep:5
              Modified 1 task.

       I need to select a weekend before a location.

              $ task 2 dep:1
              Modified 1 task.

       Design depends on location and weekend.

              $ task 5 dep:1,2
              Modified 1 task.

       And the caterer needs to know where.

              $ task 4 dep:1
              Modified 1 task.

       Let's take a look.  All my tasks are blocked except task 1.  That makes
       sense.

              $ task long pro:party

              ID Project Pri Added      Started Due        Recur Countdown Age
              Deps Tags Description
              -- ------- --- ----------  -------  ----------  -----  ---------
              ----- ---- ---- ------------------------------------
               2  party    H   10/16/2010         10/17/2010         -10 hrs 3
              hrs 1         Select and book a venue
                                                                                           2010/10/16
              11:20 Started task
                                                                                           2010/10/16
              11:21 Stopped task
               5 party   H   10/16/2010         10/22/2010         -5  days  3
              hrs 1,2  mall Design invitations
               1  party    H   10/16/2010         10/31/2010          -2 wks 3
              hrs           Select a free weekend in November
                                                                                           2010/10/16
              00:00 the 13th looks good
               3  party        10/16/2010                                    3
              hrs 6         Mail invitations
               4 party        10/16/2010                                     3
              hrs 1         Select a caterer
               6  party        10/16/2010                                    3
              hrs 5    mall Print invitations

              6 tasks

       Hmm, that double dependency isn't right.

              $ task 5 dep:-1
              Modified 1 task.

       Here are the blocked tasks, and the opposite, the unblocked tasks.

              $ task blocked

              ID Deps Project Pri Due        Active Age   Description
              --    ----    -------    ---     ----------     ------     -----
              -----------------------------
               2  1     party    H   10/17/2010        3 hrs Select and book a
              venue
                                                          2010/10/16     11:20
              Started task
                                                          2010/10/16     11:21
              Stopped task
               5 2    party   H   10/22/2010        3 hrs Design invitations
               3 6    party                         3 hrs Mail invitations
               4 1    party                         3 hrs Select a caterer
               6 5    party                         3 hrs Print invitations

              5 tasks
              $ task unblocked

              ID Deps Project Pri Due        Active Age   Description
              --    ----    -------    ---     ----------     ------     -----
              ------------------------------------
               1       party    H    10/31/2010         3  hrs  Select  a free
              weekend in November
                                                          2010/10/16 00:00 the
              13th looks good
               9       home        10/31/2010        3 hrs Pay rent at the end
              of the month
               8                                    3 hrs  Select  some  Music
              for after dinner

              3 tasks

       If we look at task 1 closely, we can see that it is blocking 2 and 4.

              $ task 1 info

              Name                  Value
              --------------------- ------------------------------------
              ID                    1
              Description           Select a free weekend in November
                                    2010/10/16 00:00 the 13th looks good
              Status                Pending
              Project               party
              Priority              H
              This task is blocking 2 Select and book a venue
                                    4 Select a caterer
              Due                   10/31/2010
              UUID                  3a6881bb-628b-4f90-93d7-4da563b83d54
              Entered               10/16/2010 (3 hrs)

       And  if we look at task 2, we see that it is blocked by 1, and blocking
       5.

              $ task 2 info

              Name                  Value
              --------------------- ------------------------------------
              ID                    2
              Description           Select and book a venue
                                    2010/10/16 11:20 Started task
                                    2010/10/16 11:21 Stopped task
              Status                Pending
              Project               party
              Priority              H
              This task blocked by  1 Select a free weekend in November
              This task is blocking 5 Design invitations
              Due                   10/17/2010
              UUID                  773c2b02-919e-4527-95f0-814c19dd198a
              Entered               10/16/2010 (3 hrs)

       This is called a dependency chain, which is a string of tasks that  are
       all  connected  not only by their project, but by dependencies.  Now we
       understand that task 1 should be done first, but you may still  violate
       the  laws  of  physics  if you wish. Let's complete task 2 and see what
       happens.

       Taskwarrior realizes  what  you  are  doing,  and  offers  to  fix  the
       dependency chain to reflect what you have done.

              $ task 2 done

              Task 2 is blocked by:
                1 Select a free weekend in November
              and is blocking:
                5 Design invitations
              Would you like the dependency chain fixed? (y/n) y
              Completed 2 'Select and book a venue'.
              Project 'party' is 12% complete (7 of 8 tasks remaining).
              Marked 1 task as done.
              $ task 1 info

              Name                  Value
              --------------------- ------------------------------------
              ID                    1
              Description           Select a free weekend in November
                                    2010/10/16 00:00 the 13th looks good
              Status                Pending
              Project               party
              Priority              H
              This task is blocking 4 Select a caterer
                                    5 Design invitations
              Due                   10/31/2010
              UUID                  3a6881bb-628b-4f90-93d7-4da563b83d54
              Entered               10/16/2010 (3 hrs)

REPORTS

       Taskwarrior  has  a  good many reports.  There is a report with minimal
       information:

              $ task minimal

              ID Project Description
              -- ------- ------------------------------------
               7         Select some Music for after dinner
               8 home    Pay rent at the end of the month
               4 party   Design invitations
               2 party   Mail invitations
               5 party   Print invitations
               3 party   Select a caterer
               1 party   Select a free weekend in November
                         2010/10/16 00:00 the 13th looks good

       There is the basic report:

              $ task ls

              ID Project Pri Description
              -- ------- --- ------------------------------------
               1 party   H   Select a free weekend in November
                             2010/10/16 00:00 the 13th looks good
               4 party   H   Design invitations
               7             Select some Music for after dinner
               8 home        Pay rent at the end of the month
               2 party       Mail invitations
               3 party       Select a caterer
               5 party       Print invitations

       There is the most common report:

              $ task list

              ID Project Pri Due        Active Age   Description
              --      -------      ---      ----------      ------       -----
              ------------------------------------
               4 party   H   10/22/2010        5 hrs Design invitations
               1  party   H   10/31/2010        6 hrs Select a free weekend in
              November
                                                     2010/10/16 00:00 the 13th
              looks good
               8  home         10/31/2010         5 hrs Pay rent at the end of
              the month
               7                               5 hrs  Select  some  Music  for
              after dinner
               2 party                         5 hrs Mail invitations
               3 party                         5 hrs Select a caterer
               5 party                         5 hrs Print invitations

       There is a report with most of the data shown:

              $ task long

              ID  Project  Pri Added      Started Due        Recur   Countdown
              Age   Deps Tags Description
              -- ------- --- ---------- ------- ----------  -------  ---------
              ----- ---- ---- ------------------------------------
               4 party   H   10/16/2010         10/22/2010           -5 days 5
              hrs 1    mall Design invitations
               1 party   H   10/16/2010         10/31/2010            -2 wks 6
              hrs           Select a free weekend in November
                                                                                             2010/10/16
              00:00 the 13th looks good
               8 home        10/16/2010         10/31/2010 monthly    -2 wks 5
              hrs           Pay rent at the end of the month
               7             10/16/2010                                      5
              hrs           Select some Music for after dinner
               2 party       10/16/2010                                      5
              hrs 5         Mail invitations
               3 party       10/16/2010                                      5
              hrs 1         Select a caterer
               5 party       10/16/2010                                      5
              hrs 4    mall Print invitations

       There is a report containing all tasks, old and new:

              $ task all

              ID Project Pri Due        Completed  Active Age   Description
              --    -------    ---    ----------   ----------   ------   -----
              ------------------------------------
               9             12/31/2010                   3 hrs Look  for  new
              apartment
               7                                           5  hrs  Select some
              Music for after dinner
               -                        10/16/2010        6 hrs Come up with a
              guest list
               -                          10/16/2010          5  hrs  Order  a
              special cake
               6 home        10/31/2010                   5 hrs  Pay  rent  at
              the end of the month
               8  home         10/31/2010                    5 hrs Pay rent at
              the end of the month
               - party   H   10/17/2010 10/16/2010         6  hrs  Select  and
              book a venue
                                                                2010/10/16
              11:20 Started task
                                                                2010/10/16
              11:21 Stopped task
               4   party     H    10/22/2010                    5  hrs  Design
              invitations
               1 party   H   10/31/2010                   6 hrs Select a  free
              weekend in November
                                                                2010/10/16
              00:00 the 13th looks good
               2   party                                      6    hrs    Mail
              invitations
               5    party                                      5   hrs   Print
              invitations
               3  party                                     6  hrs  Select   a
              caterer

       There is a report showing completed work:

              $ task completed

              Complete   Project Pri Age   Description
              ---------- ------- --- ----- -----------------------------
              10/16/2010 party   H   6 hrs Select and book a venue
                                           2010/10/16 11:20 Started task
                                           2010/10/16 11:21 Stopped task
              10/16/2010             6 hrs Come up with a guest list
              10/16/2010             5 hrs Order a special cake

       There is a report showing recurring tasks only:

              $ task recurring

              ID Project Pri Due        Recur   Active Age   Description
              --    -------    ---    ----------    -------    ------    -----
              --------------------------------
               8 home        10/31/2010 monthly        5 hrs Pay rent  at  the
              end of the month

       There is a report to show all the waiting tasks:

              $ task waiting

              ID Project Pri Wait      Age   Description
              -- ------- --- --------- ----- ----------------------
               9             12/1/2010 3 hrs Look for new apartment

       There  is  a  report  showing  all  the  tasks  that  are  blocked  via
       dependencies by other tasks:

              $ task blocked

              ID Deps Project Pri Due        Active Age   Description
              -- ---- ------- --- ---------- ------ ----- ------------------
               4 1    party   H   10/22/2010        5 hrs Design invitations
               2 5    party                         6 hrs Mail invitations
               3 1    party                         6 hrs Select a caterer
               5 4    party                         5 hrs Print invitations

       There is a report showing tasks that are not blocked by dependencies:

              $ task unblocked

              ID Deps Project Pri Due        Active Age   Description
              --    ----    -------    ---     ----------     ------     -----
              ------------------------------------
               1       party    H    10/31/2010         6  hrs  Select  a free
              weekend in November
                                                          2010/10/16 00:00 the
              13th looks good
               8       home        10/31/2010        5 hrs Pay rent at the end
              of the month
               7                                    5 hrs  Select  some  Music
              for after dinner

       There is a report showing the oldest tasks:

              $ task oldest limit:3

              ID Project Pri Due        Active Age   Description
              --       -------      ---      ----------      ------      -----
              ------------------------------------
               1 party   H   10/31/2010        6 hrs Select a free weekend  in
              November
                                                     2010/10/16 00:00 the 13th
              looks good
               2 party                         6 hrs Mail invitations
               3 party                         6 hrs Select a caterer

       There is a report showing the newest tasks:

              $ task newest limit:3

              ID Project Pri Due        Active Age   Description
              --      -------      ---      ----------      ------       -----
              ----------------------------------
               8  home         10/31/2010         5 hrs Pay rent at the end of
              the month
               7                               5 hrs  Select  some  Music  for
              after dinner
               5 party                         6 hrs Print invitations

       There is a report showing the completed and started tasks, by week:

              $ task timesheet

              10/10/2010 - 10/16/2010
                Completed (3 tasks)
                  Project Due        Description
                                     Come up with a guest list
                                     Order a special cake
                  party   10/17/2010 Select and book a venue
                                     2010/10/16 11:20 Started task
                                     2010/10/16 11:21 Stopped task

                Started (0 tasks)

       And  "what  should  I work on next?"  This one can be useful because it
       pulls a few of the highest priority tasks from all the projects.

              $ task next

              ID Project Pri Due        Active Age   Description
              --      -------      ---      ----------      ------       -----
              ------------------------------------
               1  party   H   10/31/2010        6 hrs Select a free weekend in
              November
                                                     2010/10/16 00:00 the 13th
              looks good
               8  home         10/31/2010         5 hrs Pay rent at the end of
              the month
               7                               5 hrs  Select  some  Music  for
              after dinner

CUSTOM REPORTS

       You  can  even  define  your own custom report.  Let's quickly create a
       custom report - we'll call it foo - and I can choose from a  long  list
       of  fields to include in the report, but I want to see the ID, the date
       when I entered the task, and the description.  I can specify the labels
       for those columns, the sort order of the report, and I can filter.

              $ cat >> ~/.taskrc
              report.foo.description=My own report
              report.foo.columns=id,entry,description
              report.foo.labels=ID,Entered,Description
              report.foo.sort=entry+,description+
              report.foo.filter=status:pending
              ^D

       Custom reports also show up on the help output.

              $ task help | grep foo
                     task foo [tags] [attrs] desc...            My own report

       I can inspect the configuration.

              $ task show report.foo

              Config variable        Value
              ---------------------- ----------------------
              report.foo.columns     id,entry,description
              report.foo.description My own report
              report.foo.filter      status:pending
              report.foo.labels      ID,Entered,Description
              report.foo.sort        entry+,description+

       And they can be run just like the other reports.

              $ task foo

              ID Entered    Description
              -- ---------- ------------------------------------
               4 10/16/2010 Design invitations
               2 10/16/2010 Mail invitations
               8 10/16/2010 Pay rent at the end of the month
               5 10/16/2010 Print invitations
               3 10/16/2010 Select a caterer
               1 10/16/2010 Select a free weekend in November
                            2010/10/16 00:00 the 13th looks good
               7 10/16/2010 Select some Music for after dinner

              7 tasks

CHARTS

       The  history  report gives monthly totals of tasks added, completed and
       deleted.  There is also an annual version.

              $ task history

              Year Month   Added Completed Deleted Net
              ---- ------- ----- --------- ------- ---
              2010 October    19         3       7   9

                   Average    19         3       7   9

              $ task history.annual

              Year    Added Completed Deleted Net
              ------- ----- --------- ------- ---
              2010       19         3       7   9

              Average    19         3       7   9

       There is a graphical monthly and annual version.  [These charts do  not
       show up in a man page]

              $ task ghistory
               ...
              $ task ghistory.annual
               ...

       There  is  a  project  summary  report  that  shows progress in all the
       projects.

              $ task summary

              Project      Remaining      Avg      age       Complete       0%
              100%
              -------           ---------           -------           --------
              ------------------------------
              (none)          2 59 mins      50% ===============
              home            1   3 hrs       0%
              party           5   6 hrs      16% =====

              3 projects

ADVANCED FILTERS

       Filters are a very powerful tool.  First here is  an  unfiltered  list,
       which shows all tasks.

              $ task list

              ID Project Pri Due        Active Age   Description
              --       -------      ---      ----------      ------      -----
              ------------------------------------
               4 party   H   10/22/2010        6 hrs Design invitations
               1 party   H   10/31/2010        6 hrs Select a free weekend  in
              November
                                                     2010/10/16 00:00 the 13th
              looks good
               8 home        10/31/2010        6 hrs Pay rent at  the  end  of
              the month
               7                                6  hrs  Select  some Music for
              after dinner
               2 party                         6 hrs Mail invitations
               3 party                         6 hrs Select a caterer
               5 party                         6 hrs Print invitations

              7 tasks

       Now again, but with the text 'invit', which acts as  a  filter  on  the
       description field.

              $ task list invit

              ID Project Pri Due        Active Age   Description
              -- ------- --- ---------- ------ ----- ------------------
               4 party   H   10/22/2010        6 hrs Design invitations
               2 party                         6 hrs Mail invitations
               5 party                         6 hrs Print invitations

              3 tasks

       This is the equivalent form using attribute modifiers.  In this example
       we are filtering on descriptions that contain the word fragment.   Here
       we are using the 'contains' modifier, but there are many others.

              $ task list description.contains:invit

              ID Project Pri Due        Active Age   Description
              -- ------- --- ---------- ------ ----- ------------------
               4 party   H   10/22/2010        6 hrs Design invitations
               2 party                         6 hrs Mail invitations
               5 party                         6 hrs Print invitations

              3 tasks

       All  tasks  containing  the  whole word 'the'.  See how annotations are
       also searched?

              $ task list desc.word:the

              ID Project Pri Due        Active Age   Description
              --      -------      ---      ----------      ------       -----
              ------------------------------------
               1  party   H   10/31/2010        6 hrs Select a free weekend in
              November
                                                     2010/10/16 00:00 the 13th
              looks good
               8  home         10/31/2010         6 hrs Pay rent at the end of
              the month

              2 tasks

       Here is a list of  all  tasks  that  do  not  contain  the  whole  word
       'invitations'.

              $ task list desc.noword:invitations

              ID Project Pri Due        Active Age   Description
              --       -------      ---      ----------      ------      -----
              ------------------------------------
               1 party   H   10/31/2010        6 hrs Select a free weekend  in
              November
                                                     2010/10/16 00:00 the 13th
              looks good
               8 home        10/31/2010        6 hrs Pay rent at  the  end  of
              the month
               7                                6  hrs  Select  some Music for
              after dinner
               3 party                         6 hrs Select a caterer

              4 tasks

       Here list all tasks in the 'party' project.  And the  full  equivalent.
       Here list tasks that are not in the 'party' project.  I could have also
       used 'isnt' here - there are several synonyms for  modifiers,  so  that
       the filter can be written so that it reads naturally.

              $ task list pro:party
              $ task list pro.is:party
              $ task list pro.not:party

       Here  the  'over'  modifier is filtering on priorities that sort higher
       than 'Low', and also filtering on the 'party' project.  There  are  two
       terms in this filter.

              $ task list pro:party pri.over:L

              ID Project Pri Due        Active Age   Description
              --       -------      ---      ----------      ------      -----
              ------------------------------------
               4 party   H   10/22/2010        6 hrs Design invitations
               1 party   H   10/31/2010        6 hrs Select a free weekend  in
              November
                                                     2010/10/16 00:00 the 13th
              looks good

              2 tasks

       Same again, but only show me the first two tasks.  Now all  tasks,  but
       just  show  the first page of tasks.  I don't have a page full of tasks
       here, but you get the idea.

              $ task list pro:party limit:2

              ID Project Pri Due        Active Age   Description
              --      -------      ---      ----------      ------       -----
              ------------------------------------
               4 party   H   10/22/2010        6 hrs Design invitations
               1  party   H   10/31/2010        6 hrs Select a free weekend in
              November
                                                     2010/10/16 00:00 the 13th
              looks good

              2 tasks, 2 shown
              $ task list limit:page

              ID Project Pri Due        Active Age   Description
              --       -------      ---      ----------      ------      -----
              ------------------------------------
               4 party   H   10/22/2010        6 hrs Design invitations
               1 party   H   10/31/2010        6 hrs Select a free weekend  in
              November
                                                     2010/10/16 00:00 the 13th
              looks good

              2 tasks

       Now you can see how some of the  built-in  reports  work.   The  'list'
       report  is  just all tasks, filtered so that only the pending tasks are
       shown.

              $ task all status:pending
               ...

       The 'waiting' report is similarly defined.

              $ task all status:waiting
               ...

IMPORT/EXPORT

       You can export your tasks.  Here you see all tasks  being  exported  in
       CSV format.

              $ task export.csv
              ´uuid','status','tags','entry','start','due','recur','end','project','priority','fg','bg','description'
              ´3a6881bb-628b-4f90-93d7-4da563b83d54','pending','',1287237300,,1288497600,,,'party','H',,,'Select
              a free weekend in November'
              ´4a1de9aa-9b00-41ec-8d00-e0d0131e0e0d','pending','',1287237365,,,,,'party',,,,'Mail
              invitations'
              ´2a65e922-ff18-4db1-b867-dbe745b9626a','pending','',1287237372,,,,,'party',,,,'Select
              a caterer'
               ...

       Let's just export one task in CSV format...

              $ task export.csv venue
              ´uuid','status','tags','entry','start','due','recur','end','project','priority','fg','bg','description'
              ´773c2b02-919e-4527-95f0-814c19dd198a','completed','',1287237350,,1287288000,,1287250285,'party','H',,,'Select
              and book a venue'

       Or in VCalendar format...

              $ task export.vcalendar venue
              BEGIN:VCALENDAR
              VERSION:2.0
              PRODID:-//GBF//task 1.9.4.beta1//EN
              BEGIN:VTODO
              UID:773c2b02-919e-4527-95f0-814c19dd198a
              DTSTAMP:20101016T135550Z
              DUE:20101017T040000Z
              COMPLETED:20101016T173125Z
              SUMMARY:Select and book a venue
              CLASS:PRIVATE
              PRIORITY:1
              STATUS:COMPLETED
              COMMENT:Started task
              COMMENT:Stopped task
              END:VTODO
              END:VCALENDAR

       Or YAML.

              $ task export.yaml venue
              %YAML 1.1
              ---
                task:
                  depends: 3a6881bb-628b-4f90-93d7-4da563b83d54
                  description: Select and book a venue
                  due: 1287288000
                  end: 1287250285
                  entry: 1287237350
                  priority: H
                  project: party
                  status: completed
                  uuid: 773c2b02-919e-4527-95f0-814c19dd198a
                  annotation:
                    entry: 1287242411
                    description: Started task
                  annotation:
                    entry: 1287242506
                    description: Stopped task
               ...

       I  can  also  import.   Here  I  am  importing  simple  lines  of text.
       Taskwarrior recognizes the format by looking inside the file and making
       a guess, then confirms.

              $ cat file.text
              Remember to read the task man page
              $ task import file.text
              This  looks  like  a  text file with one task per line.  Okay to
              proceed? (y/n) y
              Imported 1 tasks successfully, with 0 errors.

       Here  is  a  YAML  example.   Taskwarrior  can  read  several  formats,
       including  old  versions of its data files.  Using YAML, you can round-
       trip the data without loss, which  means  you  can  export  and  import
       without any missing information.  This also means that 'export.yaml' is
       good for making a backup copy of your tasks.

              $ cat file.yaml
              %YAML 1.1
              ---
                task:
                  description: Visit http://taskwarrior.org
                  due: 1281844800
                  entry: 1281289630
                  priority: H
                  project: work
                  status: pending
                  uuid: 23afada0-a446-8d5a-c213-30d99d52c4b0
               ...
              $ task import file.yaml
              This looks like a YAML file.  Okay to proceed? (y/n) y
              Imported 1 tasks successfully.

       Here are the imported tasks.

              $ task new limit:2

              ID Project Pri Due        Active Age   Description
              --      -------      ---      ----------      ------       -----
              ------------------------------------
              11     work        H      8/15/2010            9    wks    Visit
              http://taskwarrior.org
              10                               1 min Remember to read the task
              man page

              9 tasks, 2 shown

HELP

       You'll  find  a quick reference page built in, with the 'help' command,
       or perhaps you'll want  to  take  a  look  at  the  several  man  pages
       installed.

              $ task help
               ...

CREDITS & COPYRIGHTS

       task was written by P. Beckingham <paul@beckingham.net>.
       Copyright (C) 2006 - 2011 P. Beckingham

       This  man  page  was  originally written by Federico Hernandez, and has
       been modified and supplemented by Paul Beckingham.

       task  is  distributed  under  the  GNU  General  Public  License.   See
       http://www.gnu.org/licenses/gpl-2.0.txt for more information.

SEE ALSO

       task(1), taskrc(5), task-faq(5), task-color(5), task-sync(5)

       For more information regarding task, the following may be referenced:

       The official site at
              <http://taskwarrior.org>

       The official code repository at
              <git://tasktools.org/task.git/>

       You can contact the project by writing an email to
              <support@taskwarrior.org>

REPORTING BUGS

       Bugs in task may be reported to the issue-tracker at
              <http://taskwarrior.org>