1taskrc(5) User Manuals taskrc(5)
2
6 taskrc - Configuration file for the task(1) command
7
10 $HOME/.taskrc
11 task rc:<directory-path>/.taskrc
12
15 taskwarrior obtains its configuration data from a file called .taskrc .
16 This file is normally located in the user's home directory:
17 $HOME/.taskrc
19 The default location can be overridden using the rc: attribute when
21 running task:
22 $ task rc:<directory-path>/.taskrc
24 Individual option can be overridden by using the rc.<name>: attribute
26 when running task:
27 $ task rc.<name>:<value> ...
29 If taskwarrior is run without an existing configuration file it will
31 ask if it should create a default, sample .taskrc file in the user's
32 home directory.
33 The taskwarrior configuration file consists of a series of "assign‐
35 ments" in each line. The "assignments" have the syntax:
36 <name-of-configuration-variable>=<value-to-be-set>
38 where:
40 <name-of-configuration-variable>
42 is one of the variables described below
43 <value-to-be-set>
46 is the value the variable is to be set to.
47 and set a configuration variable to a certain value. The equal sign
49 ("=") is used to separate the variable name from the value to be set.
50 The hash mark, or pound sign ("#") is used as a "comment" character. It
52 can be used to annotate the configuration file. All text after the
53 character to the end of the line is ignored.
54 Note that taskwarrior is flexible about the values used to represent
56 Boolean items. You can use "on", "yes", "y", "1", "true", "t", "+",
57 "enabled". Anything else means "off".
58
61 You can edit your .taskrc file by hand if you wish, or you can use the
62 'config' command. To permanently set a value in your .taskrc file, use
63 this command:
64 $ task config nag "You have higher priority tasks!"
66 To delete an entry, use this command:
68 $ task config nag
70 Taskwarrior will then use the default value. To explicitly set a value
72 to blank, and therefore avoid using the default value, use this com‐
73 mand:
74 $ task config nag ""
76 Taskwarrior will also display all your settings with this command:
78 $ task config
80 and in addition, will also perform a check of all the values in the
82 file, warning you of anything it finds amiss.
83
86 The .taskrc can include other files containing configuration settings
87 by using the include statement:
88 include <path/to/the/configuration/file/to/be/included>
90 By using include files you can divide your main configuration file into
92 several ones containing just the relevant configuration data like col‐
93 ors, etc.
94 There are two excellent uses of includes in your .taskrc, shown here:
96 include /usr/local/share/doc/task/rc/holidays-US.rc
98 include /usr/local/share/doc/task/rc/dark-16.theme
99 This includes two standard files that are distributed with taskwarrior,
101 which define a set of US holidays, and set up a 16-color theme to use,
102 to color the reports and calendar.
103
106 Valid variable names and their default values are:
107 FILES
110 data.location=$HOME/.task
111 This is a path to the directory containing all the taskwarrior
112 files. By default, it is set up to be ~/.task, for example:
113 /home/paul/.task
114 Note that you can use the ~ shell meta character, which will be
116 properly expanded.
117 locking=on
120 Determines whether to use file locking when accessing the pend‐
121 ing.data and completed.data files. Defaults to "on". Solaris
122 users who store the data files on an NFS mount may need to set
123 locking to "off". Note that there is danger in setting this
124 value to "off" - another program (or another instance of task)
125 may write to the task.pending file at the same time.
126 gc=on Can be used to temporarily suspend garbage collection (gc), so
129 that task IDs don't change. Note that this should be used in
130 the form of a command line override (task rc.gc=off ...), and
131 not permanently used in the .taskrc file, as this significantly
132 affects performance.
133 TERMINAL
136 curses=on
137 Determines whether to use ncurses to establish the size of the
138 window you are using, for text wrapping.
139 defaultwidth=80
142 The width of tables used when ncurses support is not available.
143 Defaults to 80. If set to 0, is interpreted as infinite width,
144 therefore with no word-wrapping; useful when redirecting report
145 output to a file for subsequent manipulation.
146 editor=vi
149 Specifies which text editor you wish to use for when the task
150 edit <ID> command is used. Taskwarrior will first look for this
151 configuration variable. If found, it is used. Otherwise it will
152 look for the $VISUAL or $EDITOR environment variables, before it
153 defaults to using "vi".
154 edit.verbose=on
157 When set to on (the default), helpful explanatory comments are
158 added to the edited file when using the "task edit ..." command.
159 Setting this to off means that you would see a smaller, more
160 compact representation of the task, with no help text.
161 MISCELLANEOUS
164 locale=en-US
165 The locale is a combination of ISO 639-1 language code and ISO
166 3166 country code. If not specified, will assume en-US. If
167 specified, taskwarrior will locate the correct file of localized
168 strings and proceed. It is an error to specify a locale for
169 which there is no strings file.
170 verbose=yes
173 Controls some of the verbosity of taskwarrior.
174 confirmation=yes
177 May be "yes" or "no", and determines whether taskwarrior will
178 ask for confirmation before deleting a task, performing bulk
179 changes, or the undo command. The default value is "yes". Con‐
180 sider leaving this setting as "no", for safety.
181 echo.command=yes
184 May be "yes" or "no", and causes the display of the ID and
185 description of any task when you run the start, stop, do, undo
186 or delete commands. The default value is "yes".
187 annotations=full
190 report.X.annotations=full
192 Controls the display of annotations in reports. Defaults to full
193 - all annotations are displayed. Set to "sparse" only the last
194 (newest) annotation is displayed and if there are more than one
195 present for a task a "+" sign is added to the description. Set
196 to "none" the output of annotations is disabled and a "+" sign
197 will be added if there are any annotations present. The default
198 value is "full".
199 next=2 Is a number, defaulting to 2, which is the number of tasks for
202 each project that are shown in the task next command.
203 bulk=2 Is a number, defaulting to 2. When more than this number of
206 tasks are modified in a single command, confirmation will be
207 required, unless the confirmation variable is "no".
208 This is useful for preventing large-scale unintended changes.
210 nag=You have higher priority tasks.
213 This may be a string of text, or blank. It is used as a prompt
214 when a task is started or completed that is not considered high
215 priority. The "task next" command lists important tasks, and
216 completing one of those does not generate this nagging. Default
217 value is: You have higher priority tasks. It is a gentle
218 reminder that you are contradicting your own priority settings.
219 complete.all.projects=yes
222 May be yes or no, and determines whether the tab completion
223 scripts consider all the project names you have used, or just
224 the ones used in active tasks. The default value is "no".
225 list.all.projects=yes
228 May be yes or no, and determines whether 'projects' command
229 lists all the project names you have used, or just the ones used
230 in active tasks. The default value is "no".
231 complete.all.tags=yes
234 May be yes or no, and determines whether the tab completion
235 scripts consider all the tag names you have used, or just the
236 ones used in active tasks. The default value is "no".
237 list.all.tags=yes
240 May be yes or no, and determines whether the 'tags' command
241 lists all the tag names you have used, or just the ones used in
242 active tasks. The default value is "no".
243 search.case.sensitive=yes
246 May be yes or no, and determines whether keyword lookup and sub‐
247 stitutions on the description and annotations are done in a case
248 sensitive way. Defaults to yes.
249 The default value is off, because this advanced feature could
251 cause confusion among users that are not comfortable with regu‐
252 lar expressions.
253 xterm.title=no
256 Sets the xterm window title when reports are run. Defaults to
257 off.
258 _forcecolor=no
261 Taskwarrior shuts off color automatically when the output is not
262 sent directly to a TTY. For example, this command:
263 $ task list > file
265 will not use any color. To override this, use:
267 $ task rc._forcecolor=yes list > file
269 blanklines=yes
272 Turning this value off causes taskwarrior to generate a more
273 vertically compact output.
274 shell.prompt=task>
277 The task shell command uses this value as a prompt. You can
278 change it to any string you like.
279 active.indicator=*
282 The character or string to show in the active column. Defaults
283 to *.
284 tag.indicator=+
287 The character or string to show in the tag_indicator column.
288 Defaults to +.
289 recurrence.indicator=R
292 The character or string to show in the recurrence_indicator col‐
293 umn. Defaults to R.
294 recurrence.limit=1
297 The number of future recurring tasks to show. Defaults to 1.
298 For example, if a weekly recurring task is added with a due date
299 of tomorrow, and recurrence.limit is set to 2, then a report
300 will list 2 pending recurring tasks, one for tomorrow, and one
301 for a week from tomorrow.
302 undo.style=side
305 When the 'undo' command is run, taskwarrior presents a before
306 and after comparison of the data. This can be in either the
307 'side' style, which compares values side-by-side in a table, or
308 'diff' style, which uses a format similar to the 'diff' command.
309 burndown.bias=0.666
312 The burndown bias is a number that lies within the range 0 <=
313 bias <= 1. The bias is the fraction of the find/fix rates
314 derived from the short-term data (last 25% of the report) versus
315 the longer term data (last 50% of the report). A value of 0.666
316 (the default) means that the short-term rate has twice the
317 weight of the longer-term rate. The calculation is as follows:
318 rate = (long-term-rate * (1 - bias)) + (short-term-rate *
320 bias)
321 debug=off
324 Taskwarrior has a debug mode that causes diagnostic output to be
325 displayed. Typically this is not something anyone would want,
326 but when reporting a bug, debug output can be useful. It can
327 also help explain how the command line is being parsed, but the
328 information is displayed in a developer-friendly, not a user-
329 friendly way.
330 alias.rm=delete
333 Taskwarrior supports command aliases. This alias provides an
334 alternate name (rm) for the delete command. You can use aliases
335 to provide alternate names for any of the commands. Several
336 commands you may use are actually aliases - the 'history'
337 report, for example, or 'export'.
338 DATES
341 dateformat=m/d/Y
342 dateformat.report=m/d/Y
344 dateformat.holiday=YMD
346 dateformat.annotation=m/d/Y
348 report.X.dateformat=m/d/Y
350 This is a string of characters that define how taskwarrior for‐
351 mats date values. The precedence order for the configuration
352 variable is report.X.dateformat then dateformat.report then
353 dateformat. While report.X.dateformat only formats the due date
354 in reports, dateformat.report formats the due date both in
355 reports and "task info". If both of these are not set then
356 dateformat will be applied to the due date. Entered dates as
357 well as all other displayed dates in reports are formatted
358 according to dateformat.
359 The default value is: m/d/Y. The string should contain the
361 characters:
362 m minimal-digit month, for example 1 or 12
364 d minimal-digit day, for example 1 or 30
365 y two-digit year, for example 09
366 D two-digit day, for example 01 or 30
367 M two-digit month, for example 01 or 12
368 Y four-digit year, for example 2009
369 a short name of weekday, for example Mon or Wed
370 A long name of weekday, for example Monday or Wednesday
371 b short name of month, for example Jan or Aug
372 B long name of month, for example January or August
373 V weeknumber, for example 03 or 37
374 H two-digit hour, for example 03 or 11
375 N two-digit minutes, for example 05 or 42
376 S two-digit seconds, for example 07 or 47
377 The string may also contain other characters to act as spacers,
379 or formatting. Examples for other values of dateformat:
380 d/m/Y would use for input and output 24/7/2009
382 yMD would use for input and output 090724
383 M-D-Y would use for input and output 07-24-2009
384 Examples for other values of dateformat.report:
386 a D b Y (V) would do an output as "Fri 24 Jul 2009 (30)"
388 A, B D, Y would do an output as "Friday, July 24,
389 2009"
390 vV a Y-M-D would do an output as "v30 Fri 2009-07-24"
391 yMD.HN would do an output as "110124.2342"
392 m/d/Y H:N would do an output as "1/24/2011 10:42"
393 a D b Y H:N:S would do and output as "Mon 24 Jan 2011
394 11:19:42"
395 weekstart=Sunday
398 Determines the day a week starts. Valid values are Sunday or
399 Monday only. The default value is "Sunday".
400 displayweeknumber=yes
403 Determines if week numbers are displayed when using the "task
404 calendar" command. The week number is dependent on the day a
405 week starts. The default value is "yes".
406 due=7 This is the number of days into the future that define when a
409 task is considered due, and is colored accordingly. The default
410 value is 7.
411 calendar.details=sparse
414 If set to full running "task calendar" will display the details
415 of tasks with due dates that fall into the calendar period. The
416 corresponding days will be color-coded in the calendar. If set
417 to sparse only the corresponding days will be color coded and no
418 details will be displayed. The displaying of due dates with
419 details is turned off by setting the variable to none. The
420 default value is "sparse".
421 calendar.details.report=list
424 The report to run when displaying the details of tasks with due
425 date when running the "task calendar" command. The default
426 value is "list".
427 calendar.offset=off
430 If "on" the first month in the calendar report is effectively
431 changed by the offset value specified in calendar.offset.value.
432 It defaults to "off".
433 calendar.offset.value=-1
436 The offset value to apply to the first month in the calendar
437 report. The default value is "-1".
438 calendar.holidays=full
441 If set to full running "task calendar" will display holidays in
442 the calendar by color-coding the corresponding days. A detailed
443 list with the dates and names of the holidays is also shown. If
444 set to sparse only the days are color-coded and no details on
445 the holidays will be displayed. The displaying of holidays is
446 turned off by setting the variable to none. The default value
447 is "none".
448 Journal entries
451 journal.time=no
452 May be yes or no, and determines whether the 'start' and 'stop'
453 commands should record an annotation when being executed. The
454 default value is "no". The text of the corresponding annotations
455 is controlled by:
456 journal.time.start.annotation=Started task
459 The text of the annotation that is recorded when executing the
460 start command and having set journal.time.
461 journal.time.stop.annotation=Stopped task
464 The text of the annotation that is recorded when executing the
465 stop command and having set journal.time.
466 journal.info=on
469 When enabled, this setting causes a change log of each task to
470 be displayed by the 'info' command. Default value is "on".
471 Holidays
474 Holidays are entered either directly in the .taskrc file or via an
475 include file that is specified in .taskrc. For each holiday the name
476 and the date is required to be given:
477 holiday.towel.name=Day of the towel
479 holiday.towel.date=20100525
480 holiday.sysadmin.name=System Administrator Appreciation
481 Day
482 holiday.sysadmin.date=20100730
483 Dates are to be entered according to the setting in the datefor‐
485 mat.holiday variable.
486 The following holidays are computed automatically: Good Friday
488 (goodfriday), Easter (easter), Easter monday (eastermonday),
489 Ascension (ascension), Pentecost (pentecost). The date for these
490 holidays is the given keyword:
491 holiday.eastersunday.name=Easter
493 holiday.eastersunday.date=easter
494 Note that the taskwarrior distribution contains example holiday files
496 that can be included like this:
497 include /usr/local/share/doc/task/rc/holidays-US.rc
499 monthsperline=3
502 Determines how many months the "task calendar" command renders
503 across the screen. Defaults to however many will fit. If more
504 months than will fit are specified, taskwarrior will only show
505 as many that will fit.
506 DEPENDENCIES
509 dependency.reminder=on
510 Determines whether dependency chain violations generate
511 reminders.
512 dependency.confirm=yes
515 Determines whether dependency chain repair requires confirma‐
516 tion.
517 COLOR CONTROLS
520 color=on
521 May be "on" or "off". Determines whether taskwarrior uses color.
522 When "off", will use dashes (-----) to underline column head‐
523 ings.
524 fontunderline=on
527 Determines if font underlines or ASCII dashes should be used to
528 underline headers, even when color is enabled.
529 Taskwarrior has a number of coloration rules. They correspond to a
531 particular attribute of a task, such as it being due, or being active,
532 and specifies the automatic coloring of that task. A list of valid
533 colors, depending on your terminal, can be obtained by running the com‐
534 mand:
535 task color
537 Note that no default values are listed here - the defaults now
539 correspond to the dark-256.theme (Linux) and dark-16.theme
540 (other) theme values. The coloration rules are as follows:
541 color.due.today Task is due today
543 color.active Task is started, therefore active.
544 color.blocked Task is blocked by a dependency.
545 color.overdue Task is overdue (due some time prior to now).
546 color.due Task is coming due.
547 color.project.none Task does not have an assigned project.
548 color.tag.none Task has no tags.
549 color.tagged Task has at least one tag.
550 color.recurring Task is recurring.
551 color.pri.H Task has priority H.
552 color.pri.M Task has priority M.
553 color.pri.L Task has priority L.
554 color.pri.none Task has no priority.
555 To disable a coloration rule for which there is a default, set
557 the value to nothing, for example:
558 color.tagged=
559 See the task-color(5) man pages for color details.
561 Certain attributes like tags, projects and keywords can have their own
563 coloration rules.
564 color.tag.X=yellow
567 Colors any task that has the tag X.
568 color.project.X=on green
571 Colors any task assigned to project X.
572 color.keyword.X=on blue
575 Colors any task where the description or any annotation contains
576 X.
577 color.header=green
580 Colors any of the messages printed prior to the report output.
581 color.footnote=green
584 Colors any of the messages printed last.
585 color.summary.bar=on green
588 Colors the summary progress bar. Should consist of a background
589 color.
590 color.summary.background=on black
593 Colors the summary progress bar. Should consist of a background
594 color.
595 color.calendar.today=black on cyan
598 Color of today in calendar.
599 color.calendar.due=black on green
602 Color of days with due tasks in calendar.
603 color.calendar.due.today=black on magenta
606 Color of today with due tasks in calendar.
607 color.calendar.overdue=black on red
610 Color of days with overdue tasks in calendar.
611 color.calendar.weekend=bright white on black
614 Color of weekend days in calendar.
615 color.calendar.holiday=black on bright yellow
618 Color of holidays in calendar.
619 color.calendar.weeknumber=black on white
622 Color of weeknumbers in calendar.
623 color.alternate=on rgb253
626 Color of alternate tasks. This is to apply a specific color to
627 every other task in a report, which can make it easier to vis‐
628 ually separate tasks. This is especially useful when tasks are
629 displayed over multiple lines due to long descriptions or anno‐
630 tations.
631 color.history.add=on red
634 color.history.done=on green
635 color.history.delete=on yellow
636 Colors the bars on the ghistory report graphs. Defaults to red,
637 green and yellow bars.
638 color.burndown.pending=on red
641 color.burndown.started=on yellow
642 color.burndown.done=on green
643 Colors the bars on the burndown reports graphs. Defaults to
644 red, green and yellow bars.
645 color.undo.before=red
648 color.undo.after=green
649 Colors used by the undo command, to indicate the values both
650 before and after a change that is to be reverted.
651 color.sync.added=green
654 color.sync.changed=yellow
655 color.sync.rejected=red
656 Colors the output of the merge command.
657 rule.precedence.color=overdue,tag,project,keyword,active,...
660 This setting specifies the precedence of the color rules, from
661 highest to lowest. Note that the prefix 'color.' is omitted
662 (for brevity), and that any wildcard values (color.tag.XXX) is
663 shortened to 'tag', which places all specific tag rules at the
664 same precedence, again for brevity.
665 SHADOW FILE
668 shadow.file=$HOME/.task/shadow.txt
669 If specified, designates a file path that will be automatically
670 written to by taskwarrior, whenever the task database changes.
671 In other words, it is automatically kept up to date. The
672 shadow.command configuration variable is used to determine which
673 report is written to the shadow file. There is no color used in
674 the shadow file. This feature can be useful in maintaining a
675 current file for use by programs like GeekTool, Conky or Samur‐
676 ize.
677 shadow.command=list
680 This is the command that is run to maintain the shadow file,
681 determined by the shadow.file configuration variable. The format
682 is identical to that of default.command . Please see the corre‐
683 sponding documentation for that command.
684 shadow.notify=on
687 When this value is set to "on", taskwarrior will display a mes‐
688 sage whenever the shadow file is updated by some task command.
689 DEFAULTS
692 default.project=foo
693 Provides a default project name for the task add command, if you
694 don't specify one. The default is blank.
695 default.priority=M
698 Provides a default priority for the task add command, if you
699 don't specify one. The default is blank.
700 default.due=...
703 Provides a default due date for the task add command, if you
704 don't specify one. The default is blank.
705 default.command=list
708 Provides a default command that is run every time taskwarrior is
709 invoked with no arguments. For example, if set to:
710 default.command=list project:foo
712 then taskwarrior will run the "list project:foo" command if no
714 command is specified. This means that by merely typing
715 $ task
717 [task list project:foo]
718 ID Project Pri Description
720 1 foo H Design foo
721 2 foo Build foo
722 REPORTS
725 The reports can be customized by using the following configuration
726 variables. The output columns, their labels and the sort order can be
727 set using the corresponding variables for each report. Each report name
728 is used as a "command" name. For example
729 task overdue
732 report.X.description
735 The description for report X when running the "task help" com‐
736 mand.
737 report.X.columns
740 The columns that will be used when generating the report X.
741 Valid columns are: id, uuid, project, priority, priority_long,
742 entry, start, end, due, countdown, countdown_compact, age,
743 age_compact, active, tags, depends, description_only, descrip‐
744 tion, recur, recurrence_indicator, tag_indicator and wait. The
745 IDs are separated by commas.
746 report.X.labels
749 The labels for each column that will be used when generating
750 report X. The labels are a comma separated list.
751 report.X.sort
754 The sort order of the tasks in the generated report X. The sort
755 order is specified by using the column ids post-fixed by a "+"
756 for ascending sort order or a "-" for descending sort order. The
757 sort IDs are separated by commas. For example:
758 report.list.sort=due+,priority-,active-,project+
760 report.X.filter
763 This adds a filter to the report X so that only tasks matching
764 the filter criteria are displayed in the generated report.
765 report.X.dateformat
768 This adds a dateformat to the report X that will be used by the
769 "due date" column. If it is not set then dateformat.report and
770 dateformat will be used in this order. See the DATES section for
771 details on the sequence placeholders.
772 report.X.annotations
775 This adds the possibility to control the output of annotations
776 for a task in a report. See the annotations variable for details
777 on the possible values.
778 report.X.limit
781 An optional value to a report limiting the number of displayed
782 tasks in the generated report.
783 Taskwarrior comes with a number of predefined reports in its default
786 configuration file. These reports are:
787 long Lists all task, all data, matching the specified criteria.
790 list Lists all tasks matching the specified criteria.
793 ls Short listing of all tasks matching the specified criteria.
796 minimal
799 Minimal listing of all tasks matching the specified criteria.
800 newest Shows the newest tasks.
803 oldest Shows the oldest tasks.
806 overdue
809 Lists overdue tasks matching the specified criteria.
810 active Lists active tasks matching the specified criteria.
813 completed
816 Lists completed tasks matching the specified criteria.
817 recurring
820 Lists recurring tasks matching the specified criteria.
821 waiting
824 Lists all waiting tasks matching the specified criteria.
825 all Lists all tasks matching the specified criteria.
828 next Lists all tasks with upcoming due dates matching the specified
831 criteria.
832
835 Taskwarrior was written by P. Beckingham <paul@beckingham.net>.
836 Copyright (C) 2006 - 2011 P. Beckingham
837 This man page was originally written by Federico Hernandez.
839 Taskwarrior is distributed under the GNU General Public License. See
841 http://www.gnu.org/licenses/gpl-2.0.txt for more information.
842
845 task(1), task-tutorial(5), task-faq(5), task-color(5), task-sync(5)
846 For more information regarding taskwarrior, the following may be refer‐
848 enced:
849 The official site at
852 <http://taskwarrior.org>
853 The official code repository at
856 <git://tasktools.org/task.git/>
857 You can contact the project by writing an email to
860 <support@taskwarrior.org>
861
864 Bugs in taskwarrior may be reported to the issue-tracker at
865 <http://taskwarrior.org>
866task 1.9.4 2011-03-03 taskrc(5)