taskrc(5)

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

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

DESCRIPTION
taskwarrior 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 taskwarrior 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 taskwarrior 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 taskwarrior 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
Taskwarrior 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 ""
Taskwarrior 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 taskwarrior, which define a set of US holidays, and set up a 16-color theme 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 taskwarrior 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 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.

  TERMINAL

curses=on
    Determines whether to use 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. If set to 0, is interpreted as infinite width, therefore with no word-wrapping; useful when redirecting report output to a file for subsequent manipulation.

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.

  MISCELLANEOUS

locale=en-US
    The locale is a combination of ISO 639-1 language code and ISO 3166 country code. If not specified, will assume en-US. If specified, taskwarrior 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.

verbose=yes
    Controls some of the verbosity of taskwarrior.

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 "no", 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".

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. 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.

_forcecolor=no
    Taskwarrior shuts off color automatically when the output is not sent directly to 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 taskwarrior 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, 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)

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'.

  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 taskwarrior formats date values. The precedence order for the configuration variable is report.X.dateformat then dateformat.report then dateformat. While report.X.dateformat only formats the due date in reports, dateformat.report 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 dateformat.report:
        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"
        yMD.HN would do an output as "110124.2342"
        m/d/Y H:N would do an output as "1/24/2011 10:42"
        a D b Y H:N:S would do and output as "Mon 24 Jan 2011 11:19:42"

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.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".

  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:
        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 taskwarrior 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, taskwarrior will only show as many that will fit.

  DEPENDENCIES

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

dependency.confirm=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.
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:
    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.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.
    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.burndown.pending=on red
color.burndown.started=on yellow
color.burndown.done=on green
    Colors the bars on the burndown reports 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.

color.sync.added=green
color.sync.changed=yellow
color.sync.rejected=red
    Colors the output of the merge command.

rule.precedence.color=overdue,tag,project,keyword,active,...
    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 values (color.tag.XXX) is shortened to 'tag', which places all specific tag rules at the same precedence, again for brevity.

  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.

  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=list
    Provides a default command that is run every time taskwarrior is invoked with no arguments. For example, if set to:
        default.command=list project:foo
    then taskwarrior 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, 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.

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

Taskwarrior 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
Taskwarrior was written by P. Beckingham <paul@beckingham.net>.
Copyright (C) 2006 - 2011 P. Beckingham This man page was originally written by Federico Hernandez. Taskwarrior 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), task-sync(5) For more information regarding taskwarrior, 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 taskwarrior may be reported to the issue-tracker at
    <http://taskwarrior.org>