taskwarrior/TUTORIAL

Task program tutorial, for version 0.9.0
----------------------------------------

This guide shows how to quickly set up the task program, and become proficient
with it.


Quick Setup
-----------

Build the task program according to the directions in the INSTALL file.  This
transcript illustrates a typical installation:

  % ls
  task-0.9.0.tar.gz
  % gunzip task-0.9.0.tar.gz
  % tar xf task-0.9.0.tar
  % cd task-0.9.0
  % ./configure
  ...
  % make
  ...
  % make install

You need to make sure that the installed task program is in your PATH
environment variable.  The next step is to create a configuration file for the
task program.  This file resides in your home directory, is called .taskrc, and
contains various configuration settings.  Use the provided SAMPLE_taskrc file
as a starting point for your own:

  % cp SAMPLE_taskrc ~/.taskrc
  % mkdir ~/.task

Your .taskrc files contains an entry that points to the .task directory
belonging to user bob.  Change this entry to point to your own home directory,
and the .task directory you just created.  Your task program is now ready to
use.  Verify that task is properly installed with:

  % task version
  [show sample output]


Simple Usage
------------

Let us begin by adding some tasks:

  % task add Book plane ticket
  % task add Rent a tux
  % task add Reserve a rental car
  % task add Reserve a hotel room

That's it.  You'll notice immediately that task has a very minimalist
interface.  Let us take a look at those tasks:

  % task ls

  ID Project Pri Description           
   1             Book plane ticket
   2             Rent a tux
   3             Reserve a rental car
   4             Send John a birthday card

The 'ls' command provides the most minimal list of tasks.  Each task has been
given an id number, and you can see that there are no projects or priorities
assigned.  Wait a minute - I own a tux, I don't need to rent one.  Let us delete
task 2:

  % task 2 delete
  Permanently delete task? (y/n) y

Task wants you to confirm deletions.  To remove the confirmation, edit your
.taskrc file and remove the line:

  confirmation=yes

or change the yes to no.  

While projects and priorities are not necessary, they can be very useful when
the list of tasks grows large.  Let's assign a project to these tasks:

  % task 1 project:Wedding
  % task 3 project:Wedding
  % task 4 project:Family
  % task ls

  ID Project Pri Description               
   3 Family      Send John a birthday card
   2 Wedding     Reserve a rental car
   1 Wedding     Book plane ticket

Notice that the id numbers have changed.  When tasks get deleted, or have their
attributes changed (project, for example), the ids are prone to change.  But the
id numbers will remain valid until the next 'ls' command is run.  You should
only use the ids from the most recent 'ls' command.

Now that projects are assigned, we can look at just the Wedding project tasks:

  % task ls project:Wedding

  ID Project Pri Description          
   1 Wedding     Book plane ticket
   2 Wedding     Reserve a rental car

Any command arguments after the 'ls' are used for filtering the output.  We
could also have requested:

  % task ls ticket plane

  ID Project Pri Description       
   1 Wedding     Book plane ticket

Now let's prioritize.  Priorities can be H, M or L (High, Medium, Low).

  % task ls

  ID Project Pri Description               
   3 Family      Send John a birthday card
   2 Wedding     Reserve a rental car
   1 Wedding     Book plane ticket

  % task 1 priority:H
  % task 2 prior:M
  % task 3 pr:H
  Ambiguous attribute 'pr' - could be either of project, priority
  % task 3 pri:H
  % task ls

  ID Project Pri Description               
   3 Family  H   Send John a birthday card
   1 Wedding H   Book plane ticket
   2 Wedding M   Reserve a rental car

Notice that task supports the abbreviation of words such as priority, project.
Priority can be abbreviated to pri, but not pr, because it is ambiguous.  Now
that tasks have been prioritized, you can see that the tasks are being sorted
by priority, with the highest priority tasks at the top.

The 'ls' command provides the least information for each task.  The 'list'
command provides more:

  % task list

  ID Project Pri Due Active Age     Description               
   3 Family  H              4 mins Send John a birthday card
   1 Wedding H              5 mins Book plane ticket
   2 Wedding M              5 mins Reserve a rental car

Notice that task can have a due date, and can be active.  The task lists are
sorted by due date, then priority.  Let's add due dates:

  % task 3 due:3/25/2008
  % task 1 due:5/31/2008
  % task list

  ID Project Pri Due       Active Age    Description               
   3 Family  H   3/25/2008        6 mins Send John a birthday card
   1 Wedding H   5/31/2008        7 mins Book plane ticket
   2 Wedding M                    7 mins Reserve a rental car

If today's date is 3/23/2008, then task 3 is due in 2 days.  It will be colored
yellow if your terminal supports color.  To change this color, edit your
.taskrc file, and change the line to one of these alternatives:

  color.due=<foreground color> on <background color>
  color.due=<foreground color>
  color.due=on <background color>

Where color is one of:

  black
  blue
  red
  green
  cyan
  magenta
  yellow
  white

All colors are specified in this way.  Take a look in .taskrc for all the other
colors you control.


Advanced Use
------------

Commands:
  - task add
  - task list
  - task long
  - task ls
  - task done
  - task completed
  - task delete
  - task start
  - task summary
  - task history
  - task next
  - task <modify>
  - task /from/to/
  - task projects
  - task tags
  - task info
  - task active
  - task overdue
  - task calendar
  - task stats
  - task usage
  - task export
  - task version

Interacting with the Shell
--------------------------
  - Escaping shell metacharacters