GothenburgBitFactory/taskwarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/taskwarrior.git synced 2025-06-26 10:54:26 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
taskwarrior/TUTORIAL

821 lines
23 KiB
Text
Raw Blame History

Task program tutorial, for version 1.4.0
----------------------------------------
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.4.0.tar.gz
% gunzip task-1.4.0.tar.gz
% tar xf task-1.4.0.tar
% cd task-1.4.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.
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 <id> +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 <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 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 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
Average 14 13 1 -1
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
--------------
This report shows you an overview of how many tasks were added, completed and
deleted, by month, as does "task history", but as a bar chart. It looks like this:
% task history
Year Month Added/Completed/Deleted
2008 March +++++++++++++++++++++XXXXXXXXXXXXXXXX
April +++++++++++++XXXXXXXXXXX-
May ++++++++XXXXXXXXXXXXXX---
With color enabled, the bars contain the size of each bar.
% 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 <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 /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 <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 more.
% 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
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.
% 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
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.
% task rc:<file> ...
--------------------
By specifying rc:<file>, 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
...
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.
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
Reference in a new issue View git blame Copy permalink