Advanced Usage
Here are the other commands, in some detail.
% taskWith no arguments, this command will generate a help message that lists all these commands.
However, if the following configuration variable is specified:
default.command=list pri:HThen this command will be run whenever task is run without arguments. This means that your most common task command can be run simply with the command:
% task
[task list project:foo]
ID Project Pri Description
1 foo H Design the thing
2 foo Build the thingThis 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 2This 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% XXXXXXXXXThis 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 <id> append ...Appends the additional description to an existing task.
% task annotate <id> additional note...Allows an annotation to be attached to an existing task. Each annotation has a time stamp, and when displayed, the annotations are shown under the task description. For example:
% task add Go to the supermarket
% task annotate 1 need milk
% task ls
ID Project Pri Due Active Age Description
1 Go to the supermarket
3/23/2009 need milkThe date of the annotation uses the "dateformat" configuration variable.
% task duplicate 1 /foo/bar/g +tag priority:HThis duplicates task 1, then applies the modifications specified, which change all "foo" to "bar" in the description and annotations, adds the tag "tag", and sets the priority to "H".
% task delete <id>There are two ways of getting rid of tasks - mark them as done, or delete them.
% task undelete <id>If a task was inadvertently deleted, it may be undeleted, provided that no reports have been run since the deletion. Ideally, the undelete command is run immediately after the erroneous delete command.
If a report is run (such as "task list"), then task performs a garbage collection that removes deleted tasks, and the task cannot be undeleted.
% task done <id>This is how a task is marked as done.
% task undo <id>If a task was recently marked as done, and no report has been run, it may be possible to cancel the completed status of the task as though "task done ..." was never run.
% 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 <id>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
...Shows all active tasks, that is, the tasks for which the "task start ..." command was run, as shown above.
% task stop <id>Marks a task as inactive, by removing the start time.
% task overdueSimply lists all the task that have a due date that is past, in "list" format.
% task historyThis 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 -9This 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 ghistoryThe ghistory report is a "graphical" version of the history report. It shows a colored bar graph and legend.
% task timesheet 2The timesheet report shows a list of tasks completed and started during a one-week period. In the example above, 2 weeks of tasks are shown.
By default, the report starts on a Monday. To override this value, add an entry to your .taskrc file like this:
weekstart=SundayThis 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 31This 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=2To be your preferred number.
% 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
...Lists the oldest tasks. The number of tasks shown is set by the configuration variable:
report.oldest.limit=10task oldest 5Lists the newest tasks. The number of tasks shown is set by the configuration variable:
report.newest.limit=10task newest 5If 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 a single correction to the first occurrence of "from" in a task description.
If a task is annotated, the annotation can also be modified using this command.
% task <id> /from/to/gThe "g" modifier to the substitution command causes every occurrence of "from" to be replaced with "to", in both the description and any annotations.
% task tagsThis 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 statsThis 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 completedThis 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 colorsThis command displays all the colors that task supports.
% task versionThis can be used to show the version number of task, and to display all the current configuration settings, as read from the .taskrc file.
% task rc:<file> ...
By specifying rc:
% task list
% task rc:~/.taskrc listWhat this override allows, is the possibility of keeping your task lists completely separate, say for work and home. This can be accomplished with the following commands (valid for bash):
% alias htask="task rc:/home/me/.taskrc_home"
% alias wtask="task rc:/home/me/.taskrc_work"
% htask list
...
% wtask list
...Not strictly a command, the replacement of the description can be achieved by quoting the entire description. The quotes are necessary in case one of the description words looks like a task command.
% task <id> editThis command allows you to use your text editor to edit all aspects of a task. The specified task will be written to a file, and your text editor will be invoked. If you modify the task in the text editor, task will update accordingly.
Task will first check to see if you have defined a text editor in the 'editor' configuration variable. If not, task will check to see if you defined a text editor in the VISUAL environment variable. If not task will check to see if you defined a text editor in the EDITOR environment variable. If all those fail, task launches vi.
% task <id> 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_whiteNote that these are not just colors, but combinations of colors and attributes. 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_whiteNote also that this capability does depend on whether your terminal program can display these colors.
Copyright 2006-2009, P. Beckingham. All rights reserved.