+ Task Source Code +
+ +
+
+
+ + Download the latest task source code + task-1.0.1.tar.gz + (6/4/2008). +
+ + Commands + +command 1
+command 2
+command 3+ Task Program Tutorial +
+ +
+
+
+ + 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 # (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. 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 Usage +
+ +
+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 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:
+
+ Valid background colors are:
+
+ 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.
+
+ 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
+
+