taskwarrior/doc/man5/taskrc.5

.TH taskrc 5 2009-05-30 "Task 1.8.0" "User Manuals"

.SH NAME
taskrc \- Configuration file for the task(1) command

.SH SYNOPSIS
.B $HOME/.taskrc
.br
.B task rc:<directory-path>/.taskrc

.SH DESCRIPTION
.B task
obtains its configuration data from a file called
.I .taskrc
\&. This file is normally located in the user's home directory:

.RS
$HOME/.taskrc
.RE

The default location can be overridden using the
.I rc:
attribute when running task:

.RS
$ task rc:<directory-path>/.taskrc
.RE

If
.B task
is run without an existing configuration file it will ask if it should create a default, sample
.I .taskrc
file in the user's home directory.

The task configuration file consists of a series of "assignments" in each line. The "assignments" have the syntax:

.RS
<name-of-configuration-variable>=<value-to-be-set>
.RE

where:
.RS
.TP
<name-of-configuration-variable>
is one of the variables described below

.TP
<value-to-be-set>
is the value the variable is to be set to.
.RE

and set a configuration variable to a certain value. The equal sign ("=") is used to separate the variable
name from the value to be set.

The hash mark, or pound sign ("#") is used as a "comment" character. It can be used to annotate the
configuration file. It is placed at the beginning of a line and all text after the character to the
end of the line is ignored.

.SH CONFIGURATION VARIABLES
Valid variable names and their default values are:

.TP
.B data.location=$HOME/.task
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

.TP
.B locale=en-US
The locale is a combination of ISO 639-1 language code and ISO 3166 country
code.  If not specified, task will assume en-US.  If specified, task will locate
the correct file of localized strings and proceed.  It is an error to specify a
locale for which there is no strings file.

.TP
.B confirmation=yes
May be "yes" or "no", and determines whether task will ask for confirmation before deleting a task. 

.TP
.B echo.command=yes
May be "yes" or "no", and causes task to display the ID and description of any task when you run the start, stop, do, undo, delete and undelete commands. The default value is "yes". 

.TP
.B next=2
Is a number, defaulting to 2, which is the number of tasks for each project that are shown in the 
.B task next
command.

.TP
.B dateformat=m/d/Y
This is a string of characters that define how task formats dates. The default value is: m/d/Y.
The string should contain the characters

.RS
m  minimal-digit month, for example 1 or 12
.br
d  minimal-digit day,   for example 1 or 30
.br
y  two-digit year,      for example 09
.br
D  two-digit day,       for example 01 or 30
.br
M  two-digit month,     for example 01 or 12
.br
Y  four-digit year,     for example 2009
.RE

The string may also contain other characters to act as spacers, or formatting. Examples for other
variable values:

.RS
.br
d/m/Y  would output 24/7/2009
.br
YMD    would output 20090724
.br
m-d-y  would output 07-24-09
.RE

.TP
.B monthsperline=99
Determines how many months the "task calendar" command renders across the screen.
Defaults to however many will fit. If more months that will fit are specified,
task will only show as many that will fit.

.TP
.B defaultwidth=80
The width of tables used when ncurses support is not available. Defaults to 80.

.TP
.B curses=on
Determines whether task uses ncurses to establish the size of the window you are
using, for text wrapping.

.TP
.B fontunderline=on
Determines if font underlines or ascii dashes should be used to underline
headers.

.TP
.B due=7
This is the number of days into the future that define when a task is considered due,
and is colored accordingly. Defaults to 7.

.TP
.B nag=You have higher priority tasks.
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: You have higher
priority tasks.

.TP
.B locking=on
Determines whether task uses file locking when accessing the pending.data and completed.data files.
Default to "on". Solaris users who store the task data files on an NFS mount may need to set locking
to "off". Note that setting this value to "off" is dangerous. It means that another program may write
to the task.pending file when task is attempting to do the same.

.TP
.B editor=vi
Specifies which text editor you wish to use for when the
.B task edit <ID>
command is used. Task will first look for this configuration variable. If found, it is used.
Otherwise task will look for the $VISUAL or $EDITOR environment variables, before it defaults
to using "vi".

.TP
.B color=on
May be "on" or "off". Determines whether task uses color. When "off", task will
use dashes (-----) to underline column headings.

Task has a number of coloration rules. They correspond to a particular attribute
of a task, such as it being due, or being active, and specifies the automatic
coloring of that task. A list of valid color, depending on your terminal, can be
obtained by running the command

.RS
.B task color
.RE

.RS
The coloration rules and their defaults are:
.RE

.RS
.RS
.B color.overdue=bold_red
.br
.B color.due=bold_yellow
.br
.B color.pri.H=bold
.br
.B color.pri.M=on_yellow
.br
.B color.pri.L=on_green
.br
.B color.pri.none=white on_blue
.br
.B color.active=bold_cyan
.br
.B color.tagged=yellow
.br
.B color.recurring=on_red
.RE
.RE

.RS
The value for the coloration rules may be one optional foreground color and one optional
color. For example, the value may be
.RE

.RS
.RS
bold_red on_bright_yellow
.RE
.RE

.RS
Certain attributes like tags, projects and keywords can also have their own coloration rules.
.RE

.RS
.TP
.B color.tag.X=yellow
Colors any task that has the tag X.

.TP
.B color.project.X=on_green
Colors any task assigned to project X.

.TP
.B color.keyword.X=on_blue
Colors any task where the description contains X.
.RE

.TP
.B
shadow.file=$HOME/.task/shadow.txt
If specified, designates a file path that will be automatically written to by task,
whenever the task database changes. In other words, it is automatically kept up to date.
The shadow.command configuration variable is used to determine which report is written
to the shadow file. There is no color used in the shadow file. This feature can be useful
in maintaining a current file for use by programs like GeekTool, Conky or Samurize.

.TP
.B
shadow.command=list
This is the command that is run to maintain the shadow file, determined by the
.I shadow.file
configuration variable. The format is identical to that of
.I default.command
\&. Please see the corresponding documentation for that command.

.TP
.B
shadow.notify=on
When this value is set to "on", task will display a message whenever the shadow
file is updated by some task command.

.TP
.B
default.project=foo
Provides a default project name for the
.I task add
command.

.TP
.B
default.priority=M
Provides a default priority for the
.I task add
command.

.TP
.B
default.command=list
Provides a default command that is run every time task is invoked with no arguments.
For example, if set to:

.RS
.RS
default.command=list project:foo
.RE
.RE

.RS
Then task will run the "list project:foo" command if no command is specified. This means that
by merely typing
.RE

.RS
.RS
$ task
.br
[task list project:foo]
.br
\&
.br
ID Project Pri Description
 1 foo     H   Design foo
 2 foo         Build foo
.RE
.RE

The built in reports can be customized by using the following configuration variables.
The output columns, their labels and the sort order can be set using the corresponding
variables for each report.

.TP
.B
report.long.description
Lists all task, all data, matching the specified criteria

.TP
.B
report.long.labels=ID,Project,Pri,Added,Started,Due,Recur,Age,Tags,Description
.RE
.br
.B
report.long.columns=id,project,priority,entry,start,due,recur,age,tags,description
.br
.B
report.long.sort=due+,priority-,project+

.TP
.B
report.list.description
Lists all tasks matching the specified criteria

.TP
.B
report.list.labels=ID,Project,Pri,Due,Active,Age,Description
.RE
.br
.B
report.list.columns=id,project,priority,due,active,age,description
.br
.B
report.list.sort=due+,priority-,project+


.TP
.B
report.ls.description
Minimal listing of all tasks matching the specified criteria

.TP
.B
report.ls.labels=ID,Project,Pri,Description
.RE
.br
.B
report.ls.columns=id,project,priority,description
.br
.B
report.ls.sort=priority-,project+

.TP
.B
report.newest.description
Shows the newest tasks

.TP
.B
report.newest.labels=ID,Project,Pri,Due,Active,Age,Description
.RE
.br
.B
report.newest.columns=id,project,priority,due,active,age,description
.br
.B
report.newest.sort=id-
.br
.B
report.newest.limit=10


.TP
.B
report.oldest.description
Shows the oldest tasks

.TP
.B
report.oldest.labels=ID,Project,Pri,Due,Active,Age,Description
.RE
.br
.B
report.oldest.columns=id,project,priority,due,active,age,description
.br
.B
report.oldest.sort=id+
.br
.B
report.oldest.limit=10

.SH "CREDITS & COPYRIGHTS"
task was written by P. Beckingham <task@beckingham.net>.
.br
Copyright (C) 2006 \- 2009 P. Beckingham

This man page was originally written by Federico Hernandez. It is based on the task man page, which
was originally written by P.C. Shyamshankar.

task is distributed under the GNU General Public License.  See
http://www.gnu.org/licenses/gpl-2.0.txt for more information.

.SH SEE ALSO
.BR task(1),
.BR task-tutorial(5)

For more information regarding task, the following may be referenced:

.TP
The official site at
<http://taskwarrior.org>

.TP
The official code repository at
<http://github.com/pbeckingham/task/>

.SH REPORTING BUGS
.TP
Bugs in task may be reported to the issue-tracker at
<http://taskwarrior.org>