other versions
- wheezy 2.0.0-1
- wheezy-backports 2.2.0-3~bpo70+1
- jessie 2.3.0+dfsg-3
- testing 2.5.1+dfsg-3
- unstable 2.5.1+dfsg-3
taskrc(5) | User Manuals | taskrc(5) |
NAME¶
taskrc - Configuration file for the task(1) commandSYNOPSIS¶
$HOME/.taskrcDESCRIPTION¶
taskwarrior obtains its configuration data from a file called .taskrc . This file is normally located in the user's home directory:$HOME/.taskrc
$ task rc:<directory-path>/.taskrc
...
$ TASKRC=/tmp/.taskrc task ...
$ task rc.<name>:<value> ...
$ task rc.<name>=<value> ...
<name-of-configuration-variable>=<value-to-be-set>
- <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.
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!"
$ task config nag
$ task config nag ""
$ task show
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>
include /usr/share/task/holidays.en-US.rc
include /usr/share/task/dark-16.theme
ENVIRONMENT VARIABLES¶
These environmant variables override defaults and command line arguments.- TASKDATA=~/.task
- This overrides the default path for the taskwarrior data
files.
- TASKRC=~/.taskrc
- This overrides the default RC file.
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
taskwarrior files. By default, it is set up to be ~/.task, for example:
/home/paul/.task
- 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.
- 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.
- 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'.
TERMINAL¶
- detection=on
- Determines whether to use ioctl to establish the size of
the window you are using, for text wrapping.
- 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.
- 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.
- 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'.
- hyphenate=on
- Hyphenates lines when wrapping breaks occur mid-word.
Default value is 'on'.
- editor=vi
- Specifies which text editor you wish to use for when the
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 "vi".
- 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'.
- locale=en-US.UTF8
- Locale to be used by Taskwarrior for synchronization with
the task server. The default value is currently blank.
MISCELLANEOUS¶
- 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.
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
verbose=on
verbose=blank,header,footnote,label,new-id,affected,edit,special,project
verbose=off
verbose=blank,label,new-id,edit
verbose=nothing
verbose=
- 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.
- 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'.
- indent.annotation=2
- Controls the number of spaces to indent annotations when
shown beneath the description field. The default value is "2".
- indent.report=0
- Controls the indentation of the entire report output.
Default is "0".
- row.padding=0
- Controls left and right padding around each row of the
report output. Default is "0".
- column.padding=0
- Controls padding between columns of the report output.
Default is "1".
- 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 confirmation variable is "no".
- 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. 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 the '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".
- print.empty.columns=no
- May be yes or no, and determines whether columns with no
data for any task are printed. Defaults to 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.
- 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.
- xterm.title=no
- Sets the xterm window title when reports are run. Defaults
to off.
- patterns=on
- Enables or disables pattern support on the command line,
such as /foo/. Defaults to on.
- 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.
- dom=on
- Enables or disables access to taskwarrior internals and
task metadata on the command line. Defaults to on.
- json.array=off
- Determines whether the query command encloses the JSON
output in '[...]' to create a properly-formed JSON array. Defaults to off.
- _forcecolor=no
- Taskwarrior shuts off color automatically when the output
is not sent directly to a TTY. For example, this command:
$ task list > file
$ task rc._forcecolor=yes list > file
- 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 start.active column.
Defaults to *.
- tag.indicator=+
- The character or string to show in the tag.indicator
column. Defaults to +.
- dependency.indicator=D
- The character or string to show in the depends.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, 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.
- 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)
- 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.
- 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.
- 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'.
EXTENSIONS¶
- extensions=on
- Enables the extension system. Defaults to on.
DATES¶
- dateformat=m/d/Y
- dateformat.report=m/d/Y
- dateformat.holiday=YMD
- dateformat.edit=m/d/Y H:N:S
- dateformat.info=m/d/Y H:N:S
- dateformat.annotation=m/d/Y
- report.X.dateformat=m/d/Y
- 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.
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 or 12
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 or 2013
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 minimal-digit week, for example 3 or 37
V two-digit week, for example 03 or 37
h minimal-digit hour, for example 3 or 21
n minimal-digit minutes, for example 5 or 42
s minimal-digit seconds, for example 7 or 47
H two-digit hour, for example 03 or 21
N two-digit minutes, for example 05 or 42
S two-digit seconds, for example 07 or 47
The characters 'v', 'V', 'a' and 'A' can only
be used for formatting printed dates (not to parse them).
The string may also contain other characters
to act as spacers, or formatting. Examples for other values of
dateformat:
Examples for other values of
dateformat.report:
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:
- 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 dates when running the "task calendar" command. The default
value is "list".
- 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".
- calendar.offset.value=-1
- The offset value to apply to the first month in the
calendar report. The default value is "-1".
- 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".
- calendar.legend=yes
- Determines whether the calendar legend is displayed. The
default value is "yes".
JOURNAL ENTRIES¶
- 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:
- journal.time.start.annotation=Started task
- The text of the annotation that is recorded when executing
the start command and having set journal.time.
- journal.time.stop.annotation=Stopped task
- The text of the annotation that is recorded when executing
the stop command and having set journal.time.
- 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".
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: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:
- 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.
DEPENDENCIES¶
- dependency.reminder=on
- Determines whether dependency chain violations generate
reminders.
- dependency.confirmation=yes
- Determines whether dependency chain repair requires
confirmation.
COLOR CONTROLS¶
- color=on
- May be "on" or "off". Determines
whether taskwarrior uses color. When "off", 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 color
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:
color.due.today Task is due today
color.active Task is started, therefore active.
color.scheduled Task is scheduled, therefore ready for work.
color.blocking Task is blocking another in a dependency.
color.blocked Task is blocked by a dependency.
color.overdue Task is overdue (due some time prior to now).
color.due Task is coming due.
color.project.none Task does not have an assigned project.
color.tag.none Task has no tags.
color.tagged Task has at least one tag.
color.recurring Task is recurring.
color.pri.H Task has priority H.
color.pri.M Task has priority M.
color.pri.L Task has priority L.
color.pri.none Task has no priority.
color.completed Task is completed.
color.deleted Task is deleted.
To disable a coloration rule for which there
is a default, set the value to nothing, for example:
color.tagged=
- 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.uda.X=on green
- Colors any taks that has the user defined attribute X.
- color.error=green
- Colors any of the error messages.
- 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.label=
- Colors the report labels. Defaults to not use color.
- 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
Colors the bars on the ghistory report graphs.
Defaults to red, green and yellow bars.
- color.burndown.pending=on red
Colors the bars on the burndown reports
graphs. Defaults to red, green and yellow bars.
- color.undo.before=red
Colors used by the undo command, to indicate
the values both before and after a change that is to be reverted.
- color.sync.added=green
Colors the output of the merge command.
- rule.precedence.color=due.today,active,blocking,blocked,overdue,due,scheduled,keyword.,project.,tag.,uda.,recurring,pri.,tagged,completed,deleted
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.
- color.debug=green
Colors all debug output, if enabled.
URGENCY¶
The urgency calculation uses a polynomial with several terms, each of which has a configurable coefficient. Those coefficients are:- urgency.next.coefficient=15.0
Urgency coefficient for 'next' special
tag
urgency.blocking.coefficient=8.0
Urgency coefficient for blocking tasks
urgency.blocked.coefficient=-5.0
Urgency coefficient for blocked tasks
urgency.due.coefficient=12.0
Urgency coefficient for due dates
urgency.priority.coefficient=6.0
Urgency coefficient for priorities
urgency.waiting.coefficient=-3.0
Urgency coefficient for waiting status
urgency.active.coefficient=4.0
Urgency coefficient for active tasks
urgency.scheduled.coefficient=5.0
Urgency coefficient for scheduled tasks
urgency.project.coefficient=1.0
Urgency coefficient for projects
urgency.tags.coefficient=1.0
Urgency coefficient for tags
urgency.annotations.coefficient=1.0
Urgency coefficient for annotations
urgency.age.coefficient=2.0
Urgency coefficient for the age of tasks
urgency.age.max=365
Maximum age in days. After this number of days
has elapsed, the urgency of a task won't increase any more because of
aging.
urgency.user.tag.<tag>.coefficient=...
Specific tag coefficient.
urgency.user.project.<project>.coefficient=...
Specific project coefficient.
urgency.uda.<name>.coefficient=...
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:
http://tasktools.org/gitweb/gitweb.cgi?p=rfc.git;a=blob_plain;f=rfc31-urgency.txt;hb=HEAD
Presence/absence of UDA data.
SHADOW FILE¶
- 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.
- 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", taskwarrior will
display a message whenever the shadow file is updated by some task
command.
PUSH/PULL/MERGE¶
See the 'man task-synch' page for more details regarding usage.- merge.autopush=yes|no|ask
Determines post-merge behavior regarding
automatic push.
Default merge URI.
Default pull URI.
Default push URI.
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.due=...
- Provides a default due date for the task add
command, if you don't specify one. The default is blank.
- default.command=next
- Provides a default command that is run every time
taskwarrior is invoked with no arguments. For example, if set to:
default.command=project:foo list
then taskwarrior will run the
"project:foo list" command if no command is specified. This means
that by merely typing
$ task
[task project:foo list]
ID Project Pri Description
1 foo H Design foo
2 foo Build foo
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, status, project, priority, priority_long,
entry, start, end, due, countdown, countdown_compact, age, age_compact,
active, tags, depends, description_only, description, recur,
recurrence_indicator, tag_indicator and wait. 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. For example:
report.list.sort=due+,priority-,active-,project+
- 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 dateformat.report
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. Deprecated.
- report.X.limit
- An optional value to a report limiting the number of
displayed tasks in the generated report. Deprecated.
- Taskwarrior comes with a number of predefined reports, which are:
-
- next
- Lists the most important tasks.
- long
- Lists all pending tasks and 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.
- blocked
- Lists all tasks that have dependencies.
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.- uda.<name>.type=string|numeric|date|duration
Defines a UDA called '<name>', of the
specified type.
- uda.<name>.label=<column heading>
Provides a default report label for the UDA
called '<name>'.
- uda.<name>.values=A,B,C
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.
- Example 'estimate' UDA
- This example shows an 'estimate' UDA that stores specific
values for the size of a task.
uda.estimate.type=string
uda.estimate.label=Size Estimate
uda.estimate.values=trivial,small,medium,large,huge
CREDITS & COPYRIGHTS¶
Copyright (C) 2006 - 2013 P. Beckingham, F. Hernandez.SEE ALSO¶
task(1), task-tutorial(5), task-faq(5), task-color(5), task-sync(5)- The official site at
- <http://taskwarrior.org>
- The official code repository at
- <git://tasktools.org/task.git/>
- You can contact the project by emailing
- <support@taskwarrior.org>
REPORTING BUGS¶
- Bugs in taskwarrior may be reported to the issue-tracker at
- <http://taskwarrior.org>
2013-04-07 | task 2.2.0 |