1taskrc(5) User Manuals taskrc(5)
2
6 taskrc - Configuration details for the task(1) command
7
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
17 Taskwarrior obtains its configuration data from a file called .taskrc .
18 This file is normally located in the user's home directory:
19 $HOME/.taskrc
21 The default location can be overridden using the rc: attribute when
23 running task:
24 $ task rc:<directory-path>/.taskrc ...
26 or using the TASKRC environment variable:
28 $ TASKRC=/tmp/.taskrc task ...
30 Additionally, if no ~/.taskrc exists, taskwarrior will check if the
32 XDG_CONFIG_HOME environment variable is defined:
33 $ XDG_CONFIG_HOME=~/.config task ...
35 Individual options can be overridden by using the rc.<name>: attribute
37 when running task:
38 $ task rc.<name>:<value> ...
40 or
42 $ task rc.<name>=<value> ...
44 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 The .taskrc file follows a very simple syntax defining name/value
50 pairs:
51 <name> = <value>
53 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 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 include <file>
66 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 Note that environment variables are also expanded in paths (and any
77 other taskrc variables).
78 # <comment>
80 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 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 <name> =
91 This entry overrides the default value with a blank value.
93
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 $ task config nag "You have more urgent tasks."
101 To delete an entry, use this command:
103 $ task config nag
105 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 $ task config nag ""
111 Taskwarrior will also display all your settings with this command:
113 $ task show
115 and in addition, will also perform a check of all the values in the
117 file, warning you of anything it finds amiss.
118
121 The .taskrc can include other files containing configuration settings
122 by using the include statement:
123 include <path/to/the/configuration/file/to/be/included>
125 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 There are two excellent uses of includes in your .taskrc, shown here:
131 include holidays.en-US.rc
133 include dark-16.theme
134 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
141 These environment variables override defaults, but not command-line ar‐
142 guments.
143 TASKDATA=~/.task
146 This overrides the default path for the Taskwarrior data files.
147 TASKRC=~/.taskrc
150 This overrides the default RC file.
151 This environment variable will be checked if ~/.taskrc doesn't exist
153 XDG_CONFIG_HOME=~/.config
156 If set, taskwarrior will look for a $XDG_CONFIG_HOME/task/taskrc
157 file
158
161 Valid variable names and their default values are:
162 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 Note that you can use the ~ shell meta character, which will be
171 properly expanded.
172 Note that the TASKDATA environment variable overrides this set‐
174 ting.
175 hooks.location=$HOME/.task/hooks
178 This is a path to the hook scripts directory. By default it is
179 ~/.task/hooks.
180 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 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 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 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 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 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 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 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 hyphenate=1
238 Hyphenates lines when wrapping breaks occur mid-word. Default
239 value is '1'.
240 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 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 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 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 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 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 The tokens "affected", "new-id", "new-uuid", "project", "over‐
296 ride" and "recur" imply "footnote".
297 The token "default" implies "header".
299 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 Here are the shortcut equivalents:
305 verbose=on
307 verbose=blank,header,footnote,label,new-id,af‐
308 fected,edit,special,project,sync,filter,override,recur
309 verbose=0
311 verbose=blank,label,new-id,edit
312 verbose=nothing
314 verbose=
315 Those additional comments are sent to the standard error for
317 header, footnote and project. The others are sent to standard
318 output.
319 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 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 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 indent.report=0
341 Controls the indentation of the entire report output. Default is
342 "0".
343 row.padding=0
346 Controls left and right padding around each row of the report
347 output. Default is "0".
348 column.padding=0
351 Controls padding between columns of the report output. Default
352 is "1".
353 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 This is useful for preventing large-scale unintended changes.
361 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 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 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 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 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 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 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 regex=1
408 Controls whether regular expression support is enabled. The de‐
409 fault value is "1".
410 xterm.title=1
413 Sets the xterm window title when reports are run. Defaults to
414 "0".
415 expressions=infix|postfix
418 Sets a preference for infix expressions (1 + 2) or postfix ex‐
419 pressions (1 2 +). Defaults to infix.
420 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 _forcecolor=1
431 Taskwarrior shuts off color automatically when the output is not
432 sent directly to a TTY. For example, this command:
433 $ task list > file
435 will not use any color. To override this, use:
437 $ task rc._forcecolor=yes list > file
439 Defaults to "0".
441 active.indicator=*
444 The character or string to show in the start.active column. De‐
445 faults to *.
446 tag.indicator=+
449 The character or string to show in the tag.indicator column. De‐
450 faults to +.
451 dependency.indicator=D
454 The character or string to show in the depends.indicator column.
455 Defaults to D.
456 uda.<name>.indicator=U
459 The character or string to show in the <uda>.indicator column.
460 Defaults to U.
461 recurrence=1
464 Controls whether recurrence is enabled, and whether recurring
465 tasks continue to generate new task instances. Defaults to "1".
466 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 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 recurrence.indicator=R
481 The character or string to show in the recurrence_indicator col‐
482 umn. Defaults to R.
483 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 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 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 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 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 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 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 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 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 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 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 DATES
560 dateformat=Y-M-D
561 dateformat.report=
563 dateformat.holiday=YMD
565 dateformat.edit=Y-M-D H:N:S
567 dateformat.info=Y-M-D H:N:S
569 dateformat.annotation=
571 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 The default value is the ISO-8601 standard: Y-M-D. The string
583 can contain the characters:
584 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 The characters 'v', 'V', 'a' and 'A' can only be used for for‐
610 matting printed dates (not to parse them).
611 The string may also contain other characters to act as spacers,
613 or formatting. Examples for other values of dateformat:
614 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 Examples for other values of dateformat.report:
620 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 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 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 date.iso=1
640 Enables ISO-8601 date support. The default value is "1".
641 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 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 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 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 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 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 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 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 calendar.legend=1
698 Determines whether the calendar legend is displayed. The default
699 value is "1".
700 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 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 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 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 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 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 holiday.towel.name=Day of the towel
738 holiday.towel.date=20100525
739 For holidays that span a range of days (i.e. vacation), you can use a
741 start date and an end date:
742 holiday.sysadmin.name=System Administrator Appreciation
744 Week
745 holiday.sysadmin.start=20100730
746 holiday.sysadmin.end=20100805
747 Dates are to be entered according to the setting in the datefor‐
749 mat.holiday variable.
750 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 holiday.eastersunday.name=Easter
757 holiday.eastersunday.date=easter
758 Note that the Taskwarrior distribution contains example holiday files
760 that can be included like this:
761 include holidays.en-US.rc
763 DEPENDENCIES
766 dependency.reminder=1
767 Determines whether dependency chain violations generate re‐
768 minders.
769 dependency.confirmation=1
772 Determines whether dependency chain repair requires confirma‐
773 tion.
774 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 fontunderline=1
783 Determines if font underlines or ASCII dashes should be used to
784 underline headers, even when color is enabled.
785 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 task colors
792 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 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 To disable a coloration rule for which there is a default, set
813 the value to nothing, for example:
814 color.tagged=
815 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 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 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 See the task-color(5) man pages for color details.
831 Certain attributes like tags, projects and keywords can have their own
833 coloration rules.
834 color.tag.X=yellow
837 Colors any task that has the tag X.
838 color.project.X=on green
841 Colors any task assigned to project X.
842 color.keyword.X=on blue
845 Colors any task where the description or any annotation contains
846 X.
847 color.uda.X=on green
850 Colors any task that has the user defined attribute X.
851 color.uda.X.VALUE=on green
854 Colors any task that has the user defined attribute X set to
855 VALUE.
856 color.uda.X.none=on green
859 Colors any task that does not have the user defined attribute X.
860 color.error=white on red
863 Colors any of the error messages.
864 color.warning=bold red
867 Colors any of the warning messages.
868 color.header=green
871 Colors any of the messages printed prior to the report output.
872 color.footnote=green
875 Colors any of the messages printed last.
876 color.summary.bar=on green
879 Colors the summary progress bar. Should consist of a background
880 color.
881 color.summary.background=on black
884 Colors the summary progress bar. Should consist of a background
885 color.
886 color.calendar.today=black on cyan
889 Color of today in calendar.
890 color.calendar.due=black on green
893 Color of days with due tasks in calendar.
894 color.calendar.due.today=black on magenta
897 Color of today with due tasks in calendar.
898 color.calendar.overdue=black on red
901 Color of days with overdue tasks in calendar.
902 color.calendar.scheduled=black on orange
905 Color of days with scheduled tasks in calendar.
906 color.calendar.weekend=bright white on black
909 Color of weekend days in calendar.
910 color.calendar.holiday=black on bright yellow
913 Color of holidays in calendar.
914 color.calendar.weeknumber=black on white
917 Color of weeknumbers in calendar.
918 color.label=
921 Colors the report labels. Defaults to not use color.
922 color.label.sort=
925 Colors the report labels for sort columns. Defaults to color.la‐
926 bel.
927 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 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 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 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 color.sync.added=green
958 color.sync.changed=yellow
959 color.sync.rejected=red
960 Colors the output of the sync command.
961 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 color.debug=green
974 Colors all debug output, if enabled.
975 URGENCY
978 The urgency calculation uses a polynomial with several terms, each of
979 which has a configurable coefficient. Those coefficients are:
980 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 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 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 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 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 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 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 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 default.command=project:foo list
1059 then Taskwarrior will run the "project:foo list" command if no
1061 command is specified. This means that by merely typing
1062 $ task
1064 [task project:foo list]
1065 ID Project Pri Description
1067 1 foo H Design foo
1068 2 foo Build foo
1069 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 task overdue
1079 report.X.description
1082 The description for report X when running the "task help" com‐
1083 mand.
1084 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 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 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 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 report.list.sort=due+,priority-,start.active-,project+
1110 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 report.minimal.sort=project+/,description+
1116 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 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 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 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 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 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 Taskwarrior comes with a number of predefined reports, which are:
1149 next Lists the most important tasks.
1152 long Lists all pending tasks and all data, matching the specified
1155 criteria.
1156 list Lists all tasks matching the specified criteria.
1159 ls Short listing of all tasks matching the specified criteria.
1162 minimal
1165 Minimal listing of all tasks matching the specified criteria.
1166 newest Shows the newest tasks.
1169 oldest Shows the oldest tasks.
1172 overdue
1175 Lists overdue tasks matching the specified criteria.
1176 active Lists active tasks matching the specified criteria.
1179 completed
1182 Lists completed tasks matching the specified criteria.
1183 recurring
1186 Lists recurring tasks matching the specified criteria.
1187 waiting
1190 Lists all waiting tasks matching the specified criteria.
1191 all Lists all tasks matching the specified criteria.
1194 blocked
1197 Lists all tasks that have dependencies.
1198 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 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 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 uda.<name>.type=string|numeric|date|duration
1223 Defines a UDA called '<name>', of the specified type.
1224 uda.<name>.label=<column heading>
1227 Provides a default report label for the UDA called '<name>'.
1228 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 Note that the order of the value is important, and denotes the
1237 sort order from highest ('A') to lowest ('C').
1238 Note that a blank value is permitted.
1240 uda.<name>.default=...
1243 Provides a default value for the UDA called '<name>'.
1244 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 uda.estimate.type=string
1251 uda.estimate.label=Size Estimate
1252 uda.estimate.values=huge,large,medium,small,trivial,
1253 Note that the value are sorted
1255 huge > large > medium > small > trivial > ''
1257 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 The current context is stored in the .taskrc file, along with defini‐
1265 tions for all user provided contexts.
1266 context=<name>
1269 Stores the value of the currently active context.
1270 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 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 context.home.rc.default.command=home_report
1287 SYNC
1291 These configuration settings are used to connect and sync tasks with
1292 the task server.
1293 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 taskd.credentials=<organization>/<user>/<key>
1301 User identification for the Taskserver, which includes a private
1302 key.
1303 taskd.certificate=<path>
1306 Specifies the path to the client certificate used for identifi‐
1307 cation with the Taskserver.
1308 taskd.key=<path>
1311 Specifies the path to the client key used for encrypted communi‐
1312 cation with the Taskserver.
1313 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 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 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
1338 Copyright (C) 2006 - 2021 T. Babej, P. Beckingham, F. Hernandez.
1339 This man page was originally written by Federico Hernandez.
1341 Taskwarrior is distributed under the MIT license. See https://www.open‐
1343 source.org/licenses/mit-license.php for more information.
1344
1347 task(1), task-color(5), task-sync(5)
1348 For more information regarding Taskwarrior, see the following:
1350 The official site at
1353 <https://taskwarrior.org>
1354 The official code repository at
1357 <https://github.com/GothenburgBitFactory/taskwarrior>
1358 You can contact the project by emailing
1361 <support@GothenburgBitFactory.org>
1362
1365 Bugs in Taskwarrior may be reported to the issue-tracker at
1366 <https://github.com/GothenburgBitFactory/taskwarrior/issues>
1367task 2.6.2 2016-02-24 taskrc(5)