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 +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 ... 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 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 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