task-tutorial(5)

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 modify /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 modify 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 modify project:party
    Task 1 modify "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 project:home list
    ID Project Pri Due Active Age Description
    -- ------- --- --- ------ ------ ------------------------
     7 home 5 mins Pay the rent on the 31st
    1 task
    $ task pro:par li
    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 modify priority:H
    Task 1 modify "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 modify 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 modfy +mall
    Task 3 modify "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 +mall list
    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 modify -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 modify 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 dinner list
    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.
    $ 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)
    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 rc.annotations:full list
    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 rc.annotations:sparse list
    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 rc.annotations:none list
    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 New task list
    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 modify 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 modify 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 venue list
    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 venue list
    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 modify due:7/31/2010
    Modified 1 task.
    $ task 1 modify due:2wks
    Modified 1 task.
    $ task 1 modify due:-2wks
    Modified 1 task.
    $ task 1 modify due:eom
    Modified 1 task.
    $ task 2 modify due:8th
    Modified 1 task.
    $ task 2 modify due:sunday
    Modified 1 task.
    $ task 5 modify 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.en-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 be-BY, cs-CZ, da-DK, de-AT, de-DE, en-CA, en-GB, en-NZ, en-US, es-ES, fr-FR, it-IT, nb-NO, nl-NL and sv-SE locales. 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 modify due:eom recur:monthly
    Task 7 is now a recurring task.
    Modified 1 task.
    $ task 7 info
    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 modify 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 modify +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 modify -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 modify 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 modify 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 pro:party list
    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 modify depends:6
    Modified 1 task.
I can't print them until I design them.
    $ task 6 modify dep:5
    Modified 1 task.
I need to select a weekend before a location.
    $ task 2 modify dep:1
    Modified 1 task.
Design depends on location and weekend.
    $ task 5 modify dep:1,2
    Modified 1 task.
And the caterer needs to know where.
    $ task 4 modify dep:1
    Modified 1 task.
Let's take a look. All my tasks are blocked except task 1. That makes sense.
    $ task pro:party long
    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 modify 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 invit list
    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 description.contains:invit list
    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 desc.word:the list
    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 desc.noword:invitations list
    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 pro:party list
    $ task pro.is:party list
    $ task pro.not:party list
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 pro:party pri.over:L 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
    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 pro:party limit:2 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
    2 tasks, 2 shown
    $ task limit:page 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
    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 status:pending all
     ...
The 'waiting' report is similarly defined.
    $ task status:waiting all
     ...

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
Copyright (C) 2006 - 2011 P. Beckingham, F. Hernandez. This man page was originally written by Federico Hernandez, and has been modified and supplemented by Paul Beckingham. Taskwarrior is distributed under the MIT license. See http://www.opensource.org/licenses/mit-license.php 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>