1taskrc(5)                        User Manuals                        taskrc(5)
2
3
4

NAME

6       taskrc - Configuration details for the task(1) command
7
8

SYNOPSIS

10       $HOME/.taskrc
11       task rc:<directory-path>/.taskrc ...
12       TASKRC=<directory-path>/.taskrc task ...
13       XDG_CONFIG_HOME=<directory-path>/task/taskrc task ...
14
15

DESCRIPTION

17       Taskwarrior obtains its configuration data from a file called .taskrc .
18       This file is normally located in the user's home directory:
19
20              $HOME/.taskrc
21
22       The default location can be overridden using  the  rc:  attribute  when
23       running task:
24
25              $ task rc:<directory-path>/.taskrc ...
26
27       or using the TASKRC environment variable:
28
29              $ TASKRC=/tmp/.taskrc task ...
30
31       Additionally,  if  no  ~/.taskrc  exists, taskwarrior will check if the
32       XDG_CONFIG_HOME environment variable is defined:
33
34              $ XDG_CONFIG_HOME=~/.config task ...
35
36       Individual options can be overridden by using the rc.<name>:  attribute
37       when running task:
38
39              $ task rc.<name>:<value> ...
40
41       or
42
43              $ task rc.<name>=<value> ...
44
45       If  Taskwarrior  is  run without an existing configuration file it will
46       ask if it should create a default, sample .taskrc file  in  the  user's
47       home directory.
48
49       The  .taskrc  file  follows  a  very  simple syntax defining name/value
50       pairs:
51
52              <name> = <value>
53
54       There may be whitespace around <name>, '=' and <value>, and it  is  ig‐
55       nored.   Whitespace  within  the <value> is left intact.  Whitespace is
56       not permitted in comma-separated lists.  The entry must be on a  single
57       line,  no continuations.  Values support UTF8 as well as JSON encoding,
58       such as \uNNNN.
59
60       Note that Taskwarrior is flexible about the values  used  to  represent
61       Boolean  items. You can use "1" to enable, anything else is interpreted
62       as disabled.  The values "on", "yes", "y" and "true" are currently sup‐
63       ported but deprecated.
64
65              include <file>
66
67       There may be whitespace around 'include' and <file>. The file may be an
68       absolute or relative path, and the special character '~' is expanded to
69       mean  $HOME. If relative path is specified, the it will be evaluated as
70       relative with respect to the following directories (listed in order  of
71       precedence): 1. the current working directory 2. the directory contain‐
72       ing the taskrc file 3. the  directories  set  by  the  package  manager
73       (which usually contain
74          pre-defined themes)
75
76       Note  that  environment  variables  are also expanded in paths (and any
77       other taskrc variables).
78
79              # <comment>
80
81       A comment consists of the character '#', and extends from  the  '#'  to
82       the  end  of  the  line. There is no way to comment a multi-line block.
83       There may be blank lines.
84
85       Almost every value has a default setting, and an empty .taskrc file  is
86       one  that  makes use of every default. The contents of the .taskrc file
87       therefore represent overrides of the default values. To  remove  a  de‐
88       fault value completely there must be an entry like this:
89
90              <name> =
91
92       This entry overrides the default value with a blank value.
93
94

EDITING

96       You  can edit your .taskrc file by hand if you wish, or you can use the
97       'config' command. To permanently set a value in your .taskrc file,  use
98       this command:
99
100              $ task config nag "You have more urgent tasks."
101
102       To delete an entry, use this command:
103
104              $ task config nag
105
106       Taskwarrior  will then use the default value. To explicitly set a value
107       to blank, and therefore avoid using the default value,  use  this  com‐
108       mand:
109
110              $ task config nag ""
111
112       Taskwarrior will also display all your settings with this command:
113
114              $ task show
115
116       and  in  addition,  will  also perform a check of all the values in the
117       file, warning you of anything it finds amiss.
118
119

NESTING CONFIGURATION FILES

121       The .taskrc can include other files containing  configuration  settings
122       by using the include statement:
123
124              include <path/to/the/configuration/file/to/be/included>
125
126       By using include files you can divide your main configuration file into
127       several ones containing just the relevant configuration data like  col‐
128       ors, etc.
129
130       There are two excellent uses of includes in your .taskrc, shown here:
131
132              include holidays.en-US.rc
133              include dark-16.theme
134
135       This includes two standard files that are distributed with Taskwarrior,
136       which define a set of US holidays, and set up a 16-color theme to  use,
137       to color the reports and calendar.
138
139

ENVIRONMENT VARIABLES

141       These environment variables override defaults, but not command-line ar‐
142       guments.
143
144
145       TASKDATA=~/.task
146              This overrides the default path for the Taskwarrior data files.
147
148
149       TASKRC=~/.taskrc
150              This overrides the default RC file.
151
152       This environment variable will be checked if ~/.taskrc doesn't exist
153
154
155       XDG_CONFIG_HOME=~/.config
156              If set, taskwarrior will look for a $XDG_CONFIG_HOME/task/taskrc
157              file
158
159

CONFIGURATION VARIABLES

161       Valid variable names and their default values are:
162
163
164   FILES
165       data.location=$HOME/.task
166              This  is  a path to the directory containing all the Taskwarrior
167              files. By default, it is set up  to  be  ~/.task,  for  example:
168              /home/paul/.task
169
170              Note  that you can use the ~ shell meta character, which will be
171              properly expanded.
172
173              Note that the TASKDATA environment variable overrides this  set‐
174              ting.
175
176
177       hooks.location=$HOME/.task/hooks
178              This  is  a path to the hook scripts directory. By default it is
179              ~/.task/hooks.
180
181
182       locking=1
183              Determines whether to use file locking when accessing the  pend‐
184              ing.data  and  completed.data  files.  Defaults  to "1". Solaris
185              users who store the data files on an NFS mount may need  to  set
186              locking  to "0". Note that there is danger in setting this value
187              to "0" - another program (or another instance of task) may write
188              to the task.pending file at the same time.
189
190
191       gc=1   Can  be  used to temporarily suspend garbage collection (gc), so
192              that task IDs don't change. Note that this should be used in the
193              form of a command line override (task rc.gc=0 ...), and not per‐
194              manently used in the .taskrc file, as this significantly affects
195              performance in the long term.
196
197
198       hooks=1
199              This  master  control switch enables hook script processing. The
200              default value is '1', but certain  extensions  and  environments
201              may need to disable hooks.
202
203
204       exit.on.missing.db=0
205              When  set  to  '1'  causes  the  program to exit if the database
206              (~/.task or rc.data.location or TASKDATA override)  is  missing.
207              Default value is '0'.
208
209
210   TERMINAL
211       detection=1
212              Determines  whether  to  use  ioctl to establish the size of the
213              window you are using, for text wrapping.
214
215
216       defaultwidth=80
217              The width of output used  when  auto-detection  support  is  not
218              available. Defaults to 80. If set to 0, it is interpreted as in‐
219              finite width, therefore with no word-wrapping;  this  is  useful
220              when  redirecting  report  output  to a file for subsequent han‐
221              dling.
222
223
224       defaultheight=24
225              The height of output used when  auto-detection  support  is  not
226              available. Defaults to 24. If set to 0, it is interpreted as in‐
227              finite height. This is useful when redirecting charts to a  file
228              for subsequent handling.
229
230
231       avoidlastcolumn=0
232              Causes  the  width  of  the terminal minus one to be used as the
233              full width. This avoids placing color codes in the  last  column
234              which can cause problems for Cygwin users. Default value is '0'.
235
236
237       hyphenate=1
238              Hyphenates  lines  when  wrapping breaks occur mid-word. Default
239              value is '1'.
240
241
242       editor=vi
243              Specifies which text editor you wish to use for  when  the  task
244              edit  <ID> command is used. Taskwarrior will first look for this
245              configuration variable. If found, it is used. Otherwise it  will
246              look for the $VISUAL or $EDITOR environment variables, before it
247              defaults to using "vi".
248
249
250       reserved.lines=1
251              This is the number of lines reserved at the bottom of the screen
252              for  the shell prompt. This is only referenced when 'limit:page'
253              is used.
254
255
256   MISCELLANEOUS
257       verbose=1|0|nothing|list...
258              When set to "1" (the default), helpful explanatory comments  are
259              added  to all output from Taskwarrior. Setting this to "0" means
260              that you would see regular output.
261
262              The special value "nothing" can be used  to  eliminate  all  op‐
263              tional  output,  which  results in only the formatted data being
264              shown, with nothing else. This output is most readily parsed and
265              used by shell scripts.
266
267              Alternatively,  you  can  specify a comma-separated list of ver‐
268              bosity tokens that control specific  occasions  when  output  is
269              generated. This list may contain:
270
271                  blank      Inserts extra blank lines in output, for clarity
272                  header      Messages  that appear before report output (this
273              includes .taskrc/.task overrides and the "[task next]" message)
274                  footnote   Messages that appear after report output  (mostly
275              status messages and change descriptions)
276                  label      Column labels on tabular reports
277                  new-id      Provides  feedback on any new task with IDs (and
278              UUIDs for new tasks with ID 0, such as new completed tasks).
279                  new-uuid   Provides feedback on any  new  task  with  UUIDs.
280              Overrides new-id. Useful for automation.
281                  affected   Reports 'N tasks affected' and similar
282                  edit       Used the verbose template for the 'edit' command
283                  special    Feedback when applying special tags
284                  project    Feedback about project status changes
285                  sync       Feedback about sync
286                  filter     Shows the filter used in the command
287                  context    Show the current context. Displayed in footnote.
288                  override   Notification when configuration options are over‐
289              ridden
290                  recur      Notification when a new recurring  task  instance
291              is created
292                  default     Notifications about taskwarrior choosing to per‐
293              form a default action.
294
295              The tokens "affected", "new-id", "new-uuid",  "project",  "over‐
296              ride" and "recur" imply "footnote".
297
298              The token "default" implies "header".
299
300              Note  that the "1" setting is equivalent to all the tokens being
301              specified, and the "nothing" setting is equivalent  to  none  of
302              the tokens being specified.
303
304              Here are the shortcut equivalents:
305
306                  verbose=on
307                  verbose=blank,header,footnote,label,new-id,af‐
308              fected,edit,special,project,sync,filter,override,recur
309
310                  verbose=0
311                  verbose=blank,label,new-id,edit
312
313                  verbose=nothing
314                  verbose=
315
316              Those additional comments are sent to  the  standard  error  for
317              header,  footnote  and  project. The others are sent to standard
318              output.
319
320
321       confirmation=1
322              May be "1" or "0", and determines whether Taskwarrior  will  ask
323              for  confirmation  before deleting a task or performing the undo
324              command. The default value is "1".  Consider  leaving  this  en‐
325              abled, for safety.
326
327
328       allow.empty.filter=1
329              An  empty  filter combined with a write command is potentially a
330              way to modify all tasks by mistake, and when this  is  detected,
331              confirmation  is required.  Setting this to '0' means that it is
332              an error to use a write command with no filter.
333
334
335       indent.annotation=2
336              Controls the number of spaces to indent annotations  when  shown
337              beneath the description field. The default value is "2".
338
339
340       indent.report=0
341              Controls the indentation of the entire report output. Default is
342              "0".
343
344
345       row.padding=0
346              Controls left and right padding around each row  of  the  report
347              output. Default is "0".
348
349
350       column.padding=0
351              Controls  padding  between columns of the report output. Default
352              is "1".
353
354
355       bulk=3 Is a number, defaulting to 3. When this  number  or  greater  of
356              tasks are modified in a single command, confirmation will be re‐
357              quired, regardless of the value of  confirmation  variable.  The
358              special value bulk=0 is treated as an infinity.
359
360              This is useful for preventing large-scale unintended changes.
361
362
363       nag=You have more urgent tasks.
364              This  may be a string of text, or blank.  It is used as a prompt
365              when a task is started of completed, when there are other  tasks
366              with  a higher urgency.  Default value is: 'You have more urgent
367              tasks'.  It is a gentle reminder that you are contradicting your
368              own urgency settings.
369
370
371       list.all.projects=0
372              May be "1" or "0", and determines whether the 'projects' command
373              lists all the project names you have used, or just the ones used
374              in active tasks. The default value is "0".
375
376
377       summary.all.projects=0
378              If set to "1", shows all projects in the summary report, even if
379              there are no pending tasks.  The default value is "0".
380
381
382       complete.all.tags=1
383              May be "1" or "0", and determines  whether  the  tab  completion
384              scripts  consider  all  the tag names you have used, or just the
385              ones used in active tasks. The default value is "0".
386
387
388       list.all.tags=1
389              May be "1" or "0", and determines  whether  the  'tags'  command
390              lists  all the tag names you have used, or just the ones used in
391              active tasks. The default value is "0".
392
393
394       print.empty.columns=1
395              May be "1" or "0", and determines whether columns with  no  data
396              for any task are printed. Defaults to "0".
397
398
399       search.case.sensitive=1
400              May  be  "1"  or  "0", and determines whether keyword lookup and
401              substitutions on the description and annotations are done  in  a
402              case  sensitive way. Defaults to "1" on most platforms. Defaults
403              to "0" on Cygwin due to older regex library problems with  case-
404              insensitivity.
405
406
407       regex=1
408              Controls  whether regular expression support is enabled. The de‐
409              fault value is "1".
410
411
412       xterm.title=1
413              Sets the xterm window title when reports are  run.  Defaults  to
414              "0".
415
416
417       expressions=infix|postfix
418              Sets  a  preference for infix expressions (1 + 2) or postfix ex‐
419              pressions (1 2 +).  Defaults to infix.
420
421
422       json.array=1
423              Determines whether the export command encloses the  JSON  output
424              in  '[...]' and adds ',' after each exported task object to cre‐
425              ate a properly-formed JSON  array.   With  json.array=0,  export
426              writes  raw  JSON  objects to STDOUT, one per line.  Defaults to
427              "1".
428
429
430       _forcecolor=1
431              Taskwarrior shuts off color automatically when the output is not
432              sent directly to a TTY. For example, this command:
433
434                     $ task list > file
435
436              will not use any color. To override this, use:
437
438                     $ task rc._forcecolor=yes list > file
439
440       Defaults to "0".
441
442
443       active.indicator=*
444              The  character or string to show in the start.active column. De‐
445              faults to *.
446
447
448       tag.indicator=+
449              The character or string to show in the tag.indicator column. De‐
450              faults to +.
451
452
453       dependency.indicator=D
454              The character or string to show in the depends.indicator column.
455              Defaults to D.
456
457
458       uda.<name>.indicator=U
459              The character or string to show in the  <uda>.indicator  column.
460              Defaults to U.
461
462
463       recurrence=1
464              Controls  whether  recurrence  is enabled, and whether recurring
465              tasks continue to generate new task instances. Defaults to "1".
466
467              If you are syncing multiple clients, then it is advised that you
468              set 'recurrence=1' on your primary client, and 'recurrence=0' on
469              ALL other clients. This is a workaround for a duplication bug.
470
471
472       recurrence.confirmation=prompt
473              Controls whether changes to recurring tasks propagates to  other
474              child tasks with or without confirmation. A value of 'yes' means
475              propagate changes without confirmation. A value of 'no' means do
476              not propagate changes and don't ask for confirmation. A value of
477              'prompt' prompts you every time. Defaults to 'prompt'.
478
479
480       recurrence.indicator=R
481              The character or string to show in the recurrence_indicator col‐
482              umn. Defaults to R.
483
484
485       recurrence.limit=1
486              The number of future recurring tasks to show. Defaults to 1. For
487              example, if a weekly recurring task is added with a due date  of
488              tomorrow,  and  recurrence.limit is set to 2, then a report will
489              list 2 pending recurring tasks, one for tomorrow, and one for  a
490              week from tomorrow.
491
492
493       undo.style=side
494              When  the  'undo'  command is run, Taskwarrior presents a before
495              and after comparison of the data. This  can  be  in  either  the
496              'side'  style, which compares values side-by-side in a table, or
497              'diff' style, which uses a format similar to the 'diff' command.
498
499
500       abbreviation.minimum=2
501              Minimum length of any abbreviated command/value. This means that
502              "ve",  "ver", "vers", "versi", "versio" will all equate to "ver‐
503              sion", but "v" will not.  Default is 2.
504
505
506       debug=0
507              Taskwarrior has a debug mode that causes diagnostic output to be
508              displayed.   Typically  this is not something anyone would want,
509              but when reporting a bug, debug output can  be  useful.  It  can
510              also  help explain how the command line is being parsed, but the
511              information is displayed in a developer-friendly,  not  a  user-
512              friendly way.
513
514              Turning   debug   on   automatically   sets  debug.hooks=1,  de‐
515              bug.parser=1 and debug.tls=2 if they do  not  already  have  as‐
516              signed values. Defaults to "0".
517
518
519       debug.hooks=0
520              Controls  the hook system diagnostic level. Level 0 means no di‐
521              agnostics.  Level 1 shows hook calls. Level 2  also  shows  exit
522              status and I/O.
523
524
525       debug.parser=0
526              Controls  the parser diagnostic level. Level 0 shows no diagnos‐
527              tics.  Level 1 shows the final parse tree.  Level  2  shows  the
528              parse  tree from all phases of the parse.  Level 3 shows expres‐
529              sion evaluation details.
530
531
532       debug.tls=0
533              Controls the GnuTLS  diagnostic  level.  For  'sync'  debugging.
534              Level 0 means no diagnostics. Level 9 is the highest. Level 2 is
535              a good setting for debugging.
536
537
538       obfuscate=0
539              When set to '1', will replace all report text with 'xxx'.   This
540              is  useful  for  sharing  report output in bug reports.  Default
541              value is '0'.
542
543
544       alias.rm=delete
545              Taskwarrior supports command aliases. This alias provides an al‐
546              ternate name (rm) for the delete command. You can use aliases to
547              provide alternate names for any of the  commands.  Several  com‐
548              mands  you  may use are actually aliases - the 'history' report,
549              for example, or 'export'.
550
551
552       burndown.cumulative=1
553              May be "1" or "0", and controls the behaviour  of  the  burndown
554              command.  When  set to 1, it sums up all completed tasks, other‐
555              wise they only get plotted in the interval where  the  task  was
556              completed. Defaults to 1.
557
558
559   DATES
560       dateformat=Y-M-D
561
562       dateformat.report=
563
564       dateformat.holiday=YMD
565
566       dateformat.edit=Y-M-D H:N:S
567
568       dateformat.info=Y-M-D H:N:S
569
570       dateformat.annotation=
571
572       report.X.dateformat=Y-M-D
573              This is a string of characters that defines how Taskwarrior for‐
574              mats date values.  The precedence order  for  the  configuration
575              variable  is  report.X.dateformat  then  dateformat.report  then
576              dateformat for formatting the due dates in reports.  If both re‐
577              port.X.dateformat  and  dateformat.report are not set then date‐
578              format will be applied to the date. Entered dates as well as all
579              other  displayed  dates  in  reports  are formatted according to
580              dateformat.
581
582              The default value is the ISO-8601 standard:  Y-M-D.  The  string
583              can contain the characters:
584
585                     m  minimal-digit month,    for example 1 or 12
586                     d  minimal-digit day,      for example 1 or 30
587                     y  two-digit year,         for example 09 or 12
588                     D  two-digit day,          for example 01 or 30
589                     M  two-digit month,        for example 01 or 12
590                     Y  four-digit year,        for example 2009 or 2015
591                     a  short name of weekday,  for example Mon or Wed
592                     A   long name of weekday,   for example Monday or Wednes‐
593                     day
594                     b  short name of month,    for example Jan or Aug
595                     B  long name of month,     for example January or August
596                     v  minimal-digit week,     for example 3 or 37
597                     V  two-digit week,         for example 03 or 37
598                     h  minimal-digit hour,     for example 3 or 21
599                     n  minimal-digit minutes,  for example 5 or 42
600                     s  minimal-digit seconds,  for example 7 or 47
601                     H  two-digit hour,         for example 03 or 21
602                     N  two-digit minutes,      for example 05 or 42
603                     S  two-digit seconds,      for example 07 or 47
604                     J  three-digit Julian day, for example 023 or 365
605                     j  Julian day,             for example 23 or 365
606                     w  Week day,               for example 0  for  Monday,  5
607                     for Friday
608
609              The  characters  'v', 'V', 'a' and 'A' can only be used for for‐
610              matting printed dates (not to parse them).
611
612              The string may also contain other characters to act as  spacers,
613              or formatting.  Examples for other values of dateformat:
614
615                     d/m/Y  would use for input and output 24/7/2009
616                     yMD    would use for input and output 090724
617                     M-D-Y  would use for input and output 07-24-2009
618
619              Examples for other values of dateformat.report:
620
621                     a D b Y (V)   would emit "Fri 24 Jul 2009 (30)"
622                     A, B D, Y     would emit "Friday, July 24, 2009"
623                     wV a Y-M-D    would emit "w30 Fri 2009-07-24"
624                     yMD.HN        would emit "110124.2342"
625                     m/d/Y H:N     would emit "1/24/2011 10:42"
626                     a D b Y H:N:S would emit "Mon 24 Jan 2011 11:19:42"
627
628              Undefined  fields  are  put to their minimal valid values (1 for
629              month and day and 0 for hour, minutes and seconds) when there is
630              at least one more global date field that is set. Otherwise, they
631              are set to the corresponding values of "now". For example:
632
633                     8/1/2013  with m/d/Y   implies August 1, 2013 at midnight
634                     (inferred)
635                     8/1  20:40 with m/d H:N implies August 1, 2013 (inferred)
636                     at 20:40
637
638
639       date.iso=1
640              Enables ISO-8601 date support.  The default value is "1".
641
642
643   CALENDAR
644       weekstart=Sunday
645              Determines the day a week starts. Valid  values  are  Sunday  or
646              Monday only. The default value is "Sunday".
647
648
649       displayweeknumber=1
650              Determines  if  week  numbers are displayed when using the "task
651              calendar" command.  The week number is dependent on  the  day  a
652              week starts. The default value is "1".
653
654
655       due=7  This  is  the  number of days into the future that define when a
656              task is considered due, and is colored accordingly. The  default
657              value is 7.
658
659
660       calendar.details=sparse
661              If  set  to  "full" running "task calendar" will display the de‐
662              tails of tasks with due dates that fall into  the  calendar  pe‐
663              riod.  The  corresponding days will be color-coded in the calen‐
664              dar. If set to "sparse" only  the  corresponding  days  will  be
665              color  coded and no details will be displayed. The displaying of
666              due dates with details is turned off by setting the variable  to
667              "none". The default value is "sparse".
668
669
670       calendar.details.report=list
671              The  report to run when displaying the details of tasks with due
672              dates when running the  "task  calendar"  command.  The  default
673              value is "list".
674
675
676       calendar.offset=0
677              If  "1"  the  first  month in the calendar report is effectively
678              changed by the offset value specified in  calendar.offset.value.
679              It defaults to "0".
680
681
682       calendar.offset.value=-1
683              The offset value to apply to the first month in the calendar re‐
684              port. The default value is "-1".
685
686
687       calendar.holidays=none
688              If set to full running "task calendar" will display holidays  in
689              the  calendar by color-coding the corresponding days. A detailed
690              list with the dates and names of the holidays is also shown.  If
691              set  to  sparse  only the days are color-coded and no details on
692              the holidays will be displayed. The displaying  of  holidays  is
693              turned off by setting the variable to none. The default value is
694              "none".
695
696
697       calendar.legend=1
698              Determines whether the calendar legend is displayed. The default
699              value is "1".
700
701
702       calendar.monthsperline=N
703              Determines  how  many months the "task calendar" command renders
704              across the screen. Defaults to however many will  fit.  If  more
705              months  than  will fit are specified, Taskwarrior will only show
706              as many that will fit.
707
708
709   JOURNAL ENTRIES
710       journal.time=0
711              May be "1" or "0", and determines whether the 'start' and 'stop'
712              commands  should  record  an annotation when being executed. The
713              default value is "0". The text of the corresponding  annotations
714              is controlled by:
715
716
717       journal.time.start.annotation=Started task
718              The  text  of the annotation that is recorded when executing the
719              start command and having set journal.time.
720
721
722       journal.time.stop.annotation=Stopped task
723              The text of the annotation that is recorded when  executing  the
724              stop command and having set journal.time.
725
726
727       journal.info=1
728              When  enabled,  this setting causes a change log of each task to
729              be displayed by the 'info' command. Default value is "1".
730
731
732   HOLIDAYS
733       Holidays are entered either directly in the .taskrc file or via an  in‐
734       clude  file  that  is specified in .taskrc. For single-day holidays the
735       name and the date is required to be given:
736
737                     holiday.towel.name=Day of the towel
738                     holiday.towel.date=20100525
739
740       For holidays that span a range of days (i.e. vacation), you can  use  a
741       start date and an end date:
742
743                     holiday.sysadmin.name=System  Administrator  Appreciation
744                     Week
745                     holiday.sysadmin.start=20100730
746                     holiday.sysadmin.end=20100805
747
748              Dates are to be entered according to the setting in the datefor‐
749              mat.holiday variable.
750
751              The  following  holidays are computed automatically: Good Friday
752              (goodfriday), Easter (easter), Easter Monday (eastermonday), As‐
753              cension  (ascension),  Pentecost (pentecost). The date for these
754              holidays is the given keyword:
755
756                     holiday.eastersunday.name=Easter
757                     holiday.eastersunday.date=easter
758
759       Note that the Taskwarrior distribution contains example  holiday  files
760       that can be included like this:
761
762                     include holidays.en-US.rc
763
764
765   DEPENDENCIES
766       dependency.reminder=1
767              Determines  whether  dependency  chain  violations  generate re‐
768              minders.
769
770
771       dependency.confirmation=1
772              Determines whether dependency chain  repair  requires  confirma‐
773              tion.
774
775
776   COLOR CONTROLS
777       color=1
778              May  be  "1"  or "0". Determines whether Taskwarrior uses color.
779              When "0", will use dashes (-----) to underline column headings.
780
781
782       fontunderline=1
783              Determines if font underlines or ASCII dashes should be used  to
784              underline headers, even when color is enabled.
785
786       Taskwarrior has a number of coloration rules. They correspond to a par‐
787       ticular attribute of a task, such as it being due, or being active, and
788       specifies  the automatic coloring of that task. A list of valid colors,
789       depending on your terminal, can be obtained by running the command:
790
791              task colors
792
793              Note that no default values are listed here - the  defaults  now
794              correspond  to  the  dark-256.theme  (Linux)  and  dark-16.theme
795              (other) theme values.  The coloration rules are as follows:
796
797              color.due.today Task is due today
798              color.active Task is started, therefore active.
799              color.scheduled Task is scheduled, therefore ready for work.
800              color.until Task has an expiration date.
801              color.blocking Task is blocking another in a dependency.
802              color.blocked Task is blocked by a dependency.
803              color.overdue Task is overdue (due some time prior to now).
804              color.due Task is coming due.
805              color.project.none Task does not have an assigned project.
806              color.tag.none Task has no tags.
807              color.tagged Task has at least one tag.
808              color.recurring Task is recurring.
809              color.completed Task is completed.
810              color.deleted Task is deleted.
811
812              To disable a coloration rule for which there is a  default,  set
813              the value to nothing, for example:
814                     color.tagged=
815
816              By  default, colors produced by rules blend. This has the advan‐
817              tage of conveying additional information, by producing  combina‐
818              tions that are not used by any particular rule directly.
819
820              However,  color  blending  can produce highlighting combinations
821              which are not desired. In such cases, use the  following  option
822              to disable this behaviour:
823
824
825       rule.color.merge=1
826              Can be "1" or "0". When "0", disables merging of colors produced
827              by different color rules. Use if your color scheme produces  un‐
828              pleasing foreground and background combinations.
829
830              See the task-color(5) man pages for color details.
831
832       Certain  attributes like tags, projects and keywords can have their own
833       coloration rules.
834
835
836       color.tag.X=yellow
837              Colors any task that has the tag X.
838
839
840       color.project.X=on green
841              Colors any task assigned to project X.
842
843
844       color.keyword.X=on blue
845              Colors any task where the description or any annotation contains
846              X.
847
848
849       color.uda.X=on green
850              Colors any task that has the user defined attribute X.
851
852
853       color.uda.X.VALUE=on green
854              Colors  any  task  that  has the user defined attribute X set to
855              VALUE.
856
857
858       color.uda.X.none=on green
859              Colors any task that does not have the user defined attribute X.
860
861
862       color.error=white on red
863              Colors any of the error messages.
864
865
866       color.warning=bold red
867              Colors any of the warning messages.
868
869
870       color.header=green
871              Colors any of the messages printed prior to the report output.
872
873
874       color.footnote=green
875              Colors any of the messages printed last.
876
877
878       color.summary.bar=on green
879              Colors the summary progress bar. Should consist of a  background
880              color.
881
882
883       color.summary.background=on black
884              Colors  the summary progress bar. Should consist of a background
885              color.
886
887
888       color.calendar.today=black on cyan
889              Color of today in calendar.
890
891
892       color.calendar.due=black on green
893              Color of days with due tasks in calendar.
894
895
896       color.calendar.due.today=black on magenta
897              Color of today with due tasks in calendar.
898
899
900       color.calendar.overdue=black on red
901              Color of days with overdue tasks in calendar.
902
903
904       color.calendar.scheduled=black on orange
905              Color of days with scheduled tasks in calendar.
906
907
908       color.calendar.weekend=bright white on black
909              Color of weekend days in calendar.
910
911
912       color.calendar.holiday=black on bright yellow
913              Color of holidays in calendar.
914
915
916       color.calendar.weeknumber=black on white
917              Color of weeknumbers in calendar.
918
919
920       color.label=
921              Colors the report labels. Defaults to not use color.
922
923
924       color.label.sort=
925              Colors the report labels for sort columns. Defaults to color.la‐
926              bel.
927
928
929       color.alternate=on rgb253
930              Color  of alternate tasks.  This is to apply a specific color to
931              every other task in a report, which can make it easier  to  vis‐
932              ually  separate  tasks. This is especially useful when tasks are
933              displayed over multiple lines due to long descriptions or  anno‐
934              tations.
935
936
937       color.history.add=on red
938       color.history.done=on green
939       color.history.delete=on yellow
940              Colors  the bars on the ghistory report graphs. Defaults to red,
941              green and yellow bars.
942
943
944       color.burndown.pending=on red
945       color.burndown.started=on yellow
946       color.burndown.done=on green
947              Colors the bars on the burndown reports graphs. Defaults to red,
948              green and yellow bars.
949
950
951       color.undo.before=red
952       color.undo.after=green
953              Colors used by the undo command, to indicate the values both be‐
954              fore and after a change that is to be reverted.
955
956
957       color.sync.added=green
958       color.sync.changed=yellow
959       color.sync.rejected=red
960              Colors the output of the sync command.
961
962
963       rule.precedence.color=due.today,active,blocking,blocked,overdue,due,
964              scheduled,keyword.,project.,tag.,uda.,recurring,     tagged,com‐
965              pleted,deleted
966              This  setting  specifies the precedence of the color rules, from
967              highest to lowest. Note that the prefix 'color.' is omitted (for
968              brevity),  and that any wildcard value (color.tag.XXX) is short‐
969              ened to 'tag.', which places all specific tag rules at the  same
970              precedence, again for brevity.
971
972
973       color.debug=green
974              Colors all debug output, if enabled.
975
976
977   URGENCY
978       The  urgency  calculation uses a polynomial with several terms, each of
979       which has a configurable coefficient. Those coefficients are:
980
981
982       urgency.blocking.coefficient=8.0
983              Urgency coefficient for blocking tasks
984       urgency.blocked.coefficient=-5.0
985              Urgency coefficient for blocked tasks
986       urgency.due.coefficient=12.0
987              Urgency coefficient for due dates
988       urgency.waiting.coefficient=-3.0
989              Urgency coefficient for waiting status
990       urgency.active.coefficient=4.0
991              Urgency coefficient for active tasks
992       urgency.scheduled.coefficient=5.0
993              Urgency coefficient for scheduled tasks
994       urgency.project.coefficient=1.0
995              Urgency coefficient for projects
996       urgency.tags.coefficient=1.0
997              Urgency coefficient for tags
998       urgency.annotations.coefficient=1.0
999              Urgency coefficient for annotations
1000       urgency.age.coefficient=2.0
1001              Urgency coefficient for the age of tasks
1002       urgency.age.max=365
1003              Maximum age in days. After this number of days has elapsed,  the
1004              urgency of a task won't increase any more because of aging.
1005       urgency.user.tag.<tag>.coefficient=...
1006              Specific tag coefficient.
1007       urgency.user.tag.next.coefficient=15.0
1008              Urgency coefficient for tag 'next'.
1009       urgency.user.project.<project>.coefficient=...
1010              Specific project coefficient.
1011       urgency.user.keyword.<keyword>.coefficient=...
1012              Specific description keyword coefficient.
1013       urgency.uda.<name>.coefficient=...
1014              Presence/absence of UDA data.
1015       urgency.uda.<name>.<value>.coefficient=...
1016              Specific value of UDA data.
1017
1018       The  coefficients  reflect the relative importance of the various terms
1019       in the urgency calculation. These are default values, and may be  modi‐
1020       fied  to  suit your preferences, but it is important that you carefully
1021       consider any modifications.
1022
1023       urgency.inherit=0
1024              Not actually a coefficient. When enabled, blocking tasks inherit
1025              the highest urgency value found in the tasks they block. This is
1026              done recursively.  It is recommended to set urgency.blocking.co‐
1027              efficient  and  urgency.blocked.coefficient  to 0.0 in order for
1028              this setting to be the most useful.
1029
1030
1031   DEFAULTS
1032       default.project=foo
1033              Provides a default project name for the task add command, if you
1034              don't specify one. The default is blank.
1035
1036
1037       default.due=...
1038              Provides  a  default  due  date for the task add command, if you
1039              don't specify one. You can use a date, or a duration value which
1040              is assumed to be relative to 'now'. The default is blank.
1041
1042
1043       default.scheduled=...
1044              Provides  a  default scheduled date for the task add command, if
1045              you don't specify one. You can use a date, or a  duration  value
1046              which is assumed to be relative to 'now'. The default is blank.
1047
1048
1049       uda.<name>.default=...
1050              Provides  default  values for UDA fields when using the task add
1051              command, if you don't specify values. The default is blank.
1052
1053
1054       default.command=next
1055              Provides a default command that is run every time Taskwarrior is
1056              invoked with no arguments. For example, if set to:
1057
1058                     default.command=project:foo list
1059
1060              then  Taskwarrior  will run the "project:foo list" command if no
1061              command is specified. This means that by merely typing
1062
1063                     $ task
1064                     [task project:foo list]
1065
1066                     ID Project Pri Description
1067                      1 foo     H   Design foo
1068                      2 foo         Build foo
1069
1070
1071   REPORTS
1072       The reports can be customized  by  using  the  following  configuration
1073       variables.   The output columns, their labels and the sort order can be
1074       set using the corresponding variables for each report. Each report name
1075       is used as a "command" name. For example
1076
1077
1078       task overdue
1079
1080
1081       report.X.description
1082              The  description  for report X when running the "task help" com‐
1083              mand.
1084
1085
1086       report.X.columns
1087              This is a comma-separated list of columns and formatting  speci‐
1088              fiers. See the command 'task columns' for a full list of options
1089              and examples.
1090
1091
1092       report.X.context
1093              A boolean value representing whether the given report should re‐
1094              spect  (apply) the currently active context. See CONTEXT section
1095              for details about context.  Defaults to 1.
1096
1097
1098       report.X.labels
1099              The labels for each column that will be used when generating re‐
1100              port X. The labels are a comma separated list.
1101
1102
1103       report.X.sort
1104              The  sort order of the tasks in the generated report X. The sort
1105              order is specified by using the column ids post-fixed by  a  "+"
1106              for ascending sort order or a "-" for descending sort order. The
1107              sort IDs are separated by commas.  For example:
1108
1109                  report.list.sort=due+,priority-,start.active-,project+
1110
1111              Additionally, after the "+" or "-", there can be a  solidus  "/"
1112              which  indicates  that  there are breaks after the column values
1113              change. For example:
1114
1115                  report.minimal.sort=project+/,description+
1116
1117              This sort order now specifies that there is a listing break  be‐
1118              tween  each  project.  A  listing  break is simply a blank line,
1119              which provides a visual grouping.
1120
1121              A special sort value of "none" indicates that no sorting is  re‐
1122              quired,  and  tasks  will  be presented in the order (if any) in
1123              which they are selected.
1124
1125
1126       report.X.filter
1127              This adds a filter to the report X so that only  tasks  matching
1128              the filter criteria are displayed in the generated report.
1129
1130              There is a special case for 'report.timesheet.filter', which may
1131              be specified even though the 'timesheet' report is not very cus‐
1132              tomizable.
1133
1134
1135       report.X.dateformat
1136              This  adds a dateformat to the report X that will be used by the
1137              "due date" column. If it is not set then  dateformat.report  and
1138              dateformat will be used in this order. See the DATES section for
1139              details on the sequence placeholders.
1140
1141
1142       report.X.annotations
1143              This adds the possibility to control the output  of  annotations
1144              for  a  task in a report. Deprecated. Use the description column
1145              with a format (e.g., description.count) instead.
1146
1147
1148       Taskwarrior comes with a number of predefined reports, which are:
1149
1150
1151       next   Lists the most important tasks.
1152
1153
1154       long   Lists all pending tasks and all  data,  matching  the  specified
1155              criteria.
1156
1157
1158       list   Lists all tasks matching the specified criteria.
1159
1160
1161       ls     Short listing of all tasks matching the specified criteria.
1162
1163
1164       minimal
1165              Minimal listing of all tasks matching the specified criteria.
1166
1167
1168       newest Shows the newest tasks.
1169
1170
1171       oldest Shows the oldest tasks.
1172
1173
1174       overdue
1175              Lists overdue tasks matching the specified criteria.
1176
1177
1178       active Lists active tasks matching the specified criteria.
1179
1180
1181       completed
1182              Lists completed tasks matching the specified criteria.
1183
1184
1185       recurring
1186              Lists recurring tasks matching the specified criteria.
1187
1188
1189       waiting
1190              Lists all waiting tasks matching the specified criteria.
1191
1192
1193       all    Lists all tasks matching the specified criteria.
1194
1195
1196       blocked
1197              Lists all tasks that have dependencies.
1198
1199
1200   USER DEFINED ATTRIBUTES
1201       User  defined  attributes (UDAs) are an extension mechanism that allows
1202       you to define new attributes for Taskwarrior to store and display.  One
1203       such  example  is  an  'estimate' attribute that could be used to store
1204       time estimates associated with a task. This 'estimate' attribute is not
1205       built  in  to Taskwarrior, but with a few simple configuration settings
1206       you can instruct Taskwarrior to store this item, and provide access  to
1207       it for custom reports and filters.
1208
1209       This allows you to augment Taskwarrior to accommodate your workflow, or
1210       bend the rules and use Taskwarrior to store and synch data that is  not
1211       necessarily task-related.
1212
1213       One  important  restriction is that because this is an open system that
1214       allows the definition of any new attribute, Taskwarrior  cannot  under‐
1215       stand  the  meaning of that attribute. So while Taskwarrior will faith‐
1216       fully store, modify, report, sort and filter your UDA, it does not  un‐
1217       derstand  anything about it. For example if you define a UDA named 'es‐
1218       timate', Taskwarrior will not know that this  value  is  weeks,  hours,
1219       minutes, money, or some other resource count.
1220
1221
1222       uda.<name>.type=string|numeric|date|duration
1223              Defines a UDA called '<name>', of the specified type.
1224
1225
1226       uda.<name>.label=<column heading>
1227              Provides a default report label for the UDA called '<name>'.
1228
1229
1230       uda.<name>.values=A,B,C
1231              For  type  'string'  UDAs  only, this provides a comma-separated
1232              list of acceptable values. In this example, the '<name>' UDA may
1233              only  contain  values  'A', 'B', or 'C', but may also contain no
1234              value.
1235
1236              Note that the order of the value is important, and  denotes  the
1237              sort order from highest ('A') to lowest ('C').
1238
1239              Note that a blank value is permitted.
1240
1241
1242       uda.<name>.default=...
1243              Provides a default value for the UDA called '<name>'.
1244
1245
1246       Example 'estimate' UDA
1247              This example shows an 'estimate' UDA that stores specific values
1248              for the size of a task.  Note the blank value after 'trivial'.
1249
1250              uda.estimate.type=string
1251              uda.estimate.label=Size Estimate
1252              uda.estimate.values=huge,large,medium,small,trivial,
1253
1254              Note that the value are sorted
1255
1256                  huge > large > medium > small > trivial > ''
1257
1258
1259   CONTEXT
1260       Context setting is a mechanism which allows the user to set a permanent
1261       filter,  thus  avoiding the need to specify one filter repeatedly. More
1262       details on usage can be found in the task(1) man page.
1263
1264       The current context is stored in the .taskrc file, along  with  defini‐
1265       tions for all user provided contexts.
1266
1267
1268       context=<name>
1269              Stores the value of the currently active context.
1270
1271
1272       context.<name>.read=<filter>
1273       context.<name>.write=<modifications>
1274              Stores the definition of the read or write context with the name
1275              <name>. Read context is the default filter applied when the con‐
1276              text  is active. The write context are the default modifications
1277              applied to newly added tasks when the context is active.
1278
1279
1280       context.<name>.rc.<key>=<value>
1281              The rc type allows to override any configuration  parameter  for
1282              the current context, e.g. if the default command for the context
1283              home should be changed to home_report, the  following  statement
1284              could be added:
1285
1286              context.home.rc.default.command=home_report
1287
1288
1289
1290   SYNC
1291       These  configuration  settings  are used to connect and sync tasks with
1292       the task server.
1293
1294
1295       taskd.server=<host>:<port>
1296              Specifies the hostname and port of the Taskserver. Hostname  may
1297              be an IPv4 or IPv6 address, or domain. Port is an integer.
1298
1299
1300       taskd.credentials=<organization>/<user>/<key>
1301              User identification for the Taskserver, which includes a private
1302              key.
1303
1304
1305       taskd.certificate=<path>
1306              Specifies the path to the client certificate used for  identifi‐
1307              cation with the Taskserver.
1308
1309
1310       taskd.key=<path>
1311              Specifies the path to the client key used for encrypted communi‐
1312              cation with the Taskserver.
1313
1314
1315       taskd.ca=<path>
1316              Specifies the path to the CA certificate in the event that  your
1317              Taskserver is using a self-signed certificate. Optional.
1318
1319
1320       taskd.trust=strict|ignore hostname|allow all
1321              This settings allows you to override the trust level when server
1322              certificates are validated. With "allow all",  the  server  cer‐
1323              tificate  is  trusted automatically. With "ignore hostname", the
1324              server certificate is verified but the hostname is ignored. With
1325              "strict",  the  server  certificate  is  verified.   Default  is
1326              "strict", which requires full validation.
1327
1328
1329       taskd.ciphers=NORMAL
1330              Override of the cipher selection. The set of ciphers used by TLS
1331              may  be controlled by both server and client. There must be some
1332              overlap between client and server supported ciphers, or communi‐
1333              cation cannot occur.  Default is "NORMAL". See GnuTLS documenta‐
1334              tion for full details.
1335
1336

CREDITS & COPYRIGHTS

1338       Copyright (C) 2006 - 2021 T. Babej, P. Beckingham, F. Hernandez.
1339
1340       This man page was originally written by Federico Hernandez.
1341
1342       Taskwarrior is distributed under the MIT license. See https://www.open
1343       source.org/licenses/mit-license.php for more information.
1344
1345

SEE ALSO

1347       task(1), task-color(5), task-sync(5)
1348
1349       For more information regarding Taskwarrior, see the following:
1350
1351
1352       The official site at
1353              <https://taskwarrior.org>
1354
1355
1356       The official code repository at
1357              <https://github.com/GothenburgBitFactory/taskwarrior>
1358
1359
1360       You can contact the project by emailing
1361              <support@GothenburgBitFactory.org>
1362
1363

REPORTING BUGS

1365       Bugs in Taskwarrior may be reported to the issue-tracker at
1366              <https://github.com/GothenburgBitFactory/taskwarrior/issues>
1367
1368
1369
1370task 2.6.2                        2016-02-24                         taskrc(5)
Impressum