Provided by: task_2.0.0.release-0ubuntu2_amd64 bug


       taskrc - Configuration file for the task(1) command


       task rc:<directory-path>/.taskrc ...
       TASKRC=<directory-path>/.taskrc task ...


       taskwarrior  obtains  its  configuration  data  from  a file called .taskrc . This file is
       normally located in the user's home directory:


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

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

       or usign the TASKRC environment variable:

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

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

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


              $ 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:



                     is one of the variables described below

                     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

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


       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 show

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


       The .taskrc can include other files containing configuration settings by using the include

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


       These environmant variables override defaults and command line arguments.

              The overrides the default path for the taskwarrior data files.

              The overrides the default RC file.


       Valid variable names and their default values are:

              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.

              Note that the TASKDATA environment variable overrides this setting.

              Determines  whether  to  use  file  locking  when  accessing  the and
     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.

              When set to  'yes'  causes  the  program  to  exit  if  the  database  (~/.task  or
     or TASKDATA override) is missing.  Default value is 'no'.

              Determines  whether to use ioctl to establish the size of the window you are using,
              for text wrapping.

              The width of output used when auto-detection 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 handling.

              The height of output used when auto-detection support is not available. Defaults to
              24.   If  set  to  0,  is  interpreted as infinite height.  Useful when redirecting
              charts to a file for subsequent handling.

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

              Hyphenates lines when wrapping breaks occur mid-word.  Default value is 'on'.

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

              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 to be used by Taskwarrior for synchronization with  the  task  server.   The
              default value is currently blank.

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

              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

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

              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.

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

              Controls the number  of  spaces  to  indent  annotations  when  shown  beneath  the
              description field.  The default value is "2".
              Controls the indentation of the entire report output.  Default is "0".

              Controls  left  and right padding around each row of the report output.  Default is

              Controls padding between columns of the report output.  Default is "1".

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

              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.  Default value is: You
              have higher priority tasks.  It is a gentle reminder  that  you  are  contradicting
              your own priority settings.

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

              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

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

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

              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.

              Sets the xterm window title when reports are run.  Defaults to off.

              Enables  or  disables pattern support on the command line, such as /foo/.  Defaults
              to 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.

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

              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

              The task shell command uses this value as a prompt.   You  can  change  it  to  any
              string you like.

              The character or string to show in the column.  Defaults to *.

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

              The character or string to show in the depends.indicator column.  Defaults to +.

              The character or string to show in the recurrence_indicator column.  Defaults to R.

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

              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)

              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.

              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.

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

              Enables the extension system.  Defaults to on.



              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
     then dateformat.  While report.X.dateformat only formats the  due
              date  in  reports, 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

                     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"

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

              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.

              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".
              The report to run when displaying the details of tasks with due date  when  running
              the "task calendar" command.  The default value is "list".

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

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

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

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

              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.
              When  enabled, this setting causes a change log of each task to be displayed by the
              'info' command.  Default value is "on".

       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:

            of the towel
            Administrator Appreciation Day

              Dates  are  to  be  entered  according  to  the  setting  in the

              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:


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

                     include /usr/local/share/doc/task/rc/holidays.en-US.rc

              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.

              Determines whether dependency chain violations generate reminders.

              Determines whether dependency chain repair requires confirmation.

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

              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:

     Task is due today
     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.
              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:

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

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

              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.

              Colors any of the messages printed prior to the report output.

              Colors any of the messages printed last. 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. on cyan
              Color of today in calendar.

       color.calendar.due=black on green
              Color of days with due tasks in calendar. 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. on bright yellow
              Color of holidays in calendar.

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

              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

       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

       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

              Colors used by the undo command, to indicate the values both  before  and  after  a
              change that is to be reverted.

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

              Colors all debug output, if enabled.

       The  urgency  calculation  uses  a  polynomial  with  several  terms,  each of which has a
       configurable coefficient.  Those coefficients are:
              Urgency coefficients for 'next' special tag
              Urgency coefficients for blocking tasks
              Urgency coefficients for blocked tasks
              Urgency coefficients for due dates
              Urgency coefficients for priorities
              Urgency coefficients for waiting status
              Urgency coefficients for active tasks
              Urgency coefficients for projects
              Urgency coefficients for tags
              Urgency coefficients for annotations
              Urgency coefficients for the age of tasks
              Maximum age in days. After this number of days has elapsed, the urgency of  a  task
              won't increase any more because of aging.
              Specific tag coefficient.
              Specific project 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:;a=blob_plain;f=rfc31-urgency.txt;hb=HEAD

              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.

              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.

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

       See the 'man task-synch' page for more details regarding usage.

              Determines post-merge behavior regarding automatic push.

              Default merge URI.

              Default pull URI.

              Default push URI.

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

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

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

              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

       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

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

              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.

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

              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:


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

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

              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.

              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 in its default
              configuration file. These reports are:

       next   Lists the most important tasks.

       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 listing of all tasks matching the specified criteria.

       newest Shows the newest tasks.

       oldest Shows the oldest tasks.

              Lists overdue tasks matching the specified criteria.

       active Lists active tasks matching the specified criteria.

              Lists completed tasks matching the specified criteria.

              Lists recurring tasks matching the specified criteria.

              Lists all waiting tasks matching the specified criteria.

       all    Lists all tasks matching the specified criteria.

              List all tasks that have dependencies.


       Copyright (C) 2006 - 2012 P. Beckingham, F. Hernandez.

       This man page was originally written by Federico Hernandez.

       Taskwarrior       is       distributed      under      the      MIT      license.      See for more information.


       task(1), task-tutorial(5), task-faq(5), task-color(5), task-sync(5)

       For more information regarding taskwarrior, see the following:

       The official site at

       The official code repository at

       You can contact the project by emailing


       Bugs in taskwarrior may be reported to the issue-tracker at