NAME
taskrc - Configuration file for the task(1) command
SYNOPSIS
$HOME/.taskrc
task rc:<directory-path>/.taskrc
DESCRIPTION
task obtains its configuration data from a file called .taskrc . This
file is normally located in the user's home directory:
$HOME/.taskrc
The default location can be overridden using the rc: attribute when
running task:
$ task rc:<directory-path>/.taskrc
Individual option can be overridden by using the rc.<name>: attribute
when running task:
$ task rc.<name>:<value> ...
If task is run without an existing configuration file it will ask if it
should create a default, sample .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:
<name-of-configuration-variable>=<value-to-be-set>
where:
<name-of-configuration-variable>
is one of the variables described below
<value-to-be-set>
is the value the variable is to be set to.
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.
Note that task is flexible about the values used to represent Boolean
items. You can use "on", "yes", "y", "1", "true", "t", "+", "enabled".
Anything else means "off".
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:
$ task config nag "You have higher priority tasks!"
To delete an entry, use this command:
$ task config nag
Task will then use the default value. To explicitly set a value to
blank, and therefore avoid using the default value, use this command:
$ task config nag ""
Task will also display all your settings with this command:
$ task config
and in addition, will also perform a check of all the values in the
file, warning you of anything it finds amiss.
NESTING CONFIGURATION FILES
The .taskrc can include other files containing configuration settings
by using the include statement:
include <path/to/the/configuration/file/to/be/included>
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:
include /usr/local/share/doc/task/rc/holidays-US.rc
include /usr/local/share/doc/task/rc/dark-16.theme
This includes two standard files that are distributed with task, which
define a set of US holidays, and set up a 16-color theme for task to
use, to color the reports and calendar.
CONFIGURATION VARIABLES
Valid variable names and their default values are:
FILES
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:
/home/paul/.task
Note that you can use the ~ shell meta character, which will be
properly expanded.
locking=on
Determines whether task uses file locking when accessing the
pending.data and completed.data files. Defaults to "on".
Solaris users who store the task 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.
TERMINAL
curses=on
Determines whether task uses ncurses to establish the size of
the window you are using, for text wrapping.
defaultwidth=80
The width of tables used when ncurses support is not available.
Defaults to 80.
editor=vi
Specifies which text editor you wish to use for when the 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".
MISCELLANEOUS
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.
confirmation=yes
May be "yes" or "no", and determines whether task will ask for
confirmation before deleting a task or doing bulk changes. The
default value is "yes".
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
or delete commands. The default value is "yes".
annotations=full
report.X.annotations=full
Controls the display of annotations in reports. Defaults to full
- all annotations are displayed. Set to "sparse" only the last
(newest) annotation is displayed and if there are more than one
present for a task a "+" sign is added to the description. Set
to "none" the output of annotations is disabled and a "+" sign
will be added if there are any annotations present. The default
value is "full".
next=2 Is a number, defaulting to 2, which is the number of tasks for
each project that are shown in the task next command.
bulk=2 Is a number, defaulting to 2. When more than this number of
tasks are modified in a single command, confirmation will be
required, unless the confirmation variable is "no".
This is useful for preventing large-scale unintended changes.
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 started or 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. It is a gentle
reminder that you are contradicting your own priority settings.
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".
list.all.projects=yes
May be yes or no, and determines whether 'projects' command
lists all the project names you have used, or just the ones used
in active tasks. The default value is "no".
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".
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".
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.
_forcecolor=no
Task shuts off color automatically when the output is not sent
directly to a a TTY. For example, this command:
$ task list > file
will not use any color. To override this, use:
$ task rc._forcecolor=yes list > file
blanklines=yes
Turning this value off causes task to generate a more vertically
compact output.
shell.prompt=task>
The task shell command uses this value as a prompt. You can
change it to any string you like.
active.indicator=*
The character or string to show in the active column. Defaults
to *.
tag.indicator=+
The character or string to show in the tag_indicator column.
Defaults to +.
recurrence.indicator=R
The character or string to show in the recurrence_indicator
column. Defaults to R.
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.
undo.style=side
When the 'undo' command is run, task 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.
debug=off
Task 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.
alias.rm=delete
Task 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 task's commands. Several
commands you may use are actually aliases - 'history', for
example, or 'export'.
DATES
dateformat=m/d/Y
dateformat.report=m/d/Y
dateformat.holiday=YMD
dateformat.annotation=m/d/Y
report.X.dateformat=m/d/Y
This is a string of characters that define how task formats date
values. The precedence order for the configuration variable is
report.X.dateformat then reportdateformat then dateformat.
While report.X.dateformat only formats the due date in reports,
reportdateformat formats the due date both in reports and "task
info". If both of these are not set then dateformat will be
applied to the due date. Entered dates as well as all other
displayed dates in reports are formatted according to
dateformat.
The default value is: m/d/Y. The string should contain the
characters:
m minimal-digit month, for example 1 or 12
d minimal-digit day, for example 1 or 30
y two-digit year, for example 09
D two-digit day, for example 01 or 30
M two-digit month, for example 01 or 12
Y four-digit year, for example 2009
a short name of weekday, for example Mon or Wed
A long name of weekday, for example Monday or Wednesday
b short name of month, for example Jan or Aug
B long name of month, for example January or August
V weeknumber, for example 03 or 37
H two-digit hour, for example 03 or 11
N two-digit minutes, for example 05 or 42
S two-digit seconds, for example 07 or 47
The string may also contain other characters to act as spacers,
or formatting. Examples for other values of dateformat:
d/m/Y would use for input and output 24/7/2009
yMD would use for input and output 090724
M-D-Y would use for input and output 07-24-2009
Examples for other values of reportdateformat:
a D b Y (V) would do an output as "Fri 24 Jul 2009 (30)"
A, B D, Y would do an output as "Friday, July 24,
2009"
vV a Y-M-D would do an output as "v30 Fri 2009-07.24"
weekstart=Sunday
Determines the day a week starts. Valid values are Sunday or
Monday only. The default value is "Sunday".
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".
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.
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".
calendar.details.report=list
The report to run when displaying the details of tasks with due
date when running the "task calendar" command. The default
value is "list".
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".
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:
holiday.towel.name=Day of the towel
holiday.towel.date=20100525
holiday.sysadmin.name=System Administrator Appreciation
Day
holiday.sysadmin.date=20100730
Dates are to be entered according to the setting in the
dateformat.holiday variable.
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:
holiday.eastersunday.name=Easter
holiday.eastersunday.date=easter
Note that the task distribution contains example holiday files that can
be included like this:
include /usr/local/share/doc/task/rc/holidays-US.rc
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, task will only show as many
that will fit.
COLOR CONTROLS
color=on
May be "on" or "off". Determines whether task uses color. When
"off", task will use dashes (-----) to underline column
headings.
fontunderline=on
Determines if font underlines or ASCII dashes should be used to
underline headers, even when color is enabled.
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 colors,
depending on your terminal, can be obtained by running the command:
task color
The coloration rules and their defaults are:
color.overdue=bold red The color for overdue tasks.
color.due.today=bold magenta The color of tasks due today.
color.due=bold yellow The color of due tasks.
color.pri.H=bold The color of priority:H tasks.
color.pri.M=on yellow The color of priority:M tasks. No default
value.
color.pri.L=on green The color of priority:L tasks. No default
value.
color.pri.none=white on blue The color of priority: tasks. No
default value.
color.active=bold cyan The color of active tasks.
color.tagged=yellow The color of tagged tasks.
color.recurring=on red The color for recurring tasks.
To disable a coloration rule for which there is a default, set
the value to nothing, for example:
color.tagged=
See the task-color(5) man pages for color details.
Certain attributes like tags, projects and keywords can have their own
coloration rules.
color.tag.X=yellow
Colors any task that has the tag X.
color.project.X=on green
Colors any task assigned to project X.
color.keyword.X=on blue
Colors any task where the description or any annotation contains
X.
color.header=green
Colors any of the messages printed prior to the report output.
color.footnote=green
Colors any of the messages printed last.
color.summary.bar=on green
Colors the summary progress bar. Should consist of a background
color.
color.summary.background=on black
Colors the summary progress bar. Should consist of a background
color.
color.calendar.today=black on cyan
Color of today in calendar.
color.calendar.due=black on green
Color of days with due tasks in calendar.
color.calendar.due.today=black on magenta
Color of today with due tasks in calendar.
color.calendar.overdue=black on red
Color of days with overdue tasks in calendar.
color.calendar.weekend=bright white on black
Color of weekend days in calendar.
color.calendar.holiday=black on bright yellow
Color of holidays in calendar.
color.calendar.weeknumber=black on white
Color of weeknumbers in calendar.
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.
color.history.add=on red
color.history.done=on green
color.history.delete=on yellow
Colors the bars on the ghistory report graphs. Defaults to red,
green and yellow bars.
color.undo.before=red
color.undo.after=green
Colors used by the undo command, to indicate the values both
before and after a change that is to be reverted.
SHADOW FILE
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.
shadow.command=list
This is the command that is run to maintain the shadow file,
determined by the shadow.file configuration variable. The format
is identical to that of default.command . Please see the
corresponding documentation for that command.
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.
DEFAULTS
default.project=foo
Provides a default project name for the task add command, if you
don't specify one. The default is blank.
default.priority=M
Provides a default priority for the task add command, if you
don't specify one. The default is blank.
default.command=list
Provides a default command that is run every time task is
invoked with no arguments. For example, if set to:
default.command=list project:foo
then task will run the "list project:foo" command if no command
is specified. This means that by merely typing
$ task
[task list project:foo]
ID Project Pri Description
1 foo H Design foo
2 foo Build foo
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
task overdue
report.X.description
The description for report X when running the "task help"
command.
report.X.columns
The columns that will be used when generating the report X.
Valid columns are: id, uuid, project, priority, entry, start,
due, recur, recur_indicator, age, age_compact, active, tags,
tag_indicator, description, description_only, countdown,
countdown_compact. The IDs are separated by commas.
report.X.labels
The labels for each column that will be used when generating
report X. The labels are a comma separated list.
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
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.
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 reportdateformat and
dateformat will be used in this order. See the DATES section for
details on the sequence placeholders.
report.X.annotations
This adds the possibility to control the output of annotations
for a task in a report. See the annotations variable for details
on the possible values.
report.X.limit
An optional value to a report limiting the number of displayed
tasks in the generated report.
Task comes with a number of predefined reports in its default
configuration
file. These reports are:
long Lists all task, all data, matching the specified criteria.
list Lists all tasks matching the specified criteria.
ls Short listing of all tasks matching the specified criteria.
minimal
Minimal listing of all tasks matching the specified criteria.
newest Shows the newest tasks.
oldest Shows the oldest tasks.
overdue
Lists overdue tasks matching the specified criteria.
active Lists active tasks matching the specified criteria.
completed
Lists completed tasks matching the specified criteria.
recurring
Lists recurring tasks matching the specified criteria.
waiting
Lists all waiting tasks matching the specified criteria.
all Lists all tasks matching the specified criteria.
next Lists all tasks with upcoming due dates matching the specified
criteria.
CREDITS & COPYRIGHTS
task was written by P. Beckingham <paul@beckingham.net>.
Copyright (C) 2006 - 2010 P. Beckingham
This man page was originally written by Federico Hernandez.
task is distributed under the GNU General Public License. See
http://www.gnu.org/licenses/gpl-2.0.txt for more information.
SEE ALSO
task(1), task-tutorial(5), task-faq(5) task-color(5)
For more information regarding task, the following may be referenced:
The official site at
<http://taskwarrior.org>
The official code repository at
<git://tasktools.org/task.git/>
You can contact the project by writing an email to
<support@taskwarrior.org>
REPORTING BUGS
Bugs in task may be reported to the issue-tracker at
<http://taskwarrior.org>