Find file
Fetching contributors…
Cannot retrieve contributors at this time
461 lines (290 sloc) 11.7 KB
task_advanced: |-
task Advanced Usage
[ task]
Here are the other commands, in some detail.
% task
With 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:H
Then 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 thing
% 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
% 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 milk
The date of the annotation uses the "dateformat" configuration variable.
% task duplicate 1 /foo/bar/g +tag priority:H
This 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
% task active
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 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 ghistory
The ghistory report is a "graphical" version of the history report. It shows a
colored bar graph and legend.
% task timesheet 2
The 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:
% 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:
To 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
% task oldest [limit]
Lists the oldest tasks. The number of tasks shown is set by the configuration
This value can be overridden at run time by specifying the number of tasks on
the command line:
% task oldest 5
% task newest [limit]
Lists the newest tasks. The number of tasks shown is set by the configuration
This value can be overridden at run time by specifying the number of tasks on
the command line:
task newest 5
% task <id> /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 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
% task <id> /from/to/g
The "g" modifier to the substitution command causes every occurrence of "from"
to be replaced with "to", in both the description and any annotations.
% task tags
This command will generate a list of all the tags that are currently in use by
% 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
% 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
% task colors
This command displays all the colors that task supports.
% 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.
% task rc:<file> ...
By specifying rc:, it is possible to force task to use an alternate .taskrc
file. By default, task looks in your home directory, so these two commands are
essentially identical:
% task list task rc:~/.taskrc list
What 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
% task <id> "new description"
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> edit
This 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
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_white
Note 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_white
Note also that this capability does depend on whether your terminal program
can display these colors.