NAME
task-tutorial - A tutorial for the task(1) command line todo manager.
NOTE
Please note that this tutorial was written for task 1.7.0. Though it is
still accurate on the general usage of task, it might not longer be
100% correct in all details. A new tutorial for task is planned for
task 2.0.0.
DESCRIPTION
Task is a command line TODO list manager. It maintains a list of tasks
that you want to do, allowing you to add/remove, and otherwise
manipulate them. Task has a rich list of commands that allow you to do
various things with it.
30 second tutorial
For the excessively lazy. Add two tasks:
$ task add Read task documents later
$ task add priority:H Pay bills
Easy. See that second one has a High priority? Now let's look at those
tasks:
$ task ls
ID Project Pri Description
2 H Pay bills
1 Read task documents later
They are ordered by priority. Let's mark number 2 as done:
$ task 2 done
$ task ls
ID Project Pri Description
1 Read task documents later
Gone. Now let's delete that remaining task, because, well, why bother
now we are already using task:
$ task delete 1
$ task ls
No matches
That's how easy managing your task list can be. But now consider
learning what task can really do...
Simple usage of task
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
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 suppress the confirmation, edit
your .taskrc file and change the line:
confirmation=yes
to have a value of "no". If the entry is not there, then add it.
While the use of projects and priorities are not essential, they can be
very useful when the list of tasks grows large. Let's assign projects
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. The ids change, because task is always trying to use small
numbers so that it is easy for you to enter them correctly. Now that
projects are assigned, we can look at just the Wedding project tasks:
Subprojects are supported. If you have a project "Wedding", you can
specify that a task is a subproject "Transport" of "Wedding" by
assigning the project "Wedding.Transport". Let's do this:
$ task 2 project:Wedding.Transport
$ task ls
ID Project Pri Description
3 Family Send John a birthday card
2 Wedding.Transport Reserve a rental car
1 Wedding Book plane ticket
Task matches the leftmost part of the project when searching, so
projects may be abbreviated:
$ task ls project:Wedding.Tra
ID Project Pri Description
2 Wedding.Transport Reserve a rental car
This way of matching projects can be used to see all tasks under the
"Wedding" project and all subprojects:
$ task ls project:Wedding
ID Project Pri Description
2 Wedding.Transport Reserve a rental car
1 Wedding Book plane ticket
Let's reassign 2 back to the "Wedding" project:
$ task 2 project:Wedding
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
and 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.
These attributes can all be provided when the task is added, instead of
applying them afterwards, as shown. The following command shows how to
set all the attributes at once:
$ task add project:Wedding priority:H Book plane ticket
The sequence of those arguments is not important, so you could have
entered the following command instead:
$ task project:Wedding add Book plane priority:H ticket
This is because task knows what attributes look like (name:value),
knows what commands it supports (add, ...), and just assumes the rest
is part of the description. Incidentally, if you wanted 'priority:H'
to be part of your task description, you need to fool task into
ignoring it as an attribute. That can be done in two ways:
$ task add "quoting makes task consider priority:H part of one
big argument" $ task add -- the hyphens make task treat
everything after it as description
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 a 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:6/25/2008
$ task 1 due:7/31/2008
$ task list
ID Project Pri Due Active Age Description
3 Family H 6/25/2008 6 mins Send John a birthday card
1 Wedding H 7/31/2008 7 mins Book plane ticket
2 Wedding M 7 mins Reserve a rental car
Note that due tasks may be colored to highlight the importance. See
the task-color(5) man page for full details.
Tagging tasks is a good way to group them, aside from specifying a
project. To add a tag to a task:
$ task <id> +tag
The plus sign indicates that this is a tag. Any number of tags may be
applied to a task, and then used for searching. Tags are just single
words that are labels.
$ task list
ID Project Pri Due Active Age Description
3 Family H 6/25/2008 8 mins Send John a birthday card
1 Wedding H 7/31/2008 9 mins Book plane ticket
2 Wedding M 9 mins Reserve a rental car
$ task 1 +phone
$ task 2 +phone
$ task 3 +shopping
$ task 3 +john
$ task list +phone
ID Project Pri Due Active Age Description
1 Wedding H 7/31/2008 9 mins Book plane ticket
2 Wedding M 9 mins Reserve a rental car
To remove a tag from a task, use the minus sign:
$ task 3 -john
To add a task that you have already completed, use the log command:
$ task log Notify postal service
This is equivalent to first adding a new task, then marking that new
task as done. It is simple a shortcut.
Advanced usage of task
Advanced examples of the usage of task can be found at the official
site at <http://taskwarrior.org>
CREDITS & COPYRIGHTS
task was written by P. Beckingham <paul@beckingham.net>.
Copyright (C) 2006 - 2010 P. Beckingham
This man page was originally written by Federico Hernandez.
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)
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>