Provided by: task_2.0.0.release-0ubuntu2_i386 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 ignored.

       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

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

              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:

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

              Note that  the  TASKDATA  environment  variable  overrides  this

              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

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

              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

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

              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

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

              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 *

              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

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

              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

              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

              Determines   whether   dependency    chain    repair    requires

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

              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

              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

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

              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

              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

       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"

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

              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


       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