.TH taskrc 5 2014-01-15 "${PACKAGE_STRING}" "User Manuals"

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

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

.SH DESCRIPTION
.B taskwarrior
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

or using the TASKRC environment variable:

.RS
$ TASKRC=/tmp/.taskrc task ...
.RE

Individual options can be overridden by using the
.I rc.<name>:
attribute when running task:

.RS
$ task rc.<name>:<value> ...
.RE

or

.RS
$ task rc.<name>=<value> ...
.RE

If
.B taskwarrior
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 taskwarrior 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. All text after the character to the end
of the line is ignored.

The configuration file supports UTF8 as well as JSON encoding, such as \\uNNNN.

Note that taskwarrior is flexible about the values used to represent Boolean
items.  You can use "on", "yes", "y", "1" and "true".
Anything else means "off".

.SH EDITING
You can edit your .taskrc file by hand if you wish, or you can use the 'config'
command.  To permanently set a value in your .taskrc file, use this command:

.RS
$ task config nag "You have more urgent tasks."
.RE

To delete an entry, use this command:

.RS
$ task config nag
.RE

Taskwarrior will then use the default value.  To explicitly set a value to
blank, and therefore avoid using the default value, use this command:

.RS
$ task config nag ""
.RE

Taskwarrior will also display all your settings with this command:

.RS
$ task show
.RE

and in addition, will also perform a check of all the values in the file,
warning you of anything it finds amiss.

.SH NESTING CONFIGURATION FILES
The .taskrc can include other files containing configuration settings by using the
.B include
statement:

.RS
include <path/to/the/configuration/file/to/be/included>
.RE

By using include files you can divide your main configuration file into several
ones containing just the relevant configuration data like colors, etc.

There are two excellent uses of includes in your .taskrc, shown here:

.RS
include ${CMAKE_INSTALL_PREFIX}/${TASK_RCDIR}/holidays.en-US.rc
.br
include ${CMAKE_INSTALL_PREFIX}/${TASK_RCDIR}/dark-16.theme
.RE

This includes two standard files that are distributed with taskwarrior, which
define a set of US holidays, and set up a 16-color theme to use, to color the
reports and calendar.

.SH ENVIRONMENT VARIABLES
These environment variables override defaults and command line arguments.

.TP
.B TASKDATA=~/.task
This overrides the default path for the taskwarrior data files.

.TP
.B TASKRC=~/.taskrc
This overrides the default RC file.

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

.SS FILES

.TP
.B data.location=$HOME/.task
This is a path to the directory containing all the taskwarrior files. By
default, it is set up to be ~/.task, for example: /home/paul/.task

Note that you can use the
.B ~
shell meta character, which will be properly expanded.

Note that the TASKDATA environment variable overrides this setting.

.TP
.B locking=on
Determines whether to use file locking when accessing the pending.data and
completed.data files.  Defaults to "on". Solaris users who store the data
files on an NFS mount may need to set locking to "off". Note that there is
danger in setting this value to "off" - another program (or another instance of
task) may write to the task.pending file at the same time.

.TP
.B gc=on
Can be used to temporarily suspend garbage collection (gc), so that task IDs
don't change.  Note that this should be used in the form of a command line
override (task rc.gc=off ...), and not permanently used in the .taskrc file,
as this significantly affects performance in the long term.

.TP
.B exit.on.missing.db=no
When set to 'yes' causes the program to exit if the database (~/.task or
rc.data.location or TASKDATA override) is missing.  Default value is 'no'.

.SS TERMINAL
.TP
.B detection=on
Determines whether to use ioctl to establish the size of the window you are
using, for text wrapping.

.TP
.B defaultwidth=80
The width of output used when auto-detection support is not available. Defaults
to 80.  If set to 0, it is interpreted as infinite width, therefore with no
word-wrapping; this is useful when redirecting report output to a file for subsequent
handling.

.TP
.B defaultheight=24
The height of output used when auto-detection support is not available. Defaults
to 24.  If set to 0, it is interpreted as infinite height. This is useful when redirecting
charts to a file for subsequent handling.

.TP
.B avoidlastcolumn=no
Causes the width of the terminal minus one to be used as the full width.  This
avoids placing color codes in the last column which can cause problems for
Cygwin users.  Default value is 'no'.

.TP
.B hyphenate=on
Hyphenates lines when wrapping breaks occur mid-word.  Default value is 'on'.

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

.TP
.B edit.verbose=on
When set to on (the default), helpful explanatory comments are added to the
edited file when using the "task edit ..." command.  Setting this to off means
that you would see a smaller, more compact representation of the task, with no
help text.  Deprecated - use verbosity token 'edit'.

.TP
.B reserved.lines=1
This is the number of lines reserved at the bottom of the screen for the shell
prompt.  This is only referenced when 'limit:page' is used.

.SS MISCELLANEOUS

.TP
.B verbose=on|off|nothing|list...
When set to "on" (the default), helpful explanatory comments are added to all
output from Taskwarrior.  Setting this to "off" means that you would see regular
output.

The special value "nothing" can be used to eliminate all optional output, which
results in only the formatted data being shown, with nothing else.  This output
is most readily parsed and used by shell scripts.

Alternatively, you can specify a comma-separated list of verbosity tokens that
control specific occasions when output is generated.  This list may contain:

    blank      Inserts extra blank lines in output, for clarity
    header     Messages that appear before report output
    footnote   Messages that appear after report output
    label      Column labels on tabular reports
    new-id     Provides feedback of any new task IDs
    affected   Reports 'N tasks affected' and similar
    edit       Used the verbose template for the 'edit' command
    special    Feedback when applying special tags
    project    Feedback about project status changes
    sync       Feedback about the need for sync

Note that the "on" setting is equivalent to all the tokens being specified,
and the "nothing" setting is equivalent to none of the tokens being specified.

Here are the shortcut equivalents:

.na
.nh
.cflags 4 ,
    verbose=on
    verbose=blank,header,footnote,label,new-id,affected,edit,special,project,sync

    verbose=off
    verbose=blank,label,new-id,edit

    verbose=nothing
    verbose=
.cflags 0 ,
.hy
.ad

Those additional comments are sent to the standard error for header, footnote
and project.  The others are sent to standard output.

.TP
.B confirmation=yes
May be "yes" or "no", and determines whether taskwarrior will ask for
confirmation before deleting a task, performing bulk changes, or the undo
command.  The default value is "yes".  Consider leaving this setting as "yes",
for safety.

.TP
.B echo.command=yes
May be "yes" or "no", and causes the display of the ID and description of any
task when you run the start, stop, do, undo or delete commands. The default
value is "yes".  Deprecated - use verbosity tokens 'header' and  'affected'.

.TP
.B indent.annotation=2
Controls the number of spaces to indent annotations when shown beneath the
description field.  The default value is "2".

.TP
.B indent.report=0
Controls the indentation of the entire report output.  Default is "0".

.TP
.B row.padding=0
Controls left and right padding around each row of the report output.  Default is "0".

.TP
.B column.padding=0
Controls padding between columns of the report output.  Default is "1".

.TP
.B bulk=3
Is a number, defaulting to 3.  When this number or greater of tasks are modified
in a single command, confirmation will be required, unless the
.B confirmation
variable is "no".

This is useful for preventing large-scale unintended changes.

.TP
.B nag=You have more urgent tasks.
This may be a string of text, or blank. It is used as a prompt when a task is
started or completed that is not considered high priority.  Default value is:
You have more urgent tasks.  It is a gentle reminder that you are contradicting
your own priority settings.

.TP
.B complete.all.projects=yes
May be yes or no, and determines whether the tab completion scripts consider all
the project names you have used, or just the ones used in active tasks.  The
default value is "no".

.TP
.B list.all.projects=yes
May be yes or no, and determines whether the 'projects' command lists all the project
names you have used, or just the ones used in active tasks.  The default value is
"no".

.TP
.B complete.all.tags=yes
May be yes or no, and determines whether the tab completion scripts consider all
the tag names you have used, or just the ones used in active tasks.  The default
value is "no".

.TP
.B list.all.tags=yes
May be yes or no, and determines whether the 'tags' command lists all the tag
names you have used, or just the ones used in active tasks.  The default value is
"no".

.TP
.B print.empty.columns=no
May be yes or no, and determines whether columns with no data for any task are
printed.  Defaults to no.

.TP
.B search.case.sensitive=yes
May be yes or no, and determines whether keyword lookup and substitutions on the
description and annotations are done in a case sensitive way.  Defaults to yes.

.TP
.B regex=off
Controls whether regular expression support is enabled.
The default value is off, because this advanced feature could cause confusion
among users that are not comfortable with regular expressions.

.TP
.B xterm.title=no
Sets the xterm window title when reports are run.  Defaults to off.

.TP
.B patterns=on
Enables or disables pattern support on the command line, such as /foo/.
Defaults to on.

.TP
.B expressions=on
Enables or disables algebraic expression support on the command line, such as
"due<eom and (pri=H or pri=M)".  Defaults to on.

.TP
.B dom=on
Enables or disables access to taskwarrior internals and task metadata on the
command line.  Defaults to on.

.TP
.B json.array=off
Determines whether the query command encloses the JSON output in '[...]' to
create a properly-formed JSON array.  Defaults to off.

.TP
.B _forcecolor=no
Taskwarrior shuts off color automatically when the output is not sent directly
to a TTY.  For example, this command:

.RS
.RS
$ task list > file
.RE

will not use any color.  To override this, use:

.RS
$ task rc._forcecolor=yes list > file
.RE
.RE

.TP
.B active.indicator=*
The character or string to show in the start.active column.  Defaults to *.

.TP
.B tag.indicator=+
The character or string to show in the tag.indicator column.  Defaults to +.

.TP
.B dependency.indicator=D
The character or string to show in the depends.indicator column.  Defaults to +.

.TP
.B recurrence.indicator=R
The character or string to show in the recurrence_indicator column.  Defaults to R.

.TP
.B recurrence.limit=1
The number of future recurring tasks to show.  Defaults to 1.  For example, if a
weekly recurring task is added with a due date of tomorrow, and recurrence.limit
is set to 2, then a report will list 2 pending recurring tasks, one for tomorrow,
and one for a week from tomorrow.

.TP
.B undo.style=side
When the 'undo' command is run, taskwarrior presents a before and after
comparison of the data.  This can be in either the 'side' style, which compares
values side-by-side in a table, or 'diff' style, which uses a format similar to
the 'diff' command.

.TP
.B burndown.bias=0.666
The burndown bias is a number that lies within the range 0 <= bias <= 1.  The bias
is the fraction of the find/fix rates derived from the short-term data (last
25% of the report) versus the longer term data (last 50% of the report).  A
value of 0.666 (the default) means that the short-term rate has twice the weight
of the longer-term rate.  The calculation is as follows:

    rate = (long-term-rate * (1 - bias)) + (short-term-rate * bias)

.TP
.B abbreviation.minimum=2
Minimum length of any abbreviated command/value.  This means that "ve", "ver",
"vers", "versi", "versio" will all equate to "version", but "v" will not.
Default is 2.

.TP
.B debug=off
Taskwarrior has a debug mode that causes diagnostic output to be displayed.
Typically this is not something anyone would want, but when reporting a bug,
debug output can be useful.  It can also help explain how the command line is
being parsed, but the information is displayed in a developer-friendly, not a
user-friendly way.

.TP
.B debug.tls=0
Controls the GnuTLS log level.  For 'sync' debugging.

.TP
.B alias.rm=delete
Taskwarrior supports command aliases.  This alias provides an alternate name
(rm) for the delete command.  You can use aliases to provide alternate names for
any of the commands.  Several commands you may use are actually aliases -
the 'history' report, for example, or 'export'.

.SS EXTENSIONS
.TP
.B extensions=on
Enables the extension system.  Defaults to on.

.SS DATES

.TP
.B dateformat=Y-M-D
.TP
.B dateformat.report=
.TP
.B dateformat.holiday=YMD
.TP
.B dateformat.edit=Y-M-D H:N:S
.TP
.B dateformat.info=Y-M-D H:N:S
.TP
.B dateformat.annotation=
.TP
.B report.X.dateformat=Y-M-D
This is a string of characters that defines how taskwarrior formats date values.
The precedence order for the configuration variable is report.X.dateformat then
dateformat.report then dateformat for formating the due dates in reports.
If both report.X.dateformat and dateformat.report are not set then dateformat
will be applied
to the date.  Entered dates as well as all other displayed dates in reports
are formatted according to dateformat.

The default value is the ISO-8601 standard: Y-M-D.  The string can contain the
characters:

.RS
.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 or 12
.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 or 2014
.br
a  short name of weekday,  for example Mon or Wed
.br
A  long name of weekday,   for example Monday or Wednesday
.br
b  short name of month,    for example Jan or Aug
.br
B  long name of month,     for example January or August
.br
v  minimal-digit week,     for example 3 or 37
.br
V  two-digit week,         for example 03 or 37
.br
h  minimal-digit hour,     for example 3 or 21
.br
n  minimal-digit minutes,  for example 5 or 42
.br
s  minimal-digit seconds,  for example 7 or 47
.br
H  two-digit hour,         for example 03 or 21
.br
N  two-digit minutes,      for example 05 or 42
.br
S  two-digit seconds,      for example 07 or 47
.br
J  three-digit Julian day, for example 023 or 365
.br
j  Julian day,             for example 23 or 365
.RE
.RE

.RS
The characters 'v', 'V', 'a' and 'A' can only be used for formatting printed
dates (not to parse them).
.RE

.RS
The string may also contain other characters to act as spacers, or formatting.
Examples for other values of dateformat:
.RE

.RS
.RS
.br
d/m/Y  would use for input and output 24/7/2009
.br
yMD    would use for input and output 090724
.br
M-D-Y  would use for input and output 07-24-2009
.RE
.RE

.RS
Examples for other values of dateformat.report:
.RE

.RS
.RS
.br
a D b Y (V)   would do an output as "Fri 24 Jul 2009 (30)"
.br
A, B D, Y     would do an output as "Friday, July 24, 2009"
.br
wV a Y-M-D    would do an output as "w30 Fri 2009-07-24"
.br
yMD.HN        would do an output as "110124.2342"
.br
m/d/Y H:N     would do an output as "1/24/2011 10:42"
.br
a D b Y H:N:S would do an output as "Mon 24 Jan 2011 11:19:42"
.RE
.RE

.RS
Undefined fields are put to their minimal valid values (1 for month and day and
0 for hour, minutes and seconds) when there is at least one more global date
field that is set.  Otherwise, they are set to the corresponding values of
"now".  For example:
.RE

.RS
.RS
.br
8/1/2013  with m/d/Y   implies August 1, 2013 at midnight (inferred)
.br
8/1 20:40 with m/d H:N implies August 1, 2013 (inferred) at 20:40
.RE
.RE

.TP
.B weekstart=Sunday
Determines the day a week starts. Valid values are Sunday or Monday only. The
default value is "Sunday".

.TP
.B displayweeknumber=yes
Determines if week numbers are displayed when using the "task calendar" command.
The week number is dependent on the day a week starts.  The default value is
"yes".

.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.  The default value is 7.

.TP
.B calendar.details=sparse
If set to full running "task calendar" will display the details of tasks with
due dates that fall into the calendar period.  The corresponding days will be
color-coded in the calendar.  If set to sparse only the corresponding days will
be color coded and no details will be displayed.  The displaying of due dates
with details is turned off by setting the variable to none.  The default value
is "sparse".

.TP
.B calendar.details.report=list
The report to run when displaying the details of tasks with due dates when
running the "task calendar" command.  The default value is "list".

.TP
.B calendar.offset=off
If "on" the first month in the calendar report is effectively changed by the
offset value specified in calendar.offset.value. It defaults to "off".

.TP
.B calendar.offset.value=-1
The offset value to apply to the first month in the calendar report. The default
value is "-1".

.TP
.B calendar.holidays=full
If set to full running "task calendar" will display holidays in the calendar by
color-coding the corresponding days.  A detailed list with the dates and names
of the holidays is also shown.  If set to sparse only the days are color-coded
and no details on the holidays will be displayed. The displaying of holidays is
turned off by setting the variable to none.  The default value is "none".

.TP
.B calendar.legend=yes
Determines whether the calendar legend is displayed.  The default value is "yes".

.SS JOURNAL ENTRIES

.TP
.B journal.time=no
May be yes or no, and determines whether the 'start' and 'stop' commands should
record an annotation when being executed. The default value is "no". The text of
the corresponding annotations is controlled by:

.TP
.B journal.time.start.annotation=Started task
The text of the annotation that is recorded when executing the start command and
having set journal.time.

.TP
.B journal.time.stop.annotation=Stopped task
The text of the annotation that is recorded when executing the stop command and
having set journal.time.

.TP
.B journal.info=on
When enabled, this setting causes a change log of each task to be displayed by
the 'info' command.  Default value is "on".

.SS HOLIDAYS
Holidays are entered either directly in the .taskrc file or via an include file
that is specified in .taskrc.  For each holiday the name and the date is
required to be given:

.RS
.RS
.br
holiday.towel.name=Day of the towel
.br
holiday.towel.date=20100525
.br
holiday.sysadmin.name=System Administrator Appreciation Day
.br
holiday.sysadmin.date=20100730
.RE
.RE

.RS
Dates are to be entered according to the setting in the dateformat.holiday
variable.
.RE

.RS
The following holidays are computed automatically: Good Friday (goodfriday),
Easter (easter), Easter monday (eastermonday), Ascension (ascension), Pentecost
(pentecost). The date for these holidays is the given keyword:
.RE

.RS
.RS
.br
holiday.eastersunday.name=Easter
.br
holiday.eastersunday.date=easter
.RE
.RE

Note that the taskwarrior distribution contains example holiday files that can
be included like this:

.RS
.RS
.br
include ${CMAKE_INSTALL_PREFIX}/${TASK_RCDIR}/holidays.en-US.rc
.RE
.RE

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

.SS DEPENDENCIES

.TP
.B dependency.reminder=on
Determines whether dependency chain violations generate reminders.

.TP
.B dependency.confirmation=yes
Determines whether dependency chain repair requires confirmation.

.SS COLOR CONTROLS

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

.TP
.B fontunderline=on
Determines if font underlines or ASCII dashes should be used to underline
headers, even when color is enabled.
.RE

Taskwarrior 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 colors, depending on your
terminal, can be obtained by running the command:

.RS
.B task color
.RE

.RS
Note that no default values are listed here - the defaults now correspond to the
dark-256.theme (Linux) and dark-16.theme (other) theme values.
The coloration rules are as follows:
.RE

.RS
.B color.due.today
Task is due today
.br
.B color.active
Task is started, therefore active.
.br
.B color.scheduled
Task is scheduled, therefore ready for work.
.br
.B color.blocking
Task is blocking another in a dependency.
.br
.B color.blocked
Task is blocked by a dependency.
.br
.B color.overdue
Task is overdue (due some time prior to now).
.br
.B color.due
Task is coming due.
.br
.B color.project.none
Task does not have an assigned project.
.br
.B color.tag.none
Task has no tags.
.br
.B color.tagged
Task has at least one tag.
.br
.B color.recurring
Task is recurring.
.br
.B color.pri.H
Task has priority H.
.br
.B color.pri.M
Task has priority M.
.br
.B color.pri.L
Task has priority L.
.br
.B color.pri.none
Task has no priority.
.br
.B color.completed
Task is completed.
.br
.B color.deleted
Task is deleted.
.RE
.RE

.RS
To disable a coloration rule for which there is a default, set the value to
nothing, for example:
.RS
.B color.tagged=
.RE
.RE

See the task-color(5) man pages for color details.
.RE

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

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

.TP
.B color.project.X=on green
Colors any task assigned to project X.
.RE

.TP
.B color.keyword.X=on blue
Colors any task where the description or any annotation contains X.
.RE

.TP
.B color.uda.X=on green
Colors any task that has the user defined attribute X.
.RE

.TP
.B color.error=green
Colors any of the error messages.
.RE

.TP
.B color.header=green
Colors any of the messages printed prior to the report output.
.RE

.TP
.B color.footnote=green
Colors any of the messages printed last.
.RE

.TP
.B color.summary.bar=on green
Colors the summary progress bar.  Should consist of a background color.
.RE

.TP
.B color.summary.background=on black
Colors the summary progress bar.  Should consist of a background color.
.RE

.TP
.B color.calendar.today=black on cyan
Color of today in calendar.
.RE

.TP
.B color.calendar.due=black on green
Color of days with due tasks in calendar.
.RE

.TP
.B color.calendar.due.today=black on magenta
Color of today with due tasks in calendar.
.RE

.TP
.B color.calendar.overdue=black on red
Color of days with overdue tasks in calendar.
.RE

.TP
.B color.calendar.weekend=bright white on black
Color of weekend days in calendar.
.RE

.TP
.B color.calendar.holiday=black on bright yellow
Color of holidays in calendar.
.RE

.TP
.B color.calendar.weeknumber=black on white
Color of weeknumbers in calendar.
.RE

.TP
.B color.label=
Colors the report labels.  Defaults to not use color.
.RE

.TP
.B color.alternate=on rgb253
Color of alternate tasks.
This is to apply a specific color to every other task in a report,
which can make it easier to visually separate tasks.  This is especially
useful when tasks are displayed over multiple lines due to long descriptions
or annotations.
.RE

.TP
.B color.history.add=on red
.RE
.br
.B color.history.done=on green
.RE
.br
.B color.history.delete=on yellow
.RS
Colors the bars on the ghistory report graphs.  Defaults to red, green and
yellow bars.
.RE

.TP
.B color.burndown.pending=on red
.RE
.br
.B color.burndown.started=on yellow
.RE
.br
.B color.burndown.done=on green
.RS
Colors the bars on the burndown reports graphs.  Defaults to red, green and
yellow bars.
.RE

.TP
.B color.undo.before=red
.RE
.br
.B color.undo.after=green
.RS
Colors used by the undo command, to indicate the values both before and after
a change that is to be reverted.
.RE

.TP
.B color.sync.added=green
.RE
.br
.B color.sync.changed=yellow
.RE
.br
.B color.sync.rejected=red
.RS
Colors the output of the sync command.
.RE

.TP
.na
.nh
.cflags 4 ,
.B rule.precedence.color=due.today,active,blocking,blocked,overdue,due,scheduled,keyword.,project.,tag.,uda.,recurring,pri.,tagged,completed,deleted
.cflags 0 ,
.hy
.ad
.RS
This setting specifies the precedence of the color rules, from highest to
lowest.  Note that the prefix 'color.' is omitted (for brevity), and that any
wildcard value (color.tag.XXX) is shortened to 'tag.', which places all
specific tag rules at the same precedence, again for brevity.
.RE

.TP
.B color.debug=green
.RS
Colors all debug output, if enabled.
.RE

.SS URGENCY

The urgency calculation uses a polynomial with several terms, each of which
has a configurable coefficient.  Those coefficients are:

.TP
.B urgency.next.coefficient=15.0
.RS
Urgency coefficient for 'next' special tag
.RE
.B urgency.blocking.coefficient=8.0
.RS
Urgency coefficient for blocking tasks
.RE
.B urgency.blocked.coefficient=-5.0
.RS
Urgency coefficient for blocked tasks
.RE
.B urgency.due.coefficient=12.0
.RS
Urgency coefficient for due dates
.RE
.B urgency.priority.coefficient=6.0
.RS
Urgency coefficient for priorities
.RE
.B urgency.waiting.coefficient=-3.0
.RS
Urgency coefficient for waiting status
.RE
.B urgency.active.coefficient=4.0
.RS
Urgency coefficient for active tasks
.RE
.B urgency.scheduled.coefficient=5.0
.RS
Urgency coefficient for scheduled tasks
.RE
.B urgency.project.coefficient=1.0
.RS
Urgency coefficient for projects
.RE
.B urgency.tags.coefficient=1.0
.RS
Urgency coefficient for tags
.RE
.B urgency.annotations.coefficient=1.0
.RS
Urgency coefficient for annotations
.RE
.B urgency.age.coefficient=2.0
.RS
Urgency coefficient for the age of tasks
.RE
.B urgency.age.max=365
.RS
Maximum age in days. After this number of days has elapsed, the urgency of a task won't increase any more because of aging.
.RE
.B urgency.user.tag.<tag>.coefficient=...
.RS
Specific tag coefficient.
.RE
.B urgency.user.project.<project>.coefficient=...
.RS
Specific project coefficient.
.RE
.B urgency.uda.<name>.coefficient=...
.RS
Presence/absence of UDA data.
.RE

The coefficients reflect the relative importance of the various terms in the
urgency calculation.  These are default values, and may be modified to suit your
preferences, but it is important that you carefully consider any modifications.
See the original RFC-31 for complete details at:
.br
.na
.nh
.cflags 4 /
.cflags 2 ;
http://tasktools.org/gitweb/gitweb.cgi?p=rfc.git;a=blob_plain;f=rfc31-urgency.txt;hb=HEAD
.cflags 0 ; /
.hy
.ad

.SS SHADOW FILE

.TP
.B
shadow.file=$HOME/.task/shadow.txt
If specified, designates a file path that will be automatically written to by
taskwarrior, 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", taskwarrior will display a message whenever the
shadow file is updated by some task command.

.SS DEFAULTS

.TP
.B
default.project=foo
Provides a default project name for the
.I task add
command, if you don't specify one.  The default is blank.

.TP
.B
default.priority=M
Provides a default priority for the
.I task add
command, if you don't specify one.  The default is blank.

.TP
.B
default.due=...
Provides a default due date for the
.I task add
command, if you don't specify one.  The default is blank.

.TP
.B
uda.<name>.default=...
Provides default values for UDA fields when using the
.I task add
command, if you don't specify values.  The default is blank.

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

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

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

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

.SS REPORTS

The 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. Each report name is used as a
"command" name. For example

.TP
.B task overdue

.TP
.B report.X.description
The description for report X when running the "task help" command.

.TP
.B report.X.columns
This is a comma-separated list of columns and formatting specifiers.  See the
command 'task columns' for a full list of options and examples.

.TP
.B report.X.labels
The labels for each column that will be used when generating report X. The
labels are a comma separated list.

.TP
.B report.X.sort
The sort order of the tasks in the generated report X. The sort order is
specified by using the column ids post-fixed by a "+" for ascending sort order
or a "-" for descending sort order. The sort IDs are separated by commas.
For example:

    report.list.sort=due+,priority-,start.active-,project+

.TP
.B report.X.filter
This adds a filter to the report X so that only tasks matching the filter
criteria are displayed in the generated report.

.TP
.B report.X.dateformat
This adds a dateformat to the report X that will be used by the "due date"
column. If it is not set then dateformat.report and dateformat will be used in
this order. See the
.B DATES
section for details on the sequence placeholders.

.TP
.B report.X.annotations
This adds the possibility to control the output of annotations for a task in a
report. See the
.B annotations
variable for details on the possible values.  Deprecated.

.TP
.B report.X.limit
An optional value to a report limiting the number of displayed tasks in the
generated report.  Deprecated.

.TP
Taskwarrior comes with a number of predefined reports, which are:

.TP
.B next
Lists the most important tasks.

.TP
.B long
Lists all pending tasks and all data, matching the specified criteria.

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

.TP
.B ls
Short listing of all tasks matching the specified criteria.

.TP
.B minimal
Minimal listing of all tasks matching the specified criteria.

.TP
.B newest
Shows the newest tasks.

.TP
.B oldest
Shows the oldest tasks.

.TP
.B overdue
Lists overdue tasks matching the specified criteria.

.TP
.B active
Lists active tasks matching the specified criteria.

.TP
.B completed
Lists completed tasks matching the specified criteria.

.TP
.B recurring
Lists recurring tasks matching the specified criteria.

.TP
.B waiting
Lists all waiting tasks matching the specified criteria.

.TP
.B all
Lists all tasks matching the specified criteria.

.TP
.B blocked
Lists all tasks that have dependencies.

.SS USER DEFINED ATTRIBUTES

User defined attributes (UDAs) are an extension mechanism that allows you to
define new attributes for Taskwarrior to store and display.  One such example is
an 'estimate' attribute that could be used to store time estimates associated
with a task.  This 'estimate' attribute is not built in to Taskwarrior, but with
a few simple configuration settings you can instruct Taskwarrior to store this
item, and provide access to it for custom reports and filters.

This allows you to augment Taskwarrior to accommodate your workflow, or bend the
rules and use Taskwarrior to store and synch data that is not necessarily
task-related.

One important restriction is that because this is an open system that allows
the definition of any new attribute, Taskwarrior cannot understand the meaning
of that attribute.  So while Taskwarrior will faithfully store, modify, report,
sort and filter your UDA, it does not understand anything about it.  For example
if you define a UDA named 'estimate', Taskwarrior will not know that this value
is weeks, hours, minutes, money, or some other resource count.

.TP
.B uda.<name>.type=string|numeric|date|duration
.RS
Defines a UDA called '<name>', of the specified type.
.RE

.TP
.B uda.<name>.label=<column heading>
.RS
Provides a default report label for the UDA called '<name>'.
.RE

.TP
.B uda.<name>.values=A,B,C
.RS
For type 'string' UDAs only, this provides a comma-separated list of acceptable
values.  In this example, the '<name>' UDA may only contain values 'A', 'B',
or 'C', but may also contain no value.
.RE

.TP
.B Example 'estimate' UDA
This example shows an 'estimate' UDA that stores specific values for the size
of a task.

.RS
.B uda.estimate.type=string
.br
.B uda.estimate.label=Size Estimate
.br
.B uda.estimate.values=trivial,small,medium,large,huge
.RE

.SS SYNC

These configuration settings are used to connect and sync tasks with the task
server.

.TP
.B taskd.server=<host>:<port>
.RS
Specifies the hostname and port of the Taskserver.  Hostname may be an IPv4 or
IPv6 address, or domain.  Port is an integer.
.RE

.TP
.B taskd.credentials=<organization>/<user>/<key>
.RS
User identification for the Taskserver, which includes a private key.
.RE

.TP
.B taskd.certificate=<path>
.RS
Specifies the path to the client certificate used for identification with the
Taskserver.
.RE

.TP
.B taskd.key=<path>
.RS
Specifies the path to the client key used for encrypted communication with the
Taskserver.
.RE

.TP
.B taskd.ca=<path>
.RS
Specifies the path to the CA certificate in the event that your Taskserver is
using a self-signed certificate.  Optional.
.RE

.TP
.B taskd.trust=yes|no
.RS
If you do not specify a CA certificate when your Taskserver is using a self-
signed certificate, you can override the certificate validation by setting this
value to 'yes'.  Default is not to trust a server certificate.
.RE

.TP
.B taskd.ciphers=NORMAL
Override of the cipher selection.  The set of ciphers used by TLS may be
controlled by both server and client.  There must be some overlap between
client and server supported ciphers, or communication cannot occur.
Default is "NORMAL".  See GnuTLS documentation for full details.
.RE

.SH "CREDITS & COPYRIGHTS"
Copyright (C) 2006 \- 2014 P. Beckingham, F. Hernandez.

This man page was originally written by Federico Hernandez.

Taskwarrior is distributed under the MIT license. See
http://www.opensource.org/licenses/mit-license.php for more information.

.SH SEE ALSO
.BR task(1),
.BR tasksh(1),
.BR task-tutorial(5),
.BR task-faq(5),
.BR task-color(5),
.BR task-sync(5)

For more information regarding taskwarrior, see the following:

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

.TP
The official code repository at
<git://tasktools.org/task.git/>

.TP
You can contact the project by emailing
<support@taskwarrior.org>

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