Task program tutorial, for version 1.3.1 ---------------------------------------- This guide shows how to quickly set up the task program, and become proficient with it. Contents: Quick Setup Simple Usage Advanced Usage Interacting with the Shell Configuring Task Colors Quick Setup ----------- Build the task program according to the directions in the INSTALL file. This transcript illustrates a typical installation: % ls task-1.3.1.tar.gz % gunzip task-1.3.1.tar.gz % tar xf task-1.3.1.tar % cd task-1.3.1 % ./configure ... % make ... % make install # (may require sudo, depending on --prefix) 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 whether 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. 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, 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 ------------ Here are the other commands, in some detail. Note that the command: % task with no arguments will generate a help message that lists all these commands. % task projects --------------- This report generates a list of all the different projects that you are using along with a count of the pending tasks for each project. For example: % task projects Project Tasks Errands 1 Birthdays 3 Car 2 % task summary -------------- This report lists all the projects and a summary of their task status. % task summary Project Remaining Avg age Complete 0% 100% Errands 1 3 days 50% XXXXXXXXXXXXXXXX Birthdays 3 7 mths 0% Car 2 2 wks 25% XXXXXXXXX This shows the project, the remaining tasks, the average age of each task, the percentage completed (remaining vs total) and a bar indicating that percentage. % task delete ------------------ There are two ways of getting rid of tasks - mark them as done, or delete them. % task done ---------------- This is how a task is marked as done. % task list ... --------------- The list report will show the active status, and age of the task in addition to the columns that "task ls" shows. It is just a more detailed list. % task long ... --------------- The long report will show the entry date and start date of a task, in addition to the columns that the "task list" shows. % task start ----------------- This marks a task as started (and therefore active), which is shown in the "list" report: % task list ID Project Pri Due Active Age Description 12 Errand L Remember to deposit check ... % task start 12 % task list ID Project Pri Due Active Age Description 12 Errand L * 3 days Remember to deposit check ... % task active ------------- Shows all active tasks, that is, the tasks for which the "task start ..." command was run, as shown above. % task overdue -------------- Simply lists all the task that have a due date that is past, in "list" format. % task oldest ------------- Lists the oldest tasks. Shows 10 tasks by default, but can be set via the "oldest" configuration variable. % task newest ------------- Lists the newest tasks. Shows 10 tasks by default, but can be set via the "newest" configuration variable. % task history -------------- This report shows you an overview of how many tasks were added, completed and deleted, by month. It looks like this: % task history Year Month Added Completed Deleted Net 2008 March 21 16 0 5 April 13 11 1 1 May 8 14 3 -9 This shows that for the three months that task has been used, March and April saw the total number of tasks increase, but in May the number decreased as more task were completed than added. % task calendar --------------- This report shows a calendar of the current month, with any task due or overdue dates marked on it. Color is used to mark these dates. % task calendar May 2008 Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 % task next ----------- This report shows you the tasks you should probable work on next. Task will scan all the tasks and will pick two task from each project to report. Those two tasks will be chosen in order of overdue, due soon, High, Medium or Low priority. Essentially task chooses the two most important task for each project and displays them ordered in the usual way. If you wish to show a different number of tasks per project, modify the entry in .taskrc: next=2 To be your preferred number. % 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 colors ------------- This command displays all the colors that task supports. % task usage ------------ If logging has been enabled by the "command.logging=on" directive in the .taskrc file, then task will record every command that is run. When this command is run, task will display a count of how many times each command was used. This command is for the purpose of seeing whether command are actually used. % 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 -------------------------- Certain characters are interpreted by the shell. For example, the "&". If you wish to include the & in a task description, you need to escape it, so the shell doesn't interpret it. For example: % task add Buy bread & milk This command is an error because of the &. The shell will consider this to be two commands: % task add Buy bread & % milk The shell treats the & character as an indicator that the command is complete and should be run in the background. Then the shell considers "milk" to be a command all by itself. Which it is not. One way to get around this is to individually escape the & character: % task add Buy bread \& milk Another is to quote the entire description, with either ' or " characters: % task add "Buy bread & milk" Task itself interprets the commands, and it too can make mistakes. For example, any colon : character will be interpreted by task as a delimiter between an attribute name and its value. Currently there is no workaround for this. % task fg:... bg:... ------------------------- Not strictly a command, the setting of the fg and bg (foreground and background) attributes determines the colors used to represent the task. Valid foreground colors are: bold underline bold_underline black bold_black underline_black bold_underline_black red bold_red underline_red bold_underline_red green bold_green underline_green bold_underline_green yellow bold_yellow underline_yellow bold_underline_yellow blue bold_blue underline_blue bold_underline_blue magenta bold_magenta underline_magenta bold_underline_magenta cyan bold_cyan underline_cyan bold_underline_cyan white bold_white underline_white bold_underline_white Valid background colors are: on_black on_bright_black on_red on_bright_red on_green on_bright_green on_yellow on_bright_yellow on_blue on_bright_blue on_magenta on_bright_magenta on_cyan on_bright_cyan on_white on_bright_white Note that these are not just colors, but combinations of colors and attributes. Note also that this capability does depend on whether your terminal program can display these colors. Configuring Task ---------------- Task recognizes several entries in the .taskrc file for configuration purposes. Valid entries are of the form: name=value Valid examples are: data.location This is a path to the directory containing all the task files. By default, it is set up to be ~/.task, for example: /Users/paul/.task command.logging May be "on" or "off", defaulting to "off". This determines whether task records commands. This is not generally useful, except while developing task. confirmation May be "yes" or "no", and determines whether task will ask for confirmation before deleting a task. nag This may be a string of text, or blank. It is used as a prompt when a task is completed that is not considered high priority. The "task next" command lists important tasks, and completing one of those does not generate this nagging. Default value is: Note: try to stick to high priority tasks. See "task next". next Is a number, defaulting to 2, which is the number of tasks for each project that are shown in the "task next" command. curses Determines whether task uses ncurses to establish the size of the window you are using, for text wrapping. blanklines May be "on" or "off". Prevents the display of unnecessary blank lines so that task makes better use screen real estate on small-screened devices. dateformat This is a string of characters that define how task formats dates. The default value is: m/d/Y which means dates look like: 6/7/2008 The string should contain the characters: m minimal-digit month 1, 12 d minimal-digit day 1, 30 y two-digit year 08 M two-digit month 01, 12 D two-digit day 01, 30 Y four-digit year 2008 The string may also contain other characters to act as spacers, or formatting. Other values could include (but are not limited to): d/m/Y 7/6/2008 YMD 20080607 m-d-y 6-7-08 showage May be "yes" or "no". Determines whether the "Age" column appears on the "list" and "next" reports. monthsperline Determines how many months the "task calendar" command renders across the screen. Defaults to 1. oldest Determines how many tasks are shown on the "oldest" report. Defaults to 10. newest Determines how many tasks are shown on the "newest" report. Defaults to 10. defaultwidth The width of tables used when ncurses support is not available. Defaults to 80. color May be "on" or "off". Determines whether task uses color. color.overdue These are the coloration rules. They correspond to a color.due particular attribute of a task, such as it being due, or color.pri.H being active, and specifies the automatic coloring of color.pri.M that task. color.pri.L color.pri.none The value may be one optional foreground color (see color.active below) and one optional background color. color.tagged For example, the value may be: bold_red on_bright_yellow color.tag.X Colors any task that has the tag X. color.project.X Colors any task assigned to project X. color.keyword.X Colors any task where the description contains X. Colors ------ Task supports color in several places. In cases where you may specify a color, a foreground, a background, or a combination foreground and background color may be used. The following are valid foreground colors: bold underline bold_underline black bold_black underline_black bold_underline_black red bold_red underline_red bold_underline_red green bold_green underline_green bold_underline_green yellow bold_yellow underline_yellow bold_underline_yellow blue bold_blue underline_blue bold_underline_blue magenta bold_magenta underline_magenta bold_underline_magenta cyan bold_cyan underline_cyan bold_underline_cyan white bold_white underline_white bold_underline_white and the following are valid background colors: on_black on_bright_black on_red on_bright_red on_green on_bright_green on_yellow on_bright_yellow on_blue on_bright_blue on_magenta on_bright_magenta on_cyan on_bright_cyan on_white on_bright_white