mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-06-26 10:54:26 +02:00
b34cb90709
- Set up NEWS file, with pleas for feedback. - Added welcome message to README. - Completed a chunk of the TUTORIAL. - Added error handling for "task export" when a file name is not specified.
346 lines
8.7 KiB
Text
346 lines
8.7 KiB
Text
Task program tutorial, for version 1.0.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-1.0.0.tar.gz
|
|
% gunzip task-1.0.0.tar.gz
|
|
% tar xf task-1.0.0.tar
|
|
% cd task-1.0.0
|
|
% ./configure
|
|
...
|
|
% make
|
|
...
|
|
% make install
|
|
|
|
You need to make sure that the installed task program is in your PATH
|
|
environment variable.
|
|
|
|
Task reads a configuration file - called .taskrc in your home directory - and
|
|
stores pending and completed tasks in in a directory specified in the
|
|
configuration file.
|
|
|
|
The simplest way to get a configuration file and task directory is to run task.
|
|
On startup, task will check to see if it can find the configuration file and
|
|
task directory, and if not found, will ask you if it may create both.
|
|
|
|
% task version
|
|
|
|
A configuration file could not be found in /Users/paul/.taskrc
|
|
|
|
Would you like a sample .taskrc created, so task can proceed? (y/n) y
|
|
Done.
|
|
|
|
[then task will show version information]
|
|
|
|
|
|
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 change the line:
|
|
|
|
confirmation=yes
|
|
|
|
to have a value of "no".
|
|
|
|
While the use of projects and priorities are not essential to benefitting from
|
|
task, 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. 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:
|
|
|
|
% 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.
|
|
|
|
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 '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
|
|
|
|
If today's date is 6/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=red
|
|
color.due=on_blue
|
|
color.due=red on_blue
|
|
color.due=bold_red on_blue
|
|
|
|
Where color is one of the following:
|
|
|
|
black
|
|
blue
|
|
red
|
|
green
|
|
cyan
|
|
magenta
|
|
yellow
|
|
white
|
|
|
|
All colors are specified in this way. Take a look in .taskrc for all the other
|
|
color rules that you control.
|
|
|
|
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
|
|
|
|
|
|
|
|
Advanced Use
|
|
------------
|
|
|
|
Commands:
|
|
- task add
|
|
- task list
|
|
- task long
|
|
- task ls
|
|
- task done
|
|
- task delete
|
|
- task start
|
|
- task summary
|
|
- task history
|
|
- task next
|
|
- task projects
|
|
- task active
|
|
- task overdue
|
|
- task calendar
|
|
- task usage
|
|
|
|
|
|
|
|
% task <id> ...
|
|
|
|
When a task id is specified, everything applies to just that task. Suppose
|
|
we needed to correct a task:
|
|
|
|
% task ls
|
|
|
|
ID Project Pri Description
|
|
12 Errand L Remember to deposit chekc
|
|
...
|
|
|
|
% task 12 Remember to deposit bonus check
|
|
% task ls
|
|
|
|
ID Project Pri Description
|
|
12 Errand L Remember to deposit bonus check
|
|
...
|
|
|
|
|
|
|
|
% task /from/to/
|
|
|
|
If a task has been entered with a typo, it can be easily corrected by this
|
|
command. For example:
|
|
|
|
% task ls
|
|
|
|
ID Project Pri Description
|
|
12 Errand L Remember to deposit chekc
|
|
...
|
|
|
|
% task 12 /chekc/check/
|
|
% task ls
|
|
|
|
ID Project Pri Description
|
|
12 Errand L Remember to deposit check
|
|
...
|
|
|
|
This command makes single corrections to a task description.
|
|
|
|
|
|
|
|
% task tags
|
|
|
|
This command will generate a list of all the tags that are currently in use
|
|
by task.
|
|
|
|
|
|
|
|
% task info <id>
|
|
|
|
This command gives detailed information about a single task. It will tell
|
|
you when the task was entered, when started, its status, tags, and more.
|
|
|
|
|
|
|
|
% task stats
|
|
|
|
This command generates a list of statistics about your task usage, such as
|
|
the average time it takes to complete a task, how often new tasks are added,
|
|
and more.
|
|
|
|
|
|
|
|
% task completed
|
|
|
|
This generates a list of all tasks that have been completed, sorted by their
|
|
completion date.
|
|
|
|
|
|
|
|
% task export <file name>
|
|
|
|
This instructs task to write out a CSV format dump of all tasks, both pending
|
|
and completed, to the file specified. This is how you might view tasks in a
|
|
spreadsheet.
|
|
|
|
|
|
|
|
% task version
|
|
|
|
This can be used to show the version number of task, and to display all the
|
|
current configuration settings, as read from the .taskrc file.
|
|
|
|
|
|
Interacting with the Shell
|
|
--------------------------
|
|
- Escaping shell metacharacters
|
|
|
|
|
|
|
|
Configuring Task
|
|
----------------
|
|
|
|
-nag
|
|
-confirmation
|
|
|