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 simply syntax defining name/value
44 pairs:
45 <name> = <value>
47 There may be whitespace around <name>, '=' and <value>, and it is
49 ignored. 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 "on", "yes", "y", "1" and "true". Anything
56 else means "off".
57 include <file>
59 There may be whitespace around 'include' and <file>. The file may be an
61 absolute or relative path, and the special character '~' is expanded to
62 mean $HOME. The entry must be on a single line, no continuations.
63 # <comment>
65 A comment consists of the character '#', and extends from the '#' to
67 the end of the line. There is no way to comment a multi-line block.
68 There may be blank lines.
69 Almost every value has a default setting, and an empty .taskrc file is
71 one that makes use of every default. The contents of the .taskrc file
72 therefore represent overrides of the default values. To remove a
73 default value completely there must be an entry like this:
74 <name> =
76 This entry overrides the default value with a blank value.
78
81 You can edit your .taskrc file by hand if you wish, or you can use the
82 'config' command. To permanently set a value in your .taskrc file, use
83 this command:
84 $ task config nag "You have more urgent tasks."
86 To delete an entry, use this command:
88 $ task config nag
90 Taskwarrior will then use the default value. To explicitly set a value
92 to blank, and therefore avoid using the default value, use this com‐
93 mand:
94 $ task config nag ""
96 Taskwarrior will also display all your settings with this command:
98 $ task show
100 and in addition, will also perform a check of all the values in the
102 file, warning you of anything it finds amiss.
103
106 The .taskrc can include other files containing configuration settings
107 by using the include statement:
108 include <path/to/the/configuration/file/to/be/included>
110 By using include files you can divide your main configuration file into
112 several ones containing just the relevant configuration data like col‐
113 ors, etc.
114 There are two excellent uses of includes in your .taskrc, shown here:
116 include /usr/share/task/holidays.en-US.rc
118 include /usr/share/task/dark-16.theme
119 This includes two standard files that are distributed with Taskwarrior,
121 which define a set of US holidays, and set up a 16-color theme to use,
122 to color the reports and calendar.
123
126 These environment variables override defaults and command line argu‐
127 ments.
128 TASKDATA=~/.task
131 This overrides the default path for the Taskwarrior data files.
132 TASKRC=~/.taskrc
135 This overrides the default RC file.
136
139 Valid variable names and their default values are:
140 FILES
143 data.location=$HOME/.task
144 This is a path to the directory containing all the Taskwarrior
145 files. By default, it is set up to be ~/.task, for example:
146 /home/paul/.task
147 Note that you can use the ~ shell meta character, which will be
149 properly expanded.
150 Note that the TASKDATA environment variable overrides this set‐
152 ting.
153 locking=on
156 Determines whether to use file locking when accessing the pend‐
157 ing.data and completed.data files. Defaults to "on". Solaris
158 users who store the data files on an NFS mount may need to set
159 locking to "off". Note that there is danger in setting this
160 value to "off" - another program (or another instance of task)
161 may write to the task.pending file at the same time.
162 gc=on Can be used to temporarily suspend garbage collection (gc), so
165 that task IDs don't change. Note that this should be used in the
166 form of a command line override (task rc.gc=off ...), and not
167 permanently used in the .taskrc file, as this significantly
168 affects performance in the long term.
169 hooks=on
172 This master control switch enables hook script processing. The
173 default value is 'on', but certain extensions and environments
174 may need to disable hooks.
175 exit.on.missing.db=no
178 When set to 'yes' causes the program to exit if the database
179 (~/.task or rc.data.location or TASKDATA override) is missing.
180 Default value is 'no'.
181 TERMINAL
184 detection=on
185 Determines whether to use ioctl to establish the size of the
186 window you are using, for text wrapping.
187 defaultwidth=80
190 The width of output used when auto-detection support is not
191 available. Defaults to 80. If set to 0, it is interpreted as
192 infinite width, therefore with no word-wrapping; this is useful
193 when redirecting report output to a file for subsequent han‐
194 dling.
195 defaultheight=24
198 The height of output used when auto-detection support is not
199 available. Defaults to 24. If set to 0, it is interpreted as
200 infinite height. This is useful when redirecting charts to a
201 file for subsequent handling.
202 avoidlastcolumn=no
205 Causes the width of the terminal minus one to be used as the
206 full width. This avoids placing color codes in the last column
207 which can cause problems for Cygwin users. Default value is
208 'no'.
209 hyphenate=on
212 Hyphenates lines when wrapping breaks occur mid-word. Default
213 value is 'on'.
214 editor=vi
217 Specifies which text editor you wish to use for when the task
218 edit <ID> command is used. Taskwarrior will first look for this
219 configuration variable. If found, it is used. Otherwise it will
220 look for the $VISUAL or $EDITOR environment variables, before it
221 defaults to using "vi".
222 reserved.lines=1
225 This is the number of lines reserved at the bottom of the screen
226 for the shell prompt. This is only referenced when 'limit:page'
227 is used.
228 MISCELLANEOUS
231 verbose=on|off|nothing|list...
232 When set to "on" (the default), helpful explanatory comments are
233 added to all output from Taskwarrior. Setting this to "off"
234 means that you would see regular output.
235 The special value "nothing" can be used to eliminate all
237 optional output, which results in only the formatted data being
238 shown, with nothing else. This output is most readily parsed and
239 used by shell scripts.
240 Alternatively, you can specify a comma-separated list of ver‐
242 bosity tokens that control specific occasions when output is
243 generated. This list may contain:
244 blank Inserts extra blank lines in output, for clarity
246 header Messages that appear before report output
247 footnote Messages that appear after report output
248 label Column labels on tabular reports
249 new-id Provides feedback of any new task IDs
250 new-uuid Provides feedback of any new task UUIDs. Depre‐
251 cated, to be
252 merged with new-id.
253 affected Reports 'N tasks affected' and similar
254 edit Used the verbose template for the 'edit' command
255 special Feedback when applying special tags
256 project Feedback about project status changes
257 sync Feedback about sync
258 filter Shows the filter used in the command
259 unwait Notification when a task leaves the 'waiting'
260 state
261 recur Notification when a new recurring task instance
262 is created
263 "affected", "new-id", "new-uuid" "project" and "unwait" imply
265 "footnote".
266 Note that the "on" setting is equivalent to all the tokens being
268 specified, and the "nothing" setting is equivalent to none of
269 the tokens being specified.
270 Here are the shortcut equivalents:
272 verbose=on
274 verbose=blank,header,footnote,label,new-
275 id,affected,edit,special,project,sync,filter,unwait
276 verbose=off
278 verbose=blank,label,new-id,edit
279 verbose=nothing
281 verbose=
282 Those additional comments are sent to the standard error for
284 header, footnote and project. The others are sent to standard
285 output.
286 confirmation=yes
289 May be "yes" or "no", and determines whether Taskwarrior will
290 ask for confirmation before deleting a task or performing the
291 undo command. The default value is "yes". Consider leaving this
292 setting as "yes", for safety.
293 allow.empty.filter=yes
296 An empty filter combined with a write command is potentially a
297 way to modify all tasks by mistake, and when this is detected,
298 confirmation is required. Setting this to 'no' means that it is
299 an error to use a write command with no filter.
300 indent.annotation=2
303 Controls the number of spaces to indent annotations when shown
304 beneath the description field. The default value is "2".
305 indent.report=0
308 Controls the indentation of the entire report output. Default is
309 "0".
310 row.padding=0
313 Controls left and right padding around each row of the report
314 output. Default is "0".
315 column.padding=0
318 Controls padding between columns of the report output. Default
319 is "1".
320 bulk=3 Is a number, defaulting to 3. When this number or greater of
323 tasks are modified in a single command, confirmation will be
324 required, regardless of the value of confirmation variable. The
325 special value bulk=0 is treated as an infinity.
326 This is useful for preventing large-scale unintended changes.
328 nag=You have more urgent tasks.
331 This may be a string of text, or blank. It is used as a prompt
332 when a task is started of completed, when there are other tasks
333 with a higher urgency. Default value is: 'You have more urgent
334 tasks'. It is a gentle reminder that you are contradicting your
335 own urgency settings.
336 list.all.projects=no
339 May be yes or no, and determines whether the 'projects' command
340 lists all the project names you have used, or just the ones used
341 in active tasks. The default value is "no".
342 summary.all.projects=no
345 If set to yes, shows all projects in the summary report, even if
346 there are no pending tasks. The default value is "no".
347 complete.all.tags=yes
350 May be yes or no, and determines whether the tab completion
351 scripts consider all the tag names you have used, or just the
352 ones used in active tasks. The default value is "no".
353 list.all.tags=yes
356 May be yes or no, and determines whether the 'tags' command
357 lists all the tag names you have used, or just the ones used in
358 active tasks. The default value is "no".
359 print.empty.columns=no
362 May be yes or no, and determines whether columns with no data
363 for any task are printed. Defaults to no.
364 search.case.sensitive=yes
367 May be yes or no, and determines whether keyword lookup and sub‐
368 stitutions on the description and annotations are done in a case
369 sensitive way. Defaults to yes on most platforms. Defaults to no
370 on Cygwin due to older regex library problems with case-insensi‐
371 tivity.
372 regex=on
375 Controls whether regular expression support is enabled. The
376 default value is on.
377 xterm.title=no
380 Sets the xterm window title when reports are run. Defaults to
381 off.
382 expressions=infix|postfix
385 Sets a preference for infix expressions (1 + 2) or postfix
386 expressions (1 2 +). Defaults to infix.
387 json.array=on
390 Determines whether the export command encloses the JSON output
391 in '[...]' and adds ',' after each exported task object to cre‐
392 ate a properly-formed JSON array. With json.array=off, export
393 writes raw JSON objects to STDOUT, one per line. Defaults to
394 on.
395 json.depends.array=on
398 Determines whether the export command encodes dependencies as an
399 array of string UUIDs, or one comma-separated string. Defaults
400 to on.
401 _forcecolor=no
404 Taskwarrior shuts off color automatically when the output is not
405 sent directly to a TTY. For example, this command:
406 $ task list > file
408 will not use any color. To override this, use:
410 $ task rc._forcecolor=yes list > file
412 active.indicator=*
415 The character or string to show in the start.active column.
416 Defaults to *.
417 tag.indicator=+
420 The character or string to show in the tag.indicator column.
421 Defaults to +.
422 dependency.indicator=D
425 The character or string to show in the depends.indicator column.
426 Defaults to +.
427 uda.<name>.indicator=U
430 The character or string to show in the <uda>.indicator column.
431 Defaults to U.
432 recurrence=yes
435 Controls whether recurrence is enabled, and whether recurring
436 tasks continue to generate new task instances. Defaults to
437 'yes'.
438 recurrence.confirmation=prompt
441 Controls whether changes to recurring tasks propagates to other
442 child tasks with or without confirmation. A value of 'yes' means
443 propagate changes without confirmation. A value of 'no' means do
444 not propagate changes and don't ask for confirmation. A value of
445 'prompt' prompts you every time. Defaults to 'prompt'.
446 recurrence.indicator=R
449 The character or string to show in the recurrence_indicator col‐
450 umn. Defaults to R.
451 recurrence.limit=1
454 The number of future recurring tasks to show. Defaults to 1. For
455 example, if a weekly recurring task is added with a due date of
456 tomorrow, and recurrence.limit is set to 2, then a report will
457 list 2 pending recurring tasks, one for tomorrow, and one for a
458 week from tomorrow.
459 undo.style=side
462 When the 'undo' command is run, Taskwarrior presents a before
463 and after comparison of the data. This can be in either the
464 'side' style, which compares values side-by-side in a table, or
465 'diff' style, which uses a format similar to the 'diff' command.
466 abbreviation.minimum=2
469 Minimum length of any abbreviated command/value. This means that
470 "ve", "ver", "vers", "versi", "versio" will all equate to "ver‐
471 sion", but "v" will not. Default is 2.
472 debug=off
475 Taskwarrior has a debug mode that causes diagnostic output to be
476 displayed. Typically this is not something anyone would want,
477 but when reporting a bug, debug output can be useful. It can
478 also help explain how the command line is being parsed, but the
479 information is displayed in a developer-friendly, not a user-
480 friendly way.
481 Turning debug on automatically sets debug.hooks=1,
483 debug.parser=1 and debug.tls=2 if they do not already have
484 assigned values.
485 debug.hooks=0
488 Controls the hook system diagnostic level. Level 0 means no
489 diagnostics. Level 1 shows hook calls. Level 2 also shows exit
490 status and I/O.
491 debug.parser=0
494 Controls the parser diagnostic level. Level 0 shows no diagnos‐
495 tics. Level 1 shows the final parse tree. Level 2 shows the
496 parse tree from all phases of the parse. Level 3 shows expres‐
497 sion evaluation details.
498 debug.tls=0
501 Controls the GnuTLS diagnostic level. For 'sync' debugging.
502 Level 0 means no diagnostics. Level 9 is the highest. Level 2 is
503 a good setting for debugging.
504 obfuscate=1
507 When set to '1', will replace all report text with 'xxx'. This
508 is useful for sharing report output in bug reports. Default
509 value is '0'.
510 alias.rm=delete
513 Taskwarrior supports command aliases. This alias provides an
514 alternate name (rm) for the delete command. You can use aliases
515 to provide alternate names for any of the commands. Several com‐
516 mands you may use are actually aliases - the 'history' report,
517 for example, or 'export'.
518 DATES
521 dateformat=Y-M-D
522 dateformat.report=
524 dateformat.holiday=YMD
526 dateformat.edit=Y-M-D H:N:S
528 dateformat.info=Y-M-D H:N:S
530 dateformat.annotation=
532 report.X.dateformat=Y-M-D
534 This is a string of characters that defines how Taskwarrior for‐
535 mats date values. The precedence order for the configuration
536 variable is report.X.dateformat then dateformat.report then
537 dateformat for formatting the due dates in reports. If both
538 report.X.dateformat and dateformat.report are not set then date‐
539 format will be applied to the date. Entered dates as well as all
540 other displayed dates in reports are formatted according to
541 dateformat.
542 The default value is the ISO-8601 standard: Y-M-D. The string
544 can contain the characters:
545 m minimal-digit month, for example 1 or 12
547 d minimal-digit day, for example 1 or 30
548 y two-digit year, for example 09 or 12
549 D two-digit day, for example 01 or 30
550 M two-digit month, for example 01 or 12
551 Y four-digit year, for example 2009 or 2015
552 a short name of weekday, for example Mon or Wed
553 A long name of weekday, for example Monday or Wednes‐
554 day
555 b short name of month, for example Jan or Aug
556 B long name of month, for example January or August
557 v minimal-digit week, for example 3 or 37
558 V two-digit week, for example 03 or 37
559 h minimal-digit hour, for example 3 or 21
560 n minimal-digit minutes, for example 5 or 42
561 s minimal-digit seconds, for example 7 or 47
562 H two-digit hour, for example 03 or 21
563 N two-digit minutes, for example 05 or 42
564 S two-digit seconds, for example 07 or 47
565 J three-digit Julian day, for example 023 or 365
566 j Julian day, for example 23 or 365
567 The characters 'v', 'V', 'a' and 'A' can only be used for for‐
569 matting printed dates (not to parse them).
570 The string may also contain other characters to act as spacers,
572 or formatting. Examples for other values of dateformat:
573 d/m/Y would use for input and output 24/7/2009
575 yMD would use for input and output 090724
576 M-D-Y would use for input and output 07-24-2009
577 Examples for other values of dateformat.report:
579 a D b Y (V) would emit "Fri 24 Jul 2009 (30)"
581 A, B D, Y would emit "Friday, July 24, 2009"
582 wV a Y-M-D would emit "w30 Fri 2009-07-24"
583 yMD.HN would emit "110124.2342"
584 m/d/Y H:N would emit "1/24/2011 10:42"
585 a D b Y H:N:S would emit "Mon 24 Jan 2011 11:19:42"
586 Undefined fields are put to their minimal valid values (1 for
588 month and day and 0 for hour, minutes and seconds) when there is
589 at least one more global date field that is set. Otherwise, they
590 are set to the corresponding values of "now". For example:
591 8/1/2013 with m/d/Y implies August 1, 2013 at midnight
593 (inferred)
594 8/1 20:40 with m/d H:N implies August 1, 2013 (inferred)
595 at 20:40
596 date.iso=yes
599 Enables ISO-8601 date support. The default value is "yes".
600 weekstart=Sunday
603 Determines the day a week starts. Valid values are Sunday or
604 Monday only. The default value is "Sunday".
605 displayweeknumber=yes
608 Determines if week numbers are displayed when using the "task
609 calendar" command. The week number is dependent on the day a
610 week starts. The default value is "yes".
611 due=7 This is the number of days into the future that define when a
614 task is considered due, and is colored accordingly. The default
615 value is 7.
616 calendar.details=sparse
619 If set to full running "task calendar" will display the details
620 of tasks with due dates that fall into the calendar period. The
621 corresponding days will be color-coded in the calendar. If set
622 to sparse only the corresponding days will be color coded and no
623 details will be displayed. The displaying of due dates with
624 details is turned off by setting the variable to none. The
625 default value is "sparse".
626 calendar.details.report=list
629 The report to run when displaying the details of tasks with due
630 dates when running the "task calendar" command. The default
631 value is "list".
632 calendar.offset=off
635 If "on" the first month in the calendar report is effectively
636 changed by the offset value specified in calendar.offset.value.
637 It defaults to "off".
638 calendar.offset.value=-1
641 The offset value to apply to the first month in the calendar
642 report. The default value is "-1".
643 calendar.holidays=full
646 If set to full running "task calendar" will display holidays in
647 the calendar by color-coding the corresponding days. A detailed
648 list with the dates and names of the holidays is also shown. If
649 set to sparse only the days are color-coded and no details on
650 the holidays will be displayed. The displaying of holidays is
651 turned off by setting the variable to none. The default value is
652 "none".
653 calendar.legend=yes
656 Determines whether the calendar legend is displayed. The default
657 value is "yes".
658 JOURNAL ENTRIES
661 journal.time=no
662 May be yes or no, and determines whether the 'start' and 'stop'
663 commands should record an annotation when being executed. The
664 default value is "no". The text of the corresponding annotations
665 is controlled by:
666 journal.time.start.annotation=Started task
669 The text of the annotation that is recorded when executing the
670 start command and having set journal.time.
671 journal.time.stop.annotation=Stopped task
674 The text of the annotation that is recorded when executing the
675 stop command and having set journal.time.
676 journal.info=on
679 When enabled, this setting causes a change log of each task to
680 be displayed by the 'info' command. Default value is "on".
681 HOLIDAYS
684 Holidays are entered either directly in the .taskrc file or via an
685 include file that is specified in .taskrc. For each holiday the name
686 and the date is required to be given:
687 holiday.towel.name=Day of the towel
689 holiday.towel.date=20100525
690 holiday.sysadmin.name=System Administrator Appreciation
691 Day
692 holiday.sysadmin.date=20100730
693 Dates are to be entered according to the setting in the datefor‐
695 mat.holiday variable.
696 The following holidays are computed automatically: Good Friday
698 (goodfriday), Easter (easter), Easter Monday (eastermonday),
699 Ascension (ascension), Pentecost (pentecost). The date for these
700 holidays is the given keyword:
701 holiday.eastersunday.name=Easter
703 holiday.eastersunday.date=easter
704 Note that the Taskwarrior distribution contains example holiday files
706 that can be included like this:
707 include /usr/share/task/holidays.en-US.rc
709 monthsperline=3
712 Determines how many months the "task calendar" command renders
713 across the screen. Defaults to however many will fit. If more
714 months than will fit are specified, Taskwarrior will only show
715 as many that will fit.
716 DEPENDENCIES
719 dependency.reminder=on
720 Determines whether dependency chain violations generate
721 reminders.
722 dependency.confirmation=yes
725 Determines whether dependency chain repair requires confirma‐
726 tion.
727 COLOR CONTROLS
730 color=on
731 May be "on" or "off". Determines whether Taskwarrior uses color.
732 When "off", will use dashes (-----) to underline column head‐
733 ings.
734 fontunderline=on
737 Determines if font underlines or ASCII dashes should be used to
738 underline headers, even when color is enabled.
739 Taskwarrior has a number of coloration rules. They correspond to a par‐
741 ticular attribute of a task, such as it being due, or being active, and
742 specifies the automatic coloring of that task. A list of valid colors,
743 depending on your terminal, can be obtained by running the command:
744 task color
746 Note that no default values are listed here - the defaults now
748 correspond to the dark-256.theme (Linux) and dark-16.theme
749 (other) theme values. The coloration rules are as follows:
750 color.due.today Task is due today
752 color.active Task is started, therefore active.
753 color.scheduled Task is scheduled, therefore ready for work.
754 color.until Task has an expiration date.
755 color.blocking Task is blocking another in a dependency.
756 color.blocked Task is blocked by a dependency.
757 color.overdue Task is overdue (due some time prior to now).
758 color.due Task is coming due.
759 color.project.none Task does not have an assigned project.
760 color.tag.none Task has no tags.
761 color.tagged Task has at least one tag.
762 color.recurring Task is recurring.
763 color.completed Task is completed.
764 color.deleted Task is deleted.
765 To disable a coloration rule for which there is a default, set
767 the value to nothing, for example:
768 color.tagged=
769 By default, colors produced by rules blend. This has the advan‐
771 tage of conveying additional information, by producing combina‐
772 tions that are not used by any particular rule directly.
773 However, color blending can produce highlighting combinations
775 which are not desired. In such cases, use the following option
776 to disable this behaviour:
777 rule.color.merge=yes
780 Can be "yes" or "no". When "no", disables merging of colors pro‐
781 duced by different color rules. Use if your color scheme pro‐
782 duces unpleasing foreground and background combinations.
783 See the task-color(5) man pages for color details.
786 Certain attributes like tags, projects and keywords can have their own
788 coloration rules.
789 color.tag.X=yellow
792 Colors any task that has the tag X.
793 color.project.X=on green
796 Colors any task assigned to project X.
797 color.keyword.X=on blue
800 Colors any task where the description or any annotation contains
801 X.
802 color.uda.X=on green
805 Colors any task that has the user defined attribute X.
806 color.uda.X.VALUE=on green
809 Colors any task that has the user defined attribute X set to
810 VALUE.
811 color.uda.X.none=on green
814 Colors any task that does not have the user defined attribute X.
815 color.error=white on red
818 Colors any of the error messages.
819 color.warning=bold red
822 Colors any of the warning messages.
823 color.header=green
826 Colors any of the messages printed prior to the report output.
827 color.footnote=green
830 Colors any of the messages printed last.
831 color.summary.bar=on green
834 Colors the summary progress bar. Should consist of a background
835 color.
836 color.summary.background=on black
839 Colors the summary progress bar. Should consist of a background
840 color.
841 color.calendar.today=black on cyan
844 Color of today in calendar.
845 color.calendar.due=black on green
848 Color of days with due tasks in calendar.
849 color.calendar.due.today=black on magenta
852 Color of today with due tasks in calendar.
853 color.calendar.overdue=black on red
856 Color of days with overdue tasks in calendar.
857 color.calendar.weekend=bright white on black
860 Color of weekend days in calendar.
861 color.calendar.holiday=black on bright yellow
864 Color of holidays in calendar.
865 color.calendar.weeknumber=black on white
868 Color of weeknumbers in calendar.
869 color.label=
872 Colors the report labels. Defaults to not use color.
873 color.label.sort=
876 Colors the report labels for sort columns. Defaults to
877 color.label.
878 color.alternate=on rgb253
881 Color of alternate tasks. This is to apply a specific color to
882 every other task in a report, which can make it easier to vis‐
883 ually separate tasks. This is especially useful when tasks are
884 displayed over multiple lines due to long descriptions or anno‐
885 tations.
886 color.history.add=on red
889 color.history.done=on green
890 color.history.delete=on yellow
891 Colors the bars on the ghistory report graphs. Defaults to red,
892 green and yellow bars.
893 color.burndown.pending=on red
896 color.burndown.started=on yellow
897 color.burndown.done=on green
898 Colors the bars on the burndown reports graphs. Defaults to red,
899 green and yellow bars.
900 color.undo.before=red
903 color.undo.after=green
904 Colors used by the undo command, to indicate the values both
905 before and after a change that is to be reverted.
906 color.sync.added=green
909 color.sync.changed=yellow
910 color.sync.rejected=red
911 Colors the output of the sync command.
912 rule.precedence.color=due.today,active,blocking,blocked,overdue,due,
915 scheduled,keyword.,project.,tag.,uda.,recurring,
916 pri.,tagged,completed,deleted
917 This setting specifies the precedence of the color rules, from
918 highest to lowest. Note that the prefix 'color.' is omitted (for
919 brevity), and that any wildcard value (color.tag.XXX) is short‐
920 ened to 'tag.', which places all specific tag rules at the same
921 precedence, again for brevity.
922 color.debug=green
925 Colors all debug output, if enabled.
926 URGENCY
929 The urgency calculation uses a polynomial with several terms, each of
930 which has a configurable coefficient. Those coefficients are:
931 urgency.blocking.coefficient=8.0
934 Urgency coefficient for blocking tasks
935 urgency.blocked.coefficient=-5.0
936 Urgency coefficient for blocked tasks
937 urgency.due.coefficient=12.0
938 Urgency coefficient for due dates
939 urgency.waiting.coefficient=-3.0
940 Urgency coefficient for waiting status
941 urgency.active.coefficient=4.0
942 Urgency coefficient for active tasks
943 urgency.scheduled.coefficient=5.0
944 Urgency coefficient for scheduled tasks
945 urgency.project.coefficient=1.0
946 Urgency coefficient for projects
947 urgency.tags.coefficient=1.0
948 Urgency coefficient for tags
949 urgency.annotations.coefficient=1.0
950 Urgency coefficient for annotations
951 urgency.age.coefficient=2.0
952 Urgency coefficient for the age of tasks
953 urgency.age.max=365
954 Maximum age in days. After this number of days has elapsed, the
955 urgency of a task won't increase any more because of aging.
956 urgency.user.tag.<tag>.coefficient=...
957 Specific tag coefficient.
958 urgency.user.tag.next.coefficient=15.0
959 Urgency coefficient for tag 'next'.
960 urgency.user.project.<project>.coefficient=...
961 Specific project coefficient.
962 urgency.user.keyword.<keyword>.coefficient=...
963 Specific description keyword coefficient.
964 urgency.uda.<name>.coefficient=...
965 Presence/absence of UDA data.
966 urgency.uda.<name>.<value>.coefficient=...
967 Specific value of UDA data.
968 The coefficients reflect the relative importance of the various terms
970 in the urgency calculation. These are default values, and may be modi‐
971 fied to suit your preferences, but it is important that you carefully
972 consider any modifications.
973 urgency.inherit=off
975 Not actually a coefficient. When enabled, blocking tasks inherit
976 the highest urgency value found in the tasks they block. This is
977 done recursively. It is recommended to set urgency.block‐
978 ing.coefficient and urgency.blocked.coefficient to 0.0 in order
979 for this setting to be the most useful.
980 DEFAULTS
983 default.project=foo
984 Provides a default project name for the task add command, if you
985 don't specify one. The default is blank.
986 default.due=...
989 Provides a default due date for the task add command, if you
990 don't specify one. You can use a date, or a duration value which
991 is assumed to be relative to 'now'. The default is blank.
992 uda.<name>.default=...
995 Provides default values for UDA fields when using the task add
996 command, if you don't specify values. The default is blank.
997 default.command=next
1000 Provides a default command that is run every time Taskwarrior is
1001 invoked with no arguments. For example, if set to:
1002 default.command=project:foo list
1004 then Taskwarrior will run the "project:foo list" command if no
1006 command is specified. This means that by merely typing
1007 $ task
1009 [task project:foo list]
1010 ID Project Pri Description
1012 1 foo H Design foo
1013 2 foo Build foo
1014 REPORTS
1017 The reports can be customized by using the following configuration
1018 variables. The output columns, their labels and the sort order can be
1019 set using the corresponding variables for each report. Each report name
1020 is used as a "command" name. For example
1021 task overdue
1024 report.X.description
1027 The description for report X when running the "task help" com‐
1028 mand.
1029 report.X.columns
1032 This is a comma-separated list of columns and formatting speci‐
1033 fiers. See the command 'task columns' for a full list of options
1034 and examples.
1035 report.X.labels
1038 The labels for each column that will be used when generating
1039 report X. The labels are a comma separated list.
1040 report.X.sort
1043 The sort order of the tasks in the generated report X. The sort
1044 order is specified by using the column ids post-fixed by a "+"
1045 for ascending sort order or a "-" for descending sort order. The
1046 sort IDs are separated by commas. For example:
1047 report.list.sort=due+,priority-,start.active-,project+
1049 Additionally, after the "+" or "-", there can be a solidus "/"
1051 which indicates that there are breaks after the column values
1052 change. For example:
1053 report.minimal.sort=project+/,description+
1055 This sort order now specifies that there is a listing break
1057 between each project. A listing break is simply a blank line,
1058 which provides a visual grouping.
1059 A special sort value of "none" indicates that no sorting is
1061 required, and tasks will be presented in the order (if any) in
1062 which they are selected.
1063 report.X.filter
1066 This adds a filter to the report X so that only tasks matching
1067 the filter criteria are displayed in the generated report.
1068 report.X.dateformat
1071 This adds a dateformat to the report X that will be used by the
1072 "due date" column. If it is not set then dateformat.report and
1073 dateformat will be used in this order. See the DATES section for
1074 details on the sequence placeholders.
1075 report.X.annotations
1078 This adds the possibility to control the output of annotations
1079 for a task in a report. Deprecated. Use the description column
1080 with a format (e.g., description.count) instead.
1081 Taskwarrior comes with a number of predefined reports, which are:
1084 next Lists the most important tasks.
1087 long Lists all pending tasks and all data, matching the specified
1090 criteria.
1091 list Lists all tasks matching the specified criteria.
1094 ls Short listing of all tasks matching the specified criteria.
1097 minimal
1100 Minimal listing of all tasks matching the specified criteria.
1101 newest Shows the newest tasks.
1104 oldest Shows the oldest tasks.
1107 overdue
1110 Lists overdue tasks matching the specified criteria.
1111 active Lists active tasks matching the specified criteria.
1114 completed
1117 Lists completed tasks matching the specified criteria.
1118 recurring
1121 Lists recurring tasks matching the specified criteria.
1122 waiting
1125 Lists all waiting tasks matching the specified criteria.
1126 all Lists all tasks matching the specified criteria.
1129 blocked
1132 Lists all tasks that have dependencies.
1133 USER DEFINED ATTRIBUTES
1136 User defined attributes (UDAs) are an extension mechanism that allows
1137 you to define new attributes for Taskwarrior to store and display. One
1138 such example is an 'estimate' attribute that could be used to store
1139 time estimates associated with a task. This 'estimate' attribute is not
1140 built in to Taskwarrior, but with a few simple configuration settings
1141 you can instruct Taskwarrior to store this item, and provide access to
1142 it for custom reports and filters.
1143 This allows you to augment Taskwarrior to accommodate your workflow, or
1145 bend the rules and use Taskwarrior to store and synch data that is not
1146 necessarily task-related.
1147 One important restriction is that because this is an open system that
1149 allows the definition of any new attribute, Taskwarrior cannot under‐
1150 stand the meaning of that attribute. So while Taskwarrior will faith‐
1151 fully store, modify, report, sort and filter your UDA, it does not
1152 understand anything about it. For example if you define a UDA named
1153 'estimate', Taskwarrior will not know that this value is weeks, hours,
1154 minutes, money, or some other resource count.
1155 uda.<name>.type=string|numeric|date|duration
1158 Defines a UDA called '<name>', of the specified type.
1159 uda.<name>.label=<column heading>
1162 Provides a default report label for the UDA called '<name>'.
1163 uda.<name>.values=A,B,C
1166 For type 'string' UDAs only, this provides a comma-separated
1167 list of acceptable values. In this example, the '<name>' UDA may
1168 only contain values 'A', 'B', or 'C', but may also contain no
1169 value.
1170 Note that the order of the value is important, and denotes the
1172 sort order from highest ('A') to lowest ('C').
1173 Note that a blank value is permitted.
1175 uda.<name>.default=...
1178 Provides a default value for the UDA called '<name>'.
1179 Example 'estimate' UDA
1182 This example shows an 'estimate' UDA that stores specific values
1183 for the size of a task. Note the blank value after 'trivial'.
1184 uda.estimate.type=string
1186 uda.estimate.label=Size Estimate
1187 uda.estimate.values=huge,large,medium,small,trivial,
1188 Note that the value are sorted
1190 huge > large > medium > small > trivial > ''
1192 CONTEXT
1195 Context setting is a mechanism which allows the user to set a permanent
1196 filter, thus avoiding the need to specify one filter repeatedly. More
1197 details on usage can be found in the task(1) man page.
1198 The current context is stored in the .taskrc file, along with defini‐
1200 tions for all user provided contexts.
1201 context=<name>
1204 Stores the value of the currently active context.
1205 context.<name>=<filter>
1208 Stores the definition of the context with the name <name>.
1209 SYNC
1212 These configuration settings are used to connect and sync tasks with
1213 the task server.
1214 taskd.server=<host>:<port>
1217 Specifies the hostname and port of the Taskserver. Hostname may
1218 be an IPv4 or IPv6 address, or domain. Port is an integer.
1219 taskd.credentials=<organization>/<user>/<key>
1222 User identification for the Taskserver, which includes a private
1223 key.
1224 taskd.certificate=<path>
1227 Specifies the path to the client certificate used for identifi‐
1228 cation with the Taskserver.
1229 taskd.key=<path>
1232 Specifies the path to the client key used for encrypted communi‐
1233 cation with the Taskserver.
1234 taskd.ca=<path>
1237 Specifies the path to the CA certificate in the event that your
1238 Taskserver is using a self-signed certificate. Optional.
1239 taskd.trust=strict|ignore hostname|allow all
1242 This settings allows you to override the trust level when server
1243 certificates are validated. With "allow all", the server cer‐
1244 tificate is trusted automatically. With "ignore hostname", the
1245 server certificate is verified but the hostname is ignored. With
1246 "strict", the server certificate is verified. Default is
1247 "strict", which requires full validation.
1248 taskd.ciphers=NORMAL
1251 Override of the cipher selection. The set of ciphers used by TLS
1252 may be controlled by both server and client. There must be some
1253 overlap between client and server supported ciphers, or communi‐
1254 cation cannot occur. Default is "NORMAL". See GnuTLS documenta‐
1255 tion for full details.
1256
1259 Copyright (C) 2006 - 2016 P. Beckingham, F. Hernandez.
1260 This man page was originally written by Federico Hernandez.
1262 Taskwarrior is distributed under the MIT license. See http://www.open‐
1264 source.org/licenses/mit-license.php for more information.
1265
1268 task(1), task-color(5), task-sync(5)
1269 For more information regarding Taskwarrior, see the following:
1271 The official site at
1274 <http://taskwarrior.org>
1275 The official code repository at
1278 <https://git.tasktools.org/scm/tm/task.git>
1279 You can contact the project by emailing
1282 <support@taskwarrior.org>
1283
1286 Bugs in Taskwarrior may be reported to the issue-tracker at
1287 <https://bug.tasktools.org/>
1288task 2.5.1 2016-02-24 taskrc(5)