mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-09-09 18:50:39 +02:00
Documentation
- New task-tutorial man page not fully formatted yet. but the content is good. - Modified run.193 shell script to match movie.
This commit is contained in:
parent
96d2acef42
commit
8823ba5bfa
2 changed files with 576 additions and 350 deletions
|
@ -3,374 +3,600 @@
|
||||||
.SH NAME
|
.SH NAME
|
||||||
task-tutorial \- A tutorial for the task(1) command line todo manager.
|
task-tutorial \- A tutorial for the task(1) command line todo manager.
|
||||||
|
|
||||||
.SH 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.
|
|
||||||
|
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
Task is a command line TODO list manager. It maintains a list of tasks that you
|
This tutorial contains a narrative and a series of commands that lead you
|
||||||
want to do, allowing you to add/remove, and otherwise manipulate them. Task
|
through different scenarios and illustrate the capabiliries of taskwarrior.
|
||||||
has a rich list of commands that allow you to do various things with it.
|
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.
|
||||||
|
|
||||||
.SH 30 second tutorial
|
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.
|
||||||
|
|
||||||
|
.SH 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.
|
||||||
|
|
||||||
For the excessively lazy. Add two tasks:
|
|
||||||
.br
|
.br
|
||||||
.RS
|
.RS
|
||||||
$ task add Read task documents later
|
$ task add Select a free weekend in November
|
||||||
.br
|
.br
|
||||||
$ task add priority:H Pay bills
|
$ task add Select and book a venue
|
||||||
|
.br
|
||||||
|
$ task add Come up with a guest list
|
||||||
|
.br
|
||||||
|
$ task add Mail invitations
|
||||||
|
.br
|
||||||
|
$ task add Select a caterer
|
||||||
.RE
|
.RE
|
||||||
|
|
||||||
Easy. See that second one has a High priority? Now let's look at those tasks:
|
The '$' prompt shows that these are commands that you type (don't include the
|
||||||
.br
|
$ symbol yourself), and lines without the prompt are those displayed by
|
||||||
.RS
|
taskwarrior. Let's take a look at our tasks so far.
|
||||||
$ task ls
|
|
||||||
.br
|
|
||||||
ID Project Pri Description
|
|
||||||
.br
|
|
||||||
2 H Pay bills
|
|
||||||
.br
|
|
||||||
1 Read task documents later
|
|
||||||
.RE
|
|
||||||
|
|
||||||
They are ordered by priority. Let's mark number 2 as done:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task 2 done
|
|
||||||
.br
|
|
||||||
$ task ls
|
|
||||||
.br
|
|
||||||
ID Project Pri Description
|
|
||||||
.br
|
|
||||||
1 Read task documents later
|
|
||||||
.RE
|
|
||||||
|
|
||||||
Gone. Now let's delete that remaining task, because, well, why bother
|
|
||||||
now we are already using task:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task delete 1
|
|
||||||
.br
|
|
||||||
$ task ls
|
|
||||||
.br
|
|
||||||
No matches
|
|
||||||
.RE
|
|
||||||
|
|
||||||
That's how easy managing your task list can be. But now consider learning what
|
|
||||||
task can really do...
|
|
||||||
|
|
||||||
.SH Simple usage of task
|
|
||||||
Let us begin by adding some tasks:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task add Book plane ticket
|
|
||||||
.br
|
|
||||||
$ task add Rent a tux
|
|
||||||
.br
|
|
||||||
$ task add Reserve a rental car
|
|
||||||
.br
|
|
||||||
$ task add Reserve a hotel room
|
|
||||||
.RE
|
|
||||||
|
|
||||||
You'll notice immediately that task has a very minimalist interface. Let us take
|
|
||||||
a look at those tasks:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task ls
|
|
||||||
.br
|
|
||||||
ID Project Pri Description
|
|
||||||
.br
|
|
||||||
1 Book plane ticket
|
|
||||||
.br
|
|
||||||
2 Rent a tux
|
|
||||||
.br
|
|
||||||
3 Reserve a rental car
|
|
||||||
.br
|
|
||||||
4 Send John a birthday card
|
|
||||||
.RE
|
|
||||||
|
|
||||||
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:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task 2 delete
|
|
||||||
.br
|
|
||||||
Permanently delete task? (y/n) y
|
|
||||||
.RE
|
|
||||||
|
|
||||||
Task wants you to confirm deletions. To suppress the confirmation, edit
|
|
||||||
your .taskrc file and change the line:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
confirmation=yes
|
|
||||||
.RE
|
|
||||||
.br
|
|
||||||
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:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task 1 project:Wedding
|
|
||||||
.br
|
|
||||||
$ task 3 project:Wedding
|
|
||||||
.br
|
|
||||||
$ task 4 project:Family
|
|
||||||
.br
|
|
||||||
$ task ls
|
|
||||||
.br
|
|
||||||
ID Project Pri Description
|
|
||||||
.br
|
|
||||||
3 Family Send John a birthday card
|
|
||||||
.br
|
|
||||||
2 Wedding Reserve a rental car
|
|
||||||
.br
|
|
||||||
1 Wedding Book plane ticket
|
|
||||||
.RE
|
|
||||||
|
|
||||||
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:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task 2 project:Wedding.Transport
|
|
||||||
.br
|
|
||||||
$ task ls
|
|
||||||
.br
|
|
||||||
ID Project Pri Description
|
|
||||||
.br
|
|
||||||
3 Family Send John a birthday card
|
|
||||||
.br
|
|
||||||
2 Wedding.Transport Reserve a rental car
|
|
||||||
.br
|
|
||||||
1 Wedding Book plane ticket
|
|
||||||
.RE
|
|
||||||
|
|
||||||
Task matches the leftmost part of the project when searching, so projects may be
|
|
||||||
abbreviated:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task ls project:Wedding.Tra
|
|
||||||
.br
|
|
||||||
ID Project Pri Description
|
|
||||||
.br
|
|
||||||
2 Wedding.Transport Reserve a rental car
|
|
||||||
.RE
|
|
||||||
|
|
||||||
This way of matching projects can be used to see all tasks under the "Wedding"
|
|
||||||
project and all subprojects:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task ls project:Wedding
|
|
||||||
.br
|
|
||||||
ID Project Pri Description
|
|
||||||
.br
|
|
||||||
2 Wedding.Transport Reserve a rental car
|
|
||||||
.br
|
|
||||||
1 Wedding Book plane ticket
|
|
||||||
.RE
|
|
||||||
|
|
||||||
Let's reassign 2 back to the "Wedding" project:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task 2 project:Wedding
|
|
||||||
.RE
|
|
||||||
|
|
||||||
Now that projects are assigned, we can look at just the Wedding project tasks:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task ls project:Wedding
|
|
||||||
.br
|
|
||||||
ID Project Pri Description
|
|
||||||
.br
|
|
||||||
1 Wedding Book plane ticket
|
|
||||||
.br
|
|
||||||
2 Wedding Reserve a rental car
|
|
||||||
.RE
|
|
||||||
|
|
||||||
Any command arguments after the 'ls' are used for filtering the output.
|
|
||||||
We could also have requested:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task ls ticket plane
|
|
||||||
.br
|
|
||||||
ID Project Pri Description
|
|
||||||
.br
|
|
||||||
1 Wedding Book plane ticket
|
|
||||||
.RE
|
|
||||||
|
|
||||||
Now let's prioritize. Priorities can be H, M or L (High, Medium, Low).
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task ls
|
|
||||||
.br
|
|
||||||
ID Project Pri Description
|
|
||||||
.br
|
|
||||||
3 Family Send John a birthday card
|
|
||||||
.br
|
|
||||||
2 Wedding Reserve a rental car
|
|
||||||
.br
|
|
||||||
1 Wedding Book plane ticket
|
|
||||||
.br
|
|
||||||
$ task 1 priority:H
|
|
||||||
.br
|
|
||||||
$ task 2 prior:M
|
|
||||||
.br
|
|
||||||
$ task 3 pr:H
|
|
||||||
.br
|
|
||||||
Ambiguous attribute 'pr' - could be either of project, priority
|
|
||||||
.br
|
|
||||||
$ task 3 pri:H
|
|
||||||
.br
|
|
||||||
$ task ls
|
|
||||||
.br
|
|
||||||
ID Project Pri Description
|
|
||||||
.br
|
|
||||||
3 Family H Send John a birthday card
|
|
||||||
.br
|
|
||||||
1 Wedding H Book plane ticket
|
|
||||||
.br
|
|
||||||
2 Wedding M Reserve a rental car
|
|
||||||
.RE
|
|
||||||
|
|
||||||
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:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task add project:Wedding priority:H Book plane ticket
|
|
||||||
.RE
|
|
||||||
|
|
||||||
The sequence of those arguments is not important, so you could have entered the
|
|
||||||
following command instead:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task project:Wedding add Book plane priority:H ticket
|
|
||||||
.RE
|
|
||||||
|
|
||||||
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:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ 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
|
|
||||||
.RE
|
|
||||||
|
|
||||||
The 'ls' command provides the least information for each task. The 'list'
|
|
||||||
command provides more:
|
|
||||||
.br
|
.br
|
||||||
.RS
|
.RS
|
||||||
$ task list
|
$ task list
|
||||||
.br
|
|
||||||
ID Project Pri Due Active Age Description
|
|
||||||
.br
|
|
||||||
3 Family H 4 mins Send John a birthday card
|
|
||||||
.br
|
|
||||||
1 Wedding H 5 mins Book plane ticket
|
|
||||||
.br
|
|
||||||
2 Wedding M 5 mins Reserve a rental car
|
|
||||||
.RE
|
.RE
|
||||||
|
|
||||||
Notice that a task can have a due date, and can be active. The task lists are
|
Now I've already ordered a cake, so rather than 'add' this, I'm going to 'log'
|
||||||
sorted by due date, then priority. Let's add due dates:
|
it. This just means that I want to keep track of the task, but I've already
|
||||||
|
done it. It saves me a step.
|
||||||
|
|
||||||
.br
|
.br
|
||||||
.RS
|
.RS
|
||||||
$ task 3 due:6/25/2008
|
$ task log Order a special cake
|
||||||
|
.RE
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
.br
|
.br
|
||||||
$ task 1 due:7/31/2008
|
.RS
|
||||||
|
$ task 4 duplicate /Mail/Design/
|
||||||
|
.br
|
||||||
|
$ task 4 dup /Mail/Print/
|
||||||
.br
|
.br
|
||||||
$ task list
|
$ task list
|
||||||
.br
|
|
||||||
ID Project Pri Due Active Age Description
|
|
||||||
.br
|
|
||||||
3 Family H 6/25/2008 6 mins Send John a birthday card
|
|
||||||
.br
|
|
||||||
1 Wedding H 7/31/2008 7 mins Book plane ticket
|
|
||||||
.br
|
|
||||||
2 Wedding M 7 mins Reserve a rental car
|
|
||||||
.RE
|
.RE
|
||||||
|
|
||||||
Note that due tasks may be colored to highlight the importance. See the
|
That looks good - but now I think of it, I already have my guest list, so I can
|
||||||
task-color(5) man page for full details.
|
mark that one as done.
|
||||||
|
|
||||||
Tagging tasks is a good way to group them, aside from specifying a project.
|
$ task 3 done
|
||||||
To add a tag to a task:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task <id> +tag
|
|
||||||
.RE
|
|
||||||
|
|
||||||
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.
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task list
|
$ task list
|
||||||
.br
|
|
||||||
ID Project Pri Due Active Age Description
|
|
||||||
.br
|
|
||||||
3 Family H 6/25/2008 8 mins Send John a birthday card
|
|
||||||
.br
|
|
||||||
1 Wedding H 7/31/2008 9 mins Book plane ticket
|
|
||||||
.br
|
|
||||||
2 Wedding M 9 mins Reserve a rental car
|
|
||||||
.br
|
|
||||||
$ task 1 +phone
|
|
||||||
.br
|
|
||||||
$ task 2 +phone
|
|
||||||
.br
|
|
||||||
$ task 3 +shopping
|
|
||||||
.br
|
|
||||||
$ task 3 +john
|
|
||||||
.br
|
|
||||||
$ task list +phone
|
|
||||||
.br
|
|
||||||
ID Project Pri Due Active Age Description
|
|
||||||
.br
|
|
||||||
1 Wedding H 7/31/2008 9 mins Book plane ticket
|
|
||||||
.br
|
|
||||||
2 Wedding M 9 mins Reserve a rental car
|
|
||||||
.RE
|
|
||||||
|
|
||||||
To remove a tag from a task, use the minus sign:
|
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...
|
||||||
|
|
||||||
|
.SH PROJECTS
|
||||||
|
Remember to pay the rent at the end of the month.
|
||||||
|
|
||||||
|
$ task add Pay teh rent on teh 31st
|
||||||
|
|
||||||
|
Oh, that was sloppy, but it can be fixed with a global substitution.
|
||||||
|
|
||||||
|
$ task 7 /teh/teh/g
|
||||||
|
$ task list
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
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
|
||||||
|
$ task list project:home
|
||||||
|
$ task li pro:par
|
||||||
|
|
||||||
|
.SH 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 list
|
||||||
|
|
||||||
|
You can remove priorities by specifying a blank value.
|
||||||
|
|
||||||
|
$ task 3 pri:
|
||||||
|
|
||||||
|
.SH 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.
|
||||||
|
|
||||||
|
$ task list
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
The long report shows tags, too,
|
||||||
|
|
||||||
|
$ task long
|
||||||
|
|
||||||
|
and I can use tags as a filter to any report too.
|
||||||
|
|
||||||
|
$ task list +mall
|
||||||
|
|
||||||
|
I made a mistake - I can't mail out the invitations at the mall, so let's remove
|
||||||
|
that tag.
|
||||||
|
|
||||||
|
$ task 3 -mall
|
||||||
|
|
||||||
|
.SH 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
|
||||||
|
|
||||||
|
We'll need music. I can prepend to that. I can append to that.
|
||||||
|
|
||||||
|
$ task add music
|
||||||
|
$ task 8 prepend Select some
|
||||||
|
$ task 8 append for after dinner
|
||||||
|
$ task list
|
||||||
|
|
||||||
|
I can also go straight into an editor and modify anything.
|
||||||
|
|
||||||
|
$ task edit
|
||||||
|
|
||||||
|
Sometimes the command 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 would expand that wildcard, so to avoid that, you can escape the
|
||||||
|
wildcard, 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
|
||||||
|
|
||||||
|
We don't 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 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
|
||||||
|
$ task undo
|
||||||
|
|
||||||
|
.SH 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
|
||||||
|
$ task 1
|
||||||
|
|
||||||
|
There are also statistics that taskwarrior gathers, which I can display.
|
||||||
|
|
||||||
|
$ task stats
|
||||||
|
|
||||||
|
.SH 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 12th looks good
|
||||||
|
$ task 1 annotate or the 13th
|
||||||
|
$ task list
|
||||||
|
|
||||||
|
You can choose to display annotations in different ways.
|
||||||
|
|
||||||
|
$ task list rc.annotations:full
|
||||||
|
$ task list rc.annotations:sparse
|
||||||
|
$ task list rc.annotations:none
|
||||||
|
|
||||||
|
Annotations can be removed by providing a matching pattern.
|
||||||
|
|
||||||
|
$ task 1 denotate 13th
|
||||||
|
$ task list
|
||||||
|
|
||||||
|
.SH 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
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
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
|
||||||
|
$ task config answer
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
.SH 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
|
||||||
|
$ task
|
||||||
|
|
||||||
|
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
|
||||||
|
$ task config default.project Work
|
||||||
|
$ task add New task
|
||||||
|
$ task list
|
||||||
|
|
||||||
|
Let's just revert those changes, to clean up.
|
||||||
|
|
||||||
|
$ task undo
|
||||||
|
$ task config default.priority
|
||||||
|
$ task config default.project
|
||||||
|
|
||||||
|
.SH ALIASES
|
||||||
|
You can create aliases to effectively rename commands.
|
||||||
|
|
||||||
|
$ task config alias.zzz list
|
||||||
|
$ task zzz
|
||||||
|
|
||||||
|
You can abbreviate those, too.
|
||||||
|
|
||||||
|
$ task z
|
||||||
|
|
||||||
|
.SH COLOR
|
||||||
|
All the examples so far have been shown with color turned off. How about some
|
||||||
|
color?
|
||||||
|
|
||||||
|
$ task config color on
|
||||||
|
$ task list
|
||||||
|
|
||||||
|
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
|
||||||
|
$ task list
|
||||||
|
$ task 1 bg:
|
||||||
|
|
||||||
|
Taskwarrior supports 256 colors on certain terminal emulators, and this shows
|
||||||
|
the range of colors available.
|
||||||
|
|
||||||
|
$ task color
|
||||||
|
|
||||||
|
This is how to show a color sample.
|
||||||
|
|
||||||
|
$ task color white on red
|
||||||
|
|
||||||
|
Or samples of all the active color settings.
|
||||||
|
|
||||||
|
$ task color legend
|
||||||
|
|
||||||
|
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 is a color rule that specifies 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
|
||||||
|
|
||||||
|
.SH 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
|
||||||
|
$ task list
|
||||||
|
|
||||||
|
There is an active report that shows only active tasks, and you can mark any
|
||||||
|
active task as inactive, by stopping it.
|
||||||
|
|
||||||
|
$ task active
|
||||||
|
$ task 2 stop
|
||||||
|
|
||||||
|
---------------------------------------- Due dates -------------------------------------------------
|
||||||
|
|
||||||
|
task 1 due:7/31/2010 Due dates can be specified as dates...
|
||||||
|
task 1 due:2wks as some distance into the future...
|
||||||
|
task 1 due:-2wks or past...
|
||||||
|
task 1 due:eom or by mnemonic (end of month)...
|
||||||
|
task 2 due:8th or by ordinal...
|
||||||
|
task 2 due:sunday or by day...
|
||||||
|
task 5 due:eow
|
||||||
|
task list Some of these dates are in the past, so now you see there
|
||||||
|
task overdue are overdue tasks. Due dates have different colors for
|
||||||
|
due, imminent, today and overdue values.
|
||||||
|
|
||||||
|
task rc.dateformat.report:Y-M-DTH:N:SZ list
|
||||||
|
You can also choose the format - for input and output.
|
||||||
|
|
||||||
|
---------------------------------------- Calendar --------------------------------------------------
|
||||||
|
|
||||||
|
task calendar When tasks have due dates, you can see them on the calendar.
|
||||||
|
|
||||||
|
vi ~/.taskrc
|
||||||
|
# include /usr/local/share/doc/task/rc/holidays-US.rc
|
||||||
|
task calendar
|
||||||
|
Taskwarrior provides sample holiday files. You can create
|
||||||
|
your own, or use one of the samples to show holidays on the
|
||||||
|
calendar.
|
||||||
|
|
||||||
|
task cal 2010 You can see the whole year.
|
||||||
|
task rc.calendar.details:full cal You can see the tasks with due dates also.
|
||||||
|
task rc.calendar.holidays:full cal And you can see the holidays.
|
||||||
|
|
||||||
|
---------------------------------------- Recurrence ------------------------------------------------
|
||||||
|
|
||||||
|
task 7 info Remember the task we added to pay the rent? We're going to
|
||||||
|
task 7 due:eom recur:monthly need to do that every month. Recurring tasks allow us to
|
||||||
|
task 7 set up a single task that keeps coming back, just as you'd
|
||||||
|
expect.
|
||||||
|
|
||||||
|
task 7 until:eoy You can also limit the extent of the recurrence. Let's make
|
||||||
|
sure the task doesn't recur after the lease ends.
|
||||||
|
|
||||||
|
task recurring And there is a recurring report that shows you only the
|
||||||
|
recurring tasks.
|
||||||
|
|
||||||
|
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
|
||||||
|
task long
|
||||||
|
|
||||||
|
task 11 delete # y y Deletions to recurring tasks can be escalated to include all
|
||||||
|
task list the recurrences of a task.
|
||||||
|
|
||||||
|
---------------------------------------- Shell -----------------------------------------------------
|
||||||
|
|
||||||
|
task shell You can use the shell command to create a more immersive
|
||||||
|
task> projects environment. Any task command you run outside the shell
|
||||||
|
task> tags can also be run inside the shell, without the need to prefix
|
||||||
|
task> list every command with "task".
|
||||||
|
task> quit
|
||||||
|
|
||||||
|
---------------------------------------- Special Tags ----------------------------------------------
|
||||||
|
|
||||||
|
task 6 +nocolor You've seen tags, but there are also 'special tags' that
|
||||||
|
task list have effects on individual tasks. The 'nocolor' special
|
||||||
|
tag causes the color rules to be bypassed.
|
||||||
|
|
||||||
|
task tags Special tags are highlighted by the 'tags' command.
|
||||||
|
|
||||||
|
task 6 -nocolor 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.
|
||||||
|
|
||||||
|
The 'nocal' special tag will prevent a task from appearing
|
||||||
|
on the calendar.
|
||||||
|
|
||||||
|
---------------------------------------- Waiting ---------------------------------------------------
|
||||||
|
|
||||||
|
task add Look for new apartment due:eoy When you have a task with a due date that is far out into
|
||||||
|
task list the future, you may want to hide that task for a while.
|
||||||
|
|
||||||
|
task 10 wait:12/1/2010 You can provide a wait date for a task, and it will remain
|
||||||
|
task list hidden until that date. It will no longer be cluttering
|
||||||
|
task waiting your task list, but it is still there, and visible using
|
||||||
|
the 'waiting' report. When the wait date comes, the task
|
||||||
|
will just pop back into the list.
|
||||||
|
|
||||||
|
task add Do something in a few seconds To illustrate this, let's set up a task with a very short
|
||||||
|
task 11 wait:5s wait time of five seconds.
|
||||||
|
|
||||||
|
task list It's gone.
|
||||||
|
(sleep 5) We wait for 5 seconds...
|
||||||
|
task list And it's back.
|
||||||
|
task 11 rc.confirmation:no delete And now it's deleted.
|
||||||
|
|
||||||
|
---------------------------------------- Dependencies ----------------------------------------------
|
||||||
|
|
||||||
|
task list pro:party Taskwarrior supports dependencies. Let's take a look at the
|
||||||
|
party planning tasks, and assign dependencies.
|
||||||
|
|
||||||
|
task 3 depends:6 Let's see. I can't mail invitations until they are printed.
|
||||||
|
task 6 dep:5 I can't print them until I design them.
|
||||||
|
task 2 dep:1 I need to select a weekend before a location.
|
||||||
|
task 5 dep:1,2 Design depends on location and weekend.
|
||||||
|
task 4 dep:1 And the caterer needs to know where.
|
||||||
|
|
||||||
|
task long pro:party All my tasks are blocked except task 1. That makes sense.
|
||||||
|
|
||||||
|
task 5 dep:-1 Hmm, that double dependency isn't right.
|
||||||
|
|
||||||
|
task blocked Here are the blocked tasks.
|
||||||
|
task unblocked and the opposite, the unblocked tasks.
|
||||||
|
|
||||||
|
task 1 info If we look at task 1 closely, we can see that it is blocking
|
||||||
|
task 2 info 2 and 4. And if we look at task 2, we see that it is
|
||||||
|
blocked by 1, and blocking 5.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
task 2 done (y) Taskwarrior realizes what you are doing, and offers to fix
|
||||||
|
task 1 info the dependency chain to reflect what you have done.
|
||||||
|
|
||||||
|
---------------------------------------- Reports ---------------------------------------------------
|
||||||
|
|
||||||
|
task minimal Taskwarrior has a good many reports. There is the bare minimum.
|
||||||
|
task ls The simple.
|
||||||
|
task list The standard.
|
||||||
|
task long The kitchen sink.
|
||||||
|
task all The packrat.
|
||||||
|
task completed Nostalgia.
|
||||||
|
task recurring Groundhog day.
|
||||||
|
task waiting Surprises.
|
||||||
|
task blocked Wedged.
|
||||||
|
task unblocked Unencumbered.
|
||||||
|
task oldest Ancient history.
|
||||||
|
task newest Contemporary.
|
||||||
|
task timesheet Corporate.
|
||||||
|
task next 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. It's the report we should all be using.
|
||||||
|
|
||||||
|
---------------------------------------- Custom Report ---------------------------------------------
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
task help | grep foo Custom reports also show up on the help output.
|
||||||
|
|
||||||
|
task show report.foo I can inspect the configuration.
|
||||||
|
|
||||||
|
task foo And they can be run just like the other reports.
|
||||||
|
|
||||||
|
---------------------------------------- Charts ----------------------------------------------------
|
||||||
|
|
||||||
|
task history The history report gives monthly totals of tasks added,
|
||||||
|
task history.annual completed and deleted. There is also an annual version.
|
||||||
|
|
||||||
|
task ghistory There is a graphical monthly...
|
||||||
|
task ghistory.annual and annual version.
|
||||||
|
|
||||||
|
task summary There is a project summary report that shows progress in
|
||||||
|
all the projects.
|
||||||
|
|
||||||
|
---------------------------------------- Advanced Filters ------------------------------------------
|
||||||
|
|
||||||
|
task list Filters are a very powerful tool. First here is an
|
||||||
|
task list invit unfiltered list, which shows all tasks. Now again, but with
|
||||||
|
the text 'invit', which acts as a filter on the description
|
||||||
|
field.
|
||||||
|
|
||||||
|
task list description.contains:invit 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 desc.word:the All tasks containing the whole word 'the'. See how
|
||||||
|
annotations are also searched?
|
||||||
|
|
||||||
|
task list desc.noword:invitations Here is a list of all tasks that do not contain the whole
|
||||||
|
word 'invitations'.
|
||||||
|
|
||||||
|
task list pro:party Here list all tasks in the 'party' project.
|
||||||
|
task list pro.is:party And the full equivalent.
|
||||||
|
task list pro.not:party 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 pri.over:L 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 limit:2 Same again, but only show me the first two tasks.
|
||||||
|
task list limit:page 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 all status:pending 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:waiting The 'waiting' report is similarly defined.
|
||||||
|
|
||||||
|
---------------------------------------- Import/Export ---------------------------------------------
|
||||||
|
|
||||||
|
task export.csv You can export your tasks. Here you see all tasks being
|
||||||
|
exported in CSV format.
|
||||||
|
|
||||||
|
task export.csv venue Let's just export one task in CSV format...
|
||||||
|
task export.vcalendar venue Or in VCalendar format...
|
||||||
|
task export.yaml venue Or YAML.
|
||||||
|
|
||||||
|
cat file.text I can also import. Here I am importing simple lines of
|
||||||
|
task import file.text text. Taskwarrior recognizes the format and confirms.
|
||||||
|
|
||||||
|
cat file.yaml Here is a YAML example. Taskwarrior can read several
|
||||||
|
task import file.yaml formats, including old versions task data. Using YAML,
|
||||||
|
you can round-trip the data without loss.
|
||||||
|
|
||||||
|
task new limit:2 Here are the imported tasks.
|
||||||
|
|
||||||
|
---------------------------------------- Help ------------------------------------------------------
|
||||||
|
|
||||||
|
.SH 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.
|
||||||
|
|
||||||
.br
|
.br
|
||||||
.RS
|
.RS
|
||||||
$ task 3 \-john
|
$ task help
|
||||||
.RE
|
.RE
|
||||||
|
|
||||||
To add a task that you have already completed, use the log command:
|
|
||||||
.br
|
|
||||||
.RS
|
|
||||||
$ task log Notify postal service
|
|
||||||
.RE
|
|
||||||
|
|
||||||
This is equivalent to first adding a new task, then marking that new task
|
|
||||||
as done. It is simple a shortcut.
|
|
||||||
|
|
||||||
.SH Advanced usage of task
|
|
||||||
Advanced examples of the usage of task can be found at the official site at
|
|
||||||
<http://taskwarrior.org>
|
|
||||||
|
|
||||||
.SH "CREDITS & COPYRIGHTS"
|
.SH "CREDITS & COPYRIGHTS"
|
||||||
task was written by P. Beckingham <paul@beckingham.net>.
|
task was written by P. Beckingham <paul@beckingham.net>.
|
||||||
.br
|
.br
|
||||||
|
|
|
@ -9,6 +9,8 @@ echo '#include /usr/local/share/doc/task/rc/dark-blue-256.theme' >> /Users/paul/
|
||||||
echo '#include /usr/local/share/doc/task/rc/dark-red-256.theme' >> /Users/paul/.taskrc
|
echo '#include /usr/local/share/doc/task/rc/dark-red-256.theme' >> /Users/paul/.taskrc
|
||||||
echo '#include /usr/local/share/doc/task/rc/dark-256.theme' >> /Users/paul/.taskrc
|
echo '#include /usr/local/share/doc/task/rc/dark-256.theme' >> /Users/paul/.taskrc
|
||||||
|
|
||||||
|
# 1 Intro
|
||||||
|
|
||||||
# 2 Basic usage
|
# 2 Basic usage
|
||||||
echo Basic usage --------------------------------------------------------------
|
echo Basic usage --------------------------------------------------------------
|
||||||
echo $ task add Select a free weekend in November
|
echo $ task add Select a free weekend in November
|
||||||
|
@ -36,8 +38,6 @@ task 3 done
|
||||||
echo $ task list
|
echo $ task list
|
||||||
task list
|
task list
|
||||||
|
|
||||||
exit # TODO move this line down
|
|
||||||
|
|
||||||
# 3 Projects
|
# 3 Projects
|
||||||
echo Projects --------------------------------------------------------------
|
echo Projects --------------------------------------------------------------
|
||||||
echo $ task add Pay teh rent on teh 31st
|
echo $ task add Pay teh rent on teh 31st
|
||||||
|
@ -423,8 +423,8 @@ echo $ task ghistory
|
||||||
task ghistory
|
task ghistory
|
||||||
echo $ task ghistory.annual
|
echo $ task ghistory.annual
|
||||||
task ghistory.annual
|
task ghistory.annual
|
||||||
echo $ task rc.color.summary.background:"on gray3" summary
|
echo $ task summary
|
||||||
task rc.color.summary.background:"on gray3" summary
|
task summary
|
||||||
|
|
||||||
# 24 Advanced filters
|
# 24 Advanced filters
|
||||||
echo Advanced filters --------------------------------------------------------------
|
echo Advanced filters --------------------------------------------------------------
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue