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
16 Taskwarrior obtains its configuration data from a file called .taskrc .
17 This file is normally located in the user's home directory:
18 $HOME/.taskrc
20 The default location can be overridden using the rc: attribute when
22 running task:
23 $ task rc:<directory-path>/.taskrc ...
25 or using the TASKRC environment variable:
27 $ TASKRC=/tmp/.taskrc task ...
29 Individual options can be overridden by using the rc.<name>: attribute
31 when running task:
32 $ task rc.<name>:<value> ...
34 or
36 $ task rc.<name>=<value> ...
38 If Taskwarrior is run without an existing configuration file it will
40 ask if it should create a default, sample .taskrc file in the user's
41 home directory.
42 The .taskrc file follows a very simple syntax defining name/value
44 pairs:
45 <name> = <value>
47 There may be whitespace around <name>, '=' and <value>, and it is ig‐
49 nored. Whitespace within the <value> is left intact. Whitespace is
50 not permitted in comma-separated lists. The entry must be on a single
51 line, no continuations. Values support UTF8 as well as JSON encoding,
52 such as \uNNNN.
53 Note that Taskwarrior is flexible about the values used to represent
55 Boolean items. You can use "1" to enable, anything else is interpreted
56 as disabled. The values "on", "yes", "y" and "true" are currently sup‐
57 ported but deprecated.
58 include <file>
60 There may be whitespace around 'include' and <file>. The file may be an
62 absolute or relative path, and the special character '~' is expanded to
63 mean $HOME. The entry must be on a single line, no continuations.
64 # <comment>
66 A comment consists of the character '#', and extends from the '#' to
68 the end of the line. There is no way to comment a multi-line block.
69 There may be blank lines.
70 Almost every value has a default setting, and an empty .taskrc file is
72 one that makes use of every default. The contents of the .taskrc file
73 therefore represent overrides of the default values. To remove a de‐
74 fault value completely there must be an entry like this:
75 <name> =
77 This entry overrides the default value with a blank value.
79
82 You can edit your .taskrc file by hand if you wish, or you can use the
83 'config' command. To permanently set a value in your .taskrc file, use
84 this command:
85 $ task config nag "You have more urgent tasks."
87 To delete an entry, use this command:
89 $ task config nag
91 Taskwarrior will then use the default value. To explicitly set a value
93 to blank, and therefore avoid using the default value, use this com‐
94 mand:
95 $ task config nag ""
97 Taskwarrior will also display all your settings with this command:
99 $ task show
101 and in addition, will also perform a check of all the values in the
103 file, warning you of anything it finds amiss.
104
107 The .taskrc can include other files containing configuration settings
108 by using the include statement:
109 include <path/to/the/configuration/file/to/be/included>
111 By using include files you can divide your main configuration file into
113 several ones containing just the relevant configuration data like col‐
114 ors, etc.
115 There are two excellent uses of includes in your .taskrc, shown here:
117 include /usr/share/task/holidays.en-US.rc
119 include /usr/share/task/dark-16.theme
120 This includes two standard files that are distributed with Taskwarrior,
122 which define a set of US holidays, and set up a 16-color theme to use,
123 to color the reports and calendar.
124
127 These environment variables override defaults and command line argu‐
128 ments.
129 TASKDATA=~/.task
132 This overrides the default path for the Taskwarrior data files.
133 TASKRC=~/.taskrc
136 This overrides the default RC file.
137
140 Valid variable names and their default values are:
141 FILES
144 data.location=$HOME/.task
145 This is a path to the directory containing all the Taskwarrior
146 files. By default, it is set up to be ~/.task, for example:
147 /home/paul/.task
148 Note that you can use the ~ shell meta character, which will be
150 properly expanded.
151 Note that the TASKDATA environment variable overrides this set‐
153 ting.
154 hooks.location=$HOME/.task/hooks
157 This is a path to the hook scripts directory. By default it is
158 ~/.task/hooks.
159 locking=1
162 Determines whether to use file locking when accessing the pend‐
163 ing.data and completed.data files. Defaults to "1". Solaris
164 users who store the data files on an NFS mount may need to set
165 locking to "0". Note that there is danger in setting this value
166 to "0" - another program (or another instance of task) may write
167 to the task.pending file at the same time.
168 gc=1 Can be used to temporarily suspend garbage collection (gc), so
171 that task IDs don't change. Note that this should be used in the
172 form of a command line override (task rc.gc=0 ...), and not per‐
173 manently used in the .taskrc file, as this significantly affects
174 performance in the long term.
175 hooks=1
178 This master control switch enables hook script processing. The
179 default value is '1', but certain extensions and environments
180 may need to disable hooks.
181 exit.on.missing.db=0
184 When set to '1' causes the program to exit if the database
185 (~/.task or rc.data.location or TASKDATA override) is missing.
186 Default value is '0'.
187 TERMINAL
190 detection=1
191 Determines whether to use ioctl to establish the size of the
192 window you are using, for text wrapping.
193 defaultwidth=80
196 The width of output used when auto-detection support is not
197 available. Defaults to 80. If set to 0, it is interpreted as in‐
198 finite width, therefore with no word-wrapping; this is useful
199 when redirecting report output to a file for subsequent han‐
200 dling.
201 defaultheight=24
204 The height of output used when auto-detection support is not
205 available. Defaults to 24. If set to 0, it is interpreted as in‐
206 finite height. This is useful when redirecting charts to a file
207 for subsequent handling.
208 avoidlastcolumn=0
211 Causes the width of the terminal minus one to be used as the
212 full width. This avoids placing color codes in the last column
213 which can cause problems for Cygwin users. Default value is '0'.
214 hyphenate=1
217 Hyphenates lines when wrapping breaks occur mid-word. Default
218 value is '1'.
219 editor=vi
222 Specifies which text editor you wish to use for when the task
223 edit <ID> command is used. Taskwarrior will first look for this
224 configuration variable. If found, it is used. Otherwise it will
225 look for the $VISUAL or $EDITOR environment variables, before it
226 defaults to using "vi".
227 reserved.lines=1
230 This is the number of lines reserved at the bottom of the screen
231 for the shell prompt. This is only referenced when 'limit:page'
232 is used.
233 MISCELLANEOUS
236 verbose=1|0|nothing|list...
237 When set to "1" (the default), helpful explanatory comments are
238 added to all output from Taskwarrior. Setting this to "0" means
239 that you would see regular output.
240 The special value "nothing" can be used to eliminate all op‐
242 tional output, which results in only the formatted data being
243 shown, with nothing else. This output is most readily parsed and
244 used by shell scripts.
245 Alternatively, you can specify a comma-separated list of ver‐
247 bosity tokens that control specific occasions when output is
248 generated. This list may contain:
249 blank Inserts extra blank lines in output, for clarity
251 header Messages that appear before report output (this
252 includes .taskrc/.task overrides and the "[task next]" message)
253 footnote Messages that appear after report output (mostly
254 status messages and change descriptions)
255 label Column labels on tabular reports
256 new-id Provides feedback of any new task IDs
257 new-uuid Provides feedback of any new task UUIDs. Depre‐
258 cated, to be
259 merged with new-id.
260 affected Reports 'N tasks affected' and similar
261 edit Used the verbose template for the 'edit' command
262 special Feedback when applying special tags
263 project Feedback about project status changes
264 sync Feedback about sync
265 filter Shows the filter used in the command
266 unwait Notification when a task leaves the 'waiting'
267 state
268 override Notification when configuration options are over‐
269 ridden
270 recur Notification when a new recurring task instance
271 is created
272 "affected", "new-id", "new-uuid", "project", "unwait", "over‐
274 ride" and "recur" imply "footnote".
275 Note that the "1" setting is equivalent to all the tokens being
277 specified, and the "nothing" setting is equivalent to none of
278 the tokens being specified.
279 Here are the shortcut equivalents:
281 verbose=on
283 verbose=blank,header,footnote,label,new-id,af‐
284 fected,edit,special,project,sync,filter,unwait,override
285 verbose=0
287 verbose=blank,label,new-id,edit
288 verbose=nothing
290 verbose=
291 Those additional comments are sent to the standard error for
293 header, footnote and project. The others are sent to standard
294 output.
295 confirmation=1
298 May be "1" or "0", and determines whether Taskwarrior will ask
299 for confirmation before deleting a task or performing the undo
300 command. The default value is "1". Consider leaving this en‐
301 abled, for safety.
302 allow.empty.filter=1
305 An empty filter combined with a write command is potentially a
306 way to modify all tasks by mistake, and when this is detected,
307 confirmation is required. Setting this to '0' means that it is
308 an error to use a write command with no filter.
309 indent.annotation=2
312 Controls the number of spaces to indent annotations when shown
313 beneath the description field. The default value is "2".
314 indent.report=0
317 Controls the indentation of the entire report output. Default is
318 "0".
319 row.padding=0
322 Controls left and right padding around each row of the report
323 output. Default is "0".
324 column.padding=0
327 Controls padding between columns of the report output. Default
328 is "1".
329 bulk=3 Is a number, defaulting to 3. When this number or greater of
332 tasks are modified in a single command, confirmation will be re‐
333 quired, regardless of the value of confirmation variable. The
334 special value bulk=0 is treated as an infinity.
335 This is useful for preventing large-scale unintended changes.
337 nag=You have more urgent tasks.
340 This may be a string of text, or blank. It is used as a prompt
341 when a task is started of completed, when there are other tasks
342 with a higher urgency. Default value is: 'You have more urgent
343 tasks'. It is a gentle reminder that you are contradicting your
344 own urgency settings.
345 list.all.projects=0
348 May be "1" or "0", and determines whether the 'projects' command
349 lists all the project names you have used, or just the ones used
350 in active tasks. The default value is "0".
351 summary.all.projects=0
354 If set to "1", shows all projects in the summary report, even if
355 there are no pending tasks. The default value is "0".
356 complete.all.tags=1
359 May be "1" or "0", and determines whether the tab completion
360 scripts consider all the tag names you have used, or just the
361 ones used in active tasks. The default value is "0".
362 list.all.tags=1
365 May be "1" or "0", and determines whether the 'tags' command
366 lists all the tag names you have used, or just the ones used in
367 active tasks. The default value is "0".
368 print.empty.columns=1
371 May be "1" or "0", and determines whether columns with no data
372 for any task are printed. Defaults to "0".
373 search.case.sensitive=1
376 May be "1" or "0", and determines whether keyword lookup and
377 substitutions on the description and annotations are done in a
378 case sensitive way. Defaults to "1" on most platforms. Defaults
379 to "0" on Cygwin due to older regex library problems with case-
380 insensitivity.
381 regex=1
384 Controls whether regular expression support is enabled. The de‐
385 fault value is "1".
386 xterm.title=1
389 Sets the xterm window title when reports are run. Defaults to
390 "0".
391 expressions=infix|postfix
394 Sets a preference for infix expressions (1 + 2) or postfix ex‐
395 pressions (1 2 +). Defaults to infix.
396 json.array=1
399 Determines whether the export command encloses the JSON output
400 in '[...]' and adds ',' after each exported task object to cre‐
401 ate a properly-formed JSON array. With json.array=0, export
402 writes raw JSON objects to STDOUT, one per line. Defaults to
403 "1".
404 json.depends.array=1
407 Determines whether the export command encodes dependencies as an
408 array of string UUIDs, or one comma-separated string. Defaults
409 to "1".
410 _forcecolor=1
413 Taskwarrior shuts off color automatically when the output is not
414 sent directly to a TTY. For example, this command:
415 $ task list > file
417 will not use any color. To override this, use:
419 $ task rc._forcecolor=yes list > file
421 Defaults to "0".
423 active.indicator=*
426 The character or string to show in the start.active column. De‐
427 faults to *.
428 tag.indicator=+
431 The character or string to show in the tag.indicator column. De‐
432 faults to +.
433 dependency.indicator=D
436 The character or string to show in the depends.indicator column.
437 Defaults to +.
438 uda.<name>.indicator=U
441 The character or string to show in the <uda>.indicator column.
442 Defaults to U.
443 recurrence=1
446 Controls whether recurrence is enabled, and whether recurring
447 tasks continue to generate new task instances. Defaults to "1".
448 If you are syncing multiple clients, then it is advised that you
450 set 'recurrence=1' on your primary client, and 'recurrence=0' on
451 ALL other clients. This is a workaround for a duplication bug.
452 recurrence.confirmation=prompt
455 Controls whether changes to recurring tasks propagates to other
456 child tasks with or without confirmation. A value of 'yes' means
457 propagate changes without confirmation. A value of 'no' means do
458 not propagate changes and don't ask for confirmation. A value of
459 'prompt' prompts you every time. Defaults to 'prompt'.
460 recurrence.indicator=R
463 The character or string to show in the recurrence_indicator col‐
464 umn. Defaults to R.
465 recurrence.limit=1
468 The number of future recurring tasks to show. Defaults to 1. For
469 example, if a weekly recurring task is added with a due date of
470 tomorrow, and recurrence.limit is set to 2, then a report will
471 list 2 pending recurring tasks, one for tomorrow, and one for a
472 week from tomorrow.
473 undo.style=side
476 When the 'undo' command is run, Taskwarrior presents a before
477 and after comparison of the data. This can be in either the
478 'side' style, which compares values side-by-side in a table, or
479 'diff' style, which uses a format similar to the 'diff' command.
480 abbreviation.minimum=2
483 Minimum length of any abbreviated command/value. This means that
484 "ve", "ver", "vers", "versi", "versio" will all equate to "ver‐
485 sion", but "v" will not. Default is 2.
486 debug=0
489 Taskwarrior has a debug mode that causes diagnostic output to be
490 displayed. Typically this is not something anyone would want,
491 but when reporting a bug, debug output can be useful. It can
492 also help explain how the command line is being parsed, but the
493 information is displayed in a developer-friendly, not a user-
494 friendly way.
495 Turning debug on automatically sets debug.hooks=1, de‐
497 bug.parser=1 and debug.tls=2 if they do not already have as‐
498 signed values. Defaults to "0".
499 debug.hooks=0
502 Controls the hook system diagnostic level. Level 0 means no di‐
503 agnostics. Level 1 shows hook calls. Level 2 also shows exit
504 status and I/O.
505 debug.parser=0
508 Controls the parser diagnostic level. Level 0 shows no diagnos‐
509 tics. Level 1 shows the final parse tree. Level 2 shows the
510 parse tree from all phases of the parse. Level 3 shows expres‐
511 sion evaluation details.
512 debug.tls=0
515 Controls the GnuTLS diagnostic level. For 'sync' debugging.
516 Level 0 means no diagnostics. Level 9 is the highest. Level 2 is
517 a good setting for debugging.
518 obfuscate=1
521 When set to '1', will replace all report text with 'xxx'. This
522 is useful for sharing report output in bug reports. Default
523 value is '0'.
524 alias.rm=delete
527 Taskwarrior supports command aliases. This alias provides an al‐
528 ternate name (rm) for the delete command. You can use aliases to
529 provide alternate names for any of the commands. Several com‐
530 mands you may use are actually aliases - the 'history' report,
531 for example, or 'export'.
532 DATES
535 dateformat=Y-M-D
536 dateformat.report=
538 dateformat.holiday=YMD
540 dateformat.edit=Y-M-D H:N:S
542 dateformat.info=Y-M-D H:N:S
544 dateformat.annotation=
546 report.X.dateformat=Y-M-D
548 This is a string of characters that defines how Taskwarrior for‐
549 mats date values. The precedence order for the configuration
550 variable is report.X.dateformat then dateformat.report then
551 dateformat for formatting the due dates in reports. If both re‐
552 port.X.dateformat and dateformat.report are not set then date‐
553 format will be applied to the date. Entered dates as well as all
554 other displayed dates in reports are formatted according to
555 dateformat.
556 The default value is the ISO-8601 standard: Y-M-D. The string
558 can contain the characters:
559 m minimal-digit month, for example 1 or 12
561 d minimal-digit day, for example 1 or 30
562 y two-digit year, for example 09 or 12
563 D two-digit day, for example 01 or 30
564 M two-digit month, for example 01 or 12
565 Y four-digit year, for example 2009 or 2015
566 a short name of weekday, for example Mon or Wed
567 A long name of weekday, for example Monday or Wednes‐
568 day
569 b short name of month, for example Jan or Aug
570 B long name of month, for example January or August
571 v minimal-digit week, for example 3 or 37
572 V two-digit week, for example 03 or 37
573 h minimal-digit hour, for example 3 or 21
574 n minimal-digit minutes, for example 5 or 42
575 s minimal-digit seconds, for example 7 or 47
576 H two-digit hour, for example 03 or 21
577 N two-digit minutes, for example 05 or 42
578 S two-digit seconds, for example 07 or 47
579 J three-digit Julian day, for example 023 or 365
580 j Julian day, for example 23 or 365
581 w Week day, for example 0 for Monday, 5
582 for Friday
583 The characters 'v', 'V', 'a' and 'A' can only be used for for‐
585 matting printed dates (not to parse them).
586 The string may also contain other characters to act as spacers,
588 or formatting. Examples for other values of dateformat:
589 d/m/Y would use for input and output 24/7/2009
591 yMD would use for input and output 090724
592 M-D-Y would use for input and output 07-24-2009
593 Examples for other values of dateformat.report:
595 a D b Y (V) would emit "Fri 24 Jul 2009 (30)"
597 A, B D, Y would emit "Friday, July 24, 2009"
598 wV a Y-M-D would emit "w30 Fri 2009-07-24"
599 yMD.HN would emit "110124.2342"
600 m/d/Y H:N would emit "1/24/2011 10:42"
601 a D b Y H:N:S would emit "Mon 24 Jan 2011 11:19:42"
602 Undefined fields are put to their minimal valid values (1 for
604 month and day and 0 for hour, minutes and seconds) when there is
605 at least one more global date field that is set. Otherwise, they
606 are set to the corresponding values of "now". For example:
607 8/1/2013 with m/d/Y implies August 1, 2013 at midnight
609 (inferred)
610 8/1 20:40 with m/d H:N implies August 1, 2013 (inferred)
611 at 20:40
612 date.iso=1
615 Enables ISO-8601 date support. The default value is "1".
616 weekstart=Sunday
619 Determines the day a week starts. Valid values are Sunday or
620 Monday only. The default value is "Sunday".
621 displayweeknumber=1
624 Determines if week numbers are displayed when using the "task
625 calendar" command. The week number is dependent on the day a
626 week starts. The default value is "1".
627 due=7 This is the number of days into the future that define when a
630 task is considered due, and is colored accordingly. The default
631 value is 7.
632 calendar.details=sparse
635 If set to "full" running "task calendar" will display the de‐
636 tails of tasks with due dates that fall into the calendar pe‐
637 riod. The corresponding days will be color-coded in the calen‐
638 dar. If set to "sparse" only the corresponding days will be
639 color coded and no details will be displayed. The displaying of
640 due dates with details is turned off by setting the variable to
641 "none". The default value is "sparse".
642 calendar.details.report=list
645 The report to run when displaying the details of tasks with due
646 dates when running the "task calendar" command. The default
647 value is "list".
648 calendar.offset=0
651 If "1" the first month in the calendar report is effectively
652 changed by the offset value specified in calendar.offset.value.
653 It defaults to "0".
654 calendar.offset.value=-1
657 The offset value to apply to the first month in the calendar re‐
658 port. The default value is "-1".
659 calendar.holidays=full
662 If set to full running "task calendar" will display holidays in
663 the calendar by color-coding the corresponding days. A detailed
664 list with the dates and names of the holidays is also shown. If
665 set to sparse only the days are color-coded and no details on
666 the holidays will be displayed. The displaying of holidays is
667 turned off by setting the variable to none. The default value is
668 "none".
669 calendar.legend=1
672 Determines whether the calendar legend is displayed. The default
673 value is "1".
674 JOURNAL ENTRIES
677 journal.time=0
678 May be "1" or "0", and determines whether the 'start' and 'stop'
679 commands should record an annotation when being executed. The
680 default value is "0". The text of the corresponding annotations
681 is controlled by:
682 journal.time.start.annotation=Started task
685 The text of the annotation that is recorded when executing the
686 start command and having set journal.time.
687 journal.time.stop.annotation=Stopped task
690 The text of the annotation that is recorded when executing the
691 stop command and having set journal.time.
692 journal.info=1
695 When enabled, this setting causes a change log of each task to
696 be displayed by the 'info' command. Default value is "1".
697 HOLIDAYS
700 Holidays are entered either directly in the .taskrc file or via an in‐
701 clude file that is specified in .taskrc. For each holiday the name and
702 the date is required to be given:
703 holiday.towel.name=Day of the towel
705 holiday.towel.date=20100525
706 holiday.sysadmin.name=System Administrator Appreciation
707 Day
708 holiday.sysadmin.date=20100730
709 Dates are to be entered according to the setting in the datefor‐
711 mat.holiday variable.
712 The following holidays are computed automatically: Good Friday
714 (goodfriday), Easter (easter), Easter Monday (eastermonday), As‐
715 cension (ascension), Pentecost (pentecost). The date for these
716 holidays is the given keyword:
717 holiday.eastersunday.name=Easter
719 holiday.eastersunday.date=easter
720 Note that the Taskwarrior distribution contains example holiday files
722 that can be included like this:
723 include /usr/share/task/holidays.en-US.rc
725 monthsperline=3
728 Determines how many months the "task calendar" command renders
729 across the screen. Defaults to however many will fit. If more
730 months than will fit are specified, Taskwarrior will only show
731 as many that will fit.
732 DEPENDENCIES
735 dependency.reminder=1
736 Determines whether dependency chain violations generate re‐
737 minders.
738 dependency.confirmation=1
741 Determines whether dependency chain repair requires confirma‐
742 tion.
743 COLOR CONTROLS
746 color=1
747 May be "1" or "0". Determines whether Taskwarrior uses color.
748 When "0", will use dashes (-----) to underline column headings.
749 fontunderline=1
752 Determines if font underlines or ASCII dashes should be used to
753 underline headers, even when color is enabled.
754 Taskwarrior has a number of coloration rules. They correspond to a par‐
756 ticular attribute of a task, such as it being due, or being active, and
757 specifies the automatic coloring of that task. A list of valid colors,
758 depending on your terminal, can be obtained by running the command:
759 task colors
761 Note that no default values are listed here - the defaults now
763 correspond to the dark-256.theme (Linux) and dark-16.theme
764 (other) theme values. The coloration rules are as follows:
765 color.due.today Task is due today
767 color.active Task is started, therefore active.
768 color.scheduled Task is scheduled, therefore ready for work.
769 color.until Task has an expiration date.
770 color.blocking Task is blocking another in a dependency.
771 color.blocked Task is blocked by a dependency.
772 color.overdue Task is overdue (due some time prior to now).
773 color.due Task is coming due.
774 color.project.none Task does not have an assigned project.
775 color.tag.none Task has no tags.
776 color.tagged Task has at least one tag.
777 color.recurring Task is recurring.
778 color.completed Task is completed.
779 color.deleted Task is deleted.
780 To disable a coloration rule for which there is a default, set
782 the value to nothing, for example:
783 color.tagged=
784 By default, colors produced by rules blend. This has the advan‐
786 tage of conveying additional information, by producing combina‐
787 tions that are not used by any particular rule directly.
788 However, color blending can produce highlighting combinations
790 which are not desired. In such cases, use the following option
791 to disable this behaviour:
792 rule.color.merge=1
795 Can be "1" or "0". When "0", disables merging of colors produced
796 by different color rules. Use if your color scheme produces un‐
797 pleasing foreground and background combinations.
798 See the task-color(5) man pages for color details.
800 Certain attributes like tags, projects and keywords can have their own
802 coloration rules.
803 color.tag.X=yellow
806 Colors any task that has the tag X.
807 color.project.X=on green
810 Colors any task assigned to project X.
811 color.keyword.X=on blue
814 Colors any task where the description or any annotation contains
815 X.
816 color.uda.X=on green
819 Colors any task that has the user defined attribute X.
820 color.uda.X.VALUE=on green
823 Colors any task that has the user defined attribute X set to
824 VALUE.
825 color.uda.X.none=on green
828 Colors any task that does not have the user defined attribute X.
829 color.error=white on red
832 Colors any of the error messages.
833 color.warning=bold red
836 Colors any of the warning messages.
837 color.header=green
840 Colors any of the messages printed prior to the report output.
841 color.footnote=green
844 Colors any of the messages printed last.
845 color.summary.bar=on green
848 Colors the summary progress bar. Should consist of a background
849 color.
850 color.summary.background=on black
853 Colors the summary progress bar. Should consist of a background
854 color.
855 color.calendar.today=black on cyan
858 Color of today in calendar.
859 color.calendar.due=black on green
862 Color of days with due tasks in calendar.
863 color.calendar.due.today=black on magenta
866 Color of today with due tasks in calendar.
867 color.calendar.overdue=black on red
870 Color of days with overdue tasks in calendar.
871 color.calendar.weekend=bright white on black
874 Color of weekend days in calendar.
875 color.calendar.holiday=black on bright yellow
878 Color of holidays in calendar.
879 color.calendar.weeknumber=black on white
882 Color of weeknumbers in calendar.
883 color.label=
886 Colors the report labels. Defaults to not use color.
887 color.label.sort=
890 Colors the report labels for sort columns. Defaults to color.la‐
891 bel.
892 color.alternate=on rgb253
895 Color of alternate tasks. This is to apply a specific color to
896 every other task in a report, which can make it easier to vis‐
897 ually separate tasks. This is especially useful when tasks are
898 displayed over multiple lines due to long descriptions or anno‐
899 tations.
900 color.history.add=on red
903 color.history.done=on green
904 color.history.delete=on yellow
905 Colors the bars on the ghistory report graphs. Defaults to red,
906 green and yellow bars.
907 color.burndown.pending=on red
910 color.burndown.started=on yellow
911 color.burndown.done=on green
912 Colors the bars on the burndown reports graphs. Defaults to red,
913 green and yellow bars.
914 color.undo.before=red
917 color.undo.after=green
918 Colors used by the undo command, to indicate the values both be‐
919 fore and after a change that is to be reverted.
920 color.sync.added=green
923 color.sync.changed=yellow
924 color.sync.rejected=red
925 Colors the output of the sync command.
926 rule.precedence.color=due.today,active,blocking,blocked,overdue,due,
929 scheduled,keyword.,project.,tag.,uda.,recurring, tagged,com‐
930 pleted,deleted
931 This setting specifies the precedence of the color rules, from
932 highest to lowest. Note that the prefix 'color.' is omitted (for
933 brevity), and that any wildcard value (color.tag.XXX) is short‐
934 ened to 'tag.', which places all specific tag rules at the same
935 precedence, again for brevity.
936 color.debug=green
939 Colors all debug output, if enabled.
940 URGENCY
943 The urgency calculation uses a polynomial with several terms, each of
944 which has a configurable coefficient. Those coefficients are:
945 urgency.blocking.coefficient=8.0
948 Urgency coefficient for blocking tasks
949 urgency.blocked.coefficient=-5.0
950 Urgency coefficient for blocked tasks
951 urgency.due.coefficient=12.0
952 Urgency coefficient for due dates
953 urgency.waiting.coefficient=-3.0
954 Urgency coefficient for waiting status
955 urgency.active.coefficient=4.0
956 Urgency coefficient for active tasks
957 urgency.scheduled.coefficient=5.0
958 Urgency coefficient for scheduled tasks
959 urgency.project.coefficient=1.0
960 Urgency coefficient for projects
961 urgency.tags.coefficient=1.0
962 Urgency coefficient for tags
963 urgency.annotations.coefficient=1.0
964 Urgency coefficient for annotations
965 urgency.age.coefficient=2.0
966 Urgency coefficient for the age of tasks
967 urgency.age.max=365
968 Maximum age in days. After this number of days has elapsed, the
969 urgency of a task won't increase any more because of aging.
970 urgency.user.tag.<tag>.coefficient=...
971 Specific tag coefficient.
972 urgency.user.tag.next.coefficient=15.0
973 Urgency coefficient for tag 'next'.
974 urgency.user.project.<project>.coefficient=...
975 Specific project coefficient.
976 urgency.user.keyword.<keyword>.coefficient=...
977 Specific description keyword coefficient.
978 urgency.uda.<name>.coefficient=...
979 Presence/absence of UDA data.
980 urgency.uda.<name>.<value>.coefficient=...
981 Specific value of UDA data.
982 The coefficients reflect the relative importance of the various terms
984 in the urgency calculation. These are default values, and may be modi‐
985 fied to suit your preferences, but it is important that you carefully
986 consider any modifications.
987 urgency.inherit=0
989 Not actually a coefficient. When enabled, blocking tasks inherit
990 the highest urgency value found in the tasks they block. This is
991 done recursively. It is recommended to set urgency.blocking.co‐
992 efficient and urgency.blocked.coefficient to 0.0 in order for
993 this setting to be the most useful.
994 DEFAULTS
997 default.project=foo
998 Provides a default project name for the task add command, if you
999 don't specify one. The default is blank.
1000 default.due=...
1003 Provides a default due date for the task add command, if you
1004 don't specify one. You can use a date, or a duration value which
1005 is assumed to be relative to 'now'. The default is blank.
1006 default.scheduled=...
1009 Provides a default scheduled date for the task add command, if
1010 you don't specify one. You can use a date, or a duration value
1011 which is assumed to be relative to 'now'. The default is blank.
1012 uda.<name>.default=...
1015 Provides default values for UDA fields when using the task add
1016 command, if you don't specify values. The default is blank.
1017 default.command=next
1020 Provides a default command that is run every time Taskwarrior is
1021 invoked with no arguments. For example, if set to:
1022 default.command=project:foo list
1024 then Taskwarrior will run the "project:foo list" command if no
1026 command is specified. This means that by merely typing
1027 $ task
1029 [task project:foo list]
1030 ID Project Pri Description
1032 1 foo H Design foo
1033 2 foo Build foo
1034 REPORTS
1037 The reports can be customized by using the following configuration
1038 variables. The output columns, their labels and the sort order can be
1039 set using the corresponding variables for each report. Each report name
1040 is used as a "command" name. For example
1041 task overdue
1044 report.X.description
1047 The description for report X when running the "task help" com‐
1048 mand.
1049 report.X.columns
1052 This is a comma-separated list of columns and formatting speci‐
1053 fiers. See the command 'task columns' for a full list of options
1054 and examples.
1055 report.X.labels
1058 The labels for each column that will be used when generating re‐
1059 port X. The labels are a comma separated list.
1060 report.X.sort
1063 The sort order of the tasks in the generated report X. The sort
1064 order is specified by using the column ids post-fixed by a "+"
1065 for ascending sort order or a "-" for descending sort order. The
1066 sort IDs are separated by commas. For example:
1067 report.list.sort=due+,priority-,start.active-,project+
1069 Additionally, after the "+" or "-", there can be a solidus "/"
1071 which indicates that there are breaks after the column values
1072 change. For example:
1073 report.minimal.sort=project+/,description+
1075 This sort order now specifies that there is a listing break be‐
1077 tween each project. A listing break is simply a blank line,
1078 which provides a visual grouping.
1079 A special sort value of "none" indicates that no sorting is re‐
1081 quired, and tasks will be presented in the order (if any) in
1082 which they are selected.
1083 report.X.filter
1086 This adds a filter to the report X so that only tasks matching
1087 the filter criteria are displayed in the generated report.
1088 There is a special case for 'report.timesheet.filter', which may
1090 be specified even though the 'timesheet' report is not very cus‐
1091 tomizable.
1092 report.X.dateformat
1095 This adds a dateformat to the report X that will be used by the
1096 "due date" column. If it is not set then dateformat.report and
1097 dateformat will be used in this order. See the DATES section for
1098 details on the sequence placeholders.
1099 report.X.annotations
1102 This adds the possibility to control the output of annotations
1103 for a task in a report. Deprecated. Use the description column
1104 with a format (e.g., description.count) instead.
1105 Taskwarrior comes with a number of predefined reports, which are:
1108 next Lists the most important tasks.
1111 long Lists all pending tasks and all data, matching the specified
1114 criteria.
1115 list Lists all tasks matching the specified criteria.
1118 ls Short listing of all tasks matching the specified criteria.
1121 minimal
1124 Minimal listing of all tasks matching the specified criteria.
1125 newest Shows the newest tasks.
1128 oldest Shows the oldest tasks.
1131 overdue
1134 Lists overdue tasks matching the specified criteria.
1135 active Lists active tasks matching the specified criteria.
1138 completed
1141 Lists completed tasks matching the specified criteria.
1142 recurring
1145 Lists recurring tasks matching the specified criteria.
1146 waiting
1149 Lists all waiting tasks matching the specified criteria.
1150 all Lists all tasks matching the specified criteria.
1153 blocked
1156 Lists all tasks that have dependencies.
1157 USER DEFINED ATTRIBUTES
1160 User defined attributes (UDAs) are an extension mechanism that allows
1161 you to define new attributes for Taskwarrior to store and display. One
1162 such example is an 'estimate' attribute that could be used to store
1163 time estimates associated with a task. This 'estimate' attribute is not
1164 built in to Taskwarrior, but with a few simple configuration settings
1165 you can instruct Taskwarrior to store this item, and provide access to
1166 it for custom reports and filters.
1167 This allows you to augment Taskwarrior to accommodate your workflow, or
1169 bend the rules and use Taskwarrior to store and synch data that is not
1170 necessarily task-related.
1171 One important restriction is that because this is an open system that
1173 allows the definition of any new attribute, Taskwarrior cannot under‐
1174 stand the meaning of that attribute. So while Taskwarrior will faith‐
1175 fully store, modify, report, sort and filter your UDA, it does not un‐
1176 derstand anything about it. For example if you define a UDA named 'es‐
1177 timate', Taskwarrior will not know that this value is weeks, hours,
1178 minutes, money, or some other resource count.
1179 uda.<name>.type=string|numeric|date|duration
1182 Defines a UDA called '<name>', of the specified type.
1183 uda.<name>.label=<column heading>
1186 Provides a default report label for the UDA called '<name>'.
1187 uda.<name>.values=A,B,C
1190 For type 'string' UDAs only, this provides a comma-separated
1191 list of acceptable values. In this example, the '<name>' UDA may
1192 only contain values 'A', 'B', or 'C', but may also contain no
1193 value.
1194 Note that the order of the value is important, and denotes the
1196 sort order from highest ('A') to lowest ('C').
1197 Note that a blank value is permitted.
1199 uda.<name>.default=...
1202 Provides a default value for the UDA called '<name>'.
1203 Example 'estimate' UDA
1206 This example shows an 'estimate' UDA that stores specific values
1207 for the size of a task. Note the blank value after 'trivial'.
1208 uda.estimate.type=string
1210 uda.estimate.label=Size Estimate
1211 uda.estimate.values=huge,large,medium,small,trivial,
1212 Note that the value are sorted
1214 huge > large > medium > small > trivial > ''
1216 CONTEXT
1219 Context setting is a mechanism which allows the user to set a permanent
1220 filter, thus avoiding the need to specify one filter repeatedly. More
1221 details on usage can be found in the task(1) man page.
1222 The current context is stored in the .taskrc file, along with defini‐
1224 tions for all user provided contexts.
1225 context=<name>
1228 Stores the value of the currently active context.
1229 context.<name>=<filter>
1232 Stores the definition of the context with the name <name>.
1233 SYNC
1236 These configuration settings are used to connect and sync tasks with
1237 the task server.
1238 taskd.server=<host>:<port>
1241 Specifies the hostname and port of the Taskserver. Hostname may
1242 be an IPv4 or IPv6 address, or domain. Port is an integer.
1243 taskd.credentials=<organization>/<user>/<key>
1246 User identification for the Taskserver, which includes a private
1247 key.
1248 taskd.certificate=<path>
1251 Specifies the path to the client certificate used for identifi‐
1252 cation with the Taskserver.
1253 taskd.key=<path>
1256 Specifies the path to the client key used for encrypted communi‐
1257 cation with the Taskserver.
1258 taskd.ca=<path>
1261 Specifies the path to the CA certificate in the event that your
1262 Taskserver is using a self-signed certificate. Optional.
1263 taskd.trust=strict|ignore hostname|allow all
1266 This settings allows you to override the trust level when server
1267 certificates are validated. With "allow all", the server cer‐
1268 tificate is trusted automatically. With "ignore hostname", the
1269 server certificate is verified but the hostname is ignored. With
1270 "strict", the server certificate is verified. Default is
1271 "strict", which requires full validation.
1272 taskd.ciphers=NORMAL
1275 Override of the cipher selection. The set of ciphers used by TLS
1276 may be controlled by both server and client. There must be some
1277 overlap between client and server supported ciphers, or communi‐
1278 cation cannot occur. Default is "NORMAL". See GnuTLS documenta‐
1279 tion for full details.
1280
1283 Copyright (C) 2006 - 2021 P. Beckingham, F. Hernandez.
1284 This man page was originally written by Federico Hernandez.
1286 Taskwarrior is distributed under the MIT license. See https://www.open‐
1288 source.org/licenses/mit-license.php for more information.
1289
1292 task(1), task-color(5), task-sync(5)
1293 For more information regarding Taskwarrior, see the following:
1295 The official site at
1298 <https://taskwarrior.org>
1299 The official code repository at
1302 <https://github.com/GothenburgBitFactory/taskwarrior>
1303 You can contact the project by emailing
1306 <support@GothenburgBitFactory.org>
1307
1310 Bugs in Taskwarrior may be reported to the issue-tracker at
1311 <https://github.com/GothenburgBitFactory/taskwarrior/issues>
1312task 2.5.3 2016-02-24 taskrc(5)