.TH taskrc 5 2010-01-03 "task 1.9.0" "User Manuals" .SH NAME taskrc \- Configuration file for the task(1) command .SH SYNOPSIS .B $HOME/.taskrc .br .B task rc:/.taskrc .SH DESCRIPTION .B task obtains its configuration data from a file called .I .taskrc \&. This file is normally located in the user's home directory: .RS $HOME/.taskrc .RE The default location can be overridden using the .I rc: attribute when running task: .RS $ task rc:/.taskrc .RE Individual option can be overridden by using the .I rc.: attribute when running task: .RS $ task rc.: ... .RE If .B task is run without an existing configuration file it will ask if it should create a default, sample .I .taskrc file in the user's home directory. The task configuration file consists of a series of "assignments" in each line. The "assignments" have the syntax: .RS = .RE where: .RS .TP is one of the variables described below .TP is the value the variable is to be set to. .RE and set a configuration variable to a certain value. The equal sign ("=") is used to separate the variable name from the value to be set. The hash mark, or pound sign ("#") is used as a "comment" character. It can be used to annotate the configuration file. All text after the character to the end of the line is ignored. .SH CONFIGURATION VARIABLES Valid variable names and their default values are: .SS FILES .TP .B data.location=$HOME/.task This is a path to the directory containing all the task files. By default, it is set up to be ~/.task, for example: /home/paul/.task .TP .B locking=on Determines whether task uses file locking when accessing the pending.data and completed.data files. Default to "on". Solaris users who store the task data files on an NFS mount may need to set locking to "off". Note that setting this value to "off" is dangerous. It means that another program may write to the task.pending file when task is attempting to do the same. .SS TERMINAL .TP .B curses=on Determines whether task uses ncurses to establish the size of the window you are using, for text wrapping. .TP .B defaultwidth=80 The width of tables used when ncurses support is not available. Defaults to 80. .TP .B editor=vi Specifies which text editor you wish to use for when the .B task edit command is used. Task will first look for this configuration variable. If found, it is used. Otherwise task will look for the $VISUAL or $EDITOR environment variables, before it defaults to using "vi". .SS MISCELLANEOUS .TP .B locale=en-US The locale is a combination of ISO 639-1 language code and ISO 3166 country code. If not specified, task will assume en-US. If specified, task will locate the correct file of localized strings and proceed. It is an error to specify a locale for which there is no strings file. .TP .B confirmation=yes May be "yes" or "no", and determines whether task will ask for confirmation before deleting a task or doing bulk changes. .TP .B echo.command=yes May be "yes" or "no", and causes task to display the ID and description of any task when you run the start, stop, do, undo or delete commands. The default value is "yes". .TP .B annotations=full .TP .B report.X.annotations=full Controls the output of annotations in reports. Defaults to full - all annotations are displayed. Set to "sparse" only the last (youngest) annotation is displayed and if there are more than one present for a task a "+" sign is added to the description. Set to "none" the output of annotations is disabled and a "+" sign will be added if there are any annotations present. .TP .B next=2 Is a number, defaulting to 2, which is the number of tasks for each project that are shown in the .B task next command. .TP .B bulk=2 Is a number, defaulting to 2. When more than this number of tasks are modified in a single command, confirmation will be required, unless the .B confirmation variable is "no". .TP .B nag=You have higher priority tasks. This may be a string of text, or blank. It is used as a prompt when a task is completed that is not considered high priority. The "task next" command lists important tasks, and completing one of those does not generate this nagging. Default value is: You have higher priority tasks. .TP .B complete.all.projects=yes May be yes or no, and determines whether the tab completion scripts consider all the project names you have used, or just the ones used in active tasks. .TP .B complete.all.tags=yes May be yes or no, and determines whether the tab completion scripts consider all the tag names you have used, or just the ones used in active tasks. .SS DATES .TP .B dateformat=m/d/Y .TP .B dateformat.report=m/d/Y .TP .B dateformat.holiday=YMD .TP .B report.X.dateformat=m/d/Y This is a string of characters that define how task formats dates. The precedence order for the configuration variable is report.X.dateformat then reportdateformat then dateformat. While report.X.dateformat only formats the due date in reports, does reportdateformat format the due date both in reports and "task info". If both of these are not set then dateformat will be applied to the due date. Input dates as well as all other dates in reports are formatted according to dateformat. The default value is: m/d/Y. The string should contain the characters .RS .RS m minimal-digit month, for example 1 or 12 .br d minimal-digit day, for example 1 or 30 .br y two-digit year, for example 09 .br D two-digit day, for example 01 or 30 .br M two-digit month, for example 01 or 12 .br Y four-digit year, for example 2009 .br a short name of weekday, for example Mon or Wed .br A long name of weekday, for example Monday or Wednesday .br b short name of month, for example Jan or Aug .br B long name of month, for example January or August .br V weeknumber, for example 03 or 37 .RE .RE .RS The string may also contain other characters to act as spacers, or formatting. Examples for other values of dateformat: .RE .RS .RS .br d/m/Y would use for input and output 24/7/2009 .br yMD would use for input and output 090724 .br M-D-Y would use for input and output 07-24-2009 .RE .RE .RS Examples for other values of reportdateformat: .RE .RS .RS .br a D b Y (V) would do an output as "Fri 24 Jul 2009 (30)" .br A, B D, Y would do an output as "Friday, July 24, 2009" .br vV a Y-M-D would do an output as "v30 Fri 2009-07.24" .RE .RE .TP .B weekstart=Sunday Determines the day a week starts. Valid values are Sunday or Monday only. .TP .B displayweeknumber=yes Determines if week numbers are displayed when using the "task calendar" command. The week number is dependent on the day a week starts. .TP .B due=7 This is the number of days into the future that define when a task is considered due, and is colored accordingly. Defaults to 7. .TP .B calendar.details=sparse If set to full running "task calendar" will display the details of tasks with due dates that fall into the calendar period. The corresponding days will be color-coded in the calendar. If set to sparse only the corresponding days will be color coded and no details will be displayed. The displaying of due dates with details is turned off by setting the variable to none. .TP .B calendar.details.report=list The report to run when displaying the details of tasks with due date when running the "task calendar" command. .TP .B calendar.holidays=full If set to full running "task calendar" will display holidays in the calendar by color-coding the corresponding days. A detailed list with the dates and names of the holidays is also shown. If set to sparse only the days are color-coded and no details on the holidays will be displayed. The displaying of holidays is turned off by setting the variable to none. .TP .B Holidays Holidays are entered either directly in the .taskrc file or via an include file that is specified in .taskrc. For each holiday the name and the date is required to be given: .RS .RS .br holiday.towel.name=Day of the towel .br holiday.towel.date=20100525 .br holiday.sysadmin.name=System Administrator Appreciation Day .br holiday.sysadmin.date=20100730 .RE .RE .RS Dates are to be entered according to the setting in the dateformat.holiday variable. .RE .TP .B monthsperline=2 Determines how many months the "task calendar" command renders across the screen. Defaults to however many will fit. If more months that will fit are specified, task will only show as many that will fit. .SS COLOR CONTROLS .TP .B color=on May be "on" or "off". Determines whether task uses color. When "off", task will use dashes (-----) to underline column headings. .TP .B fontunderline=on Determines if font underlines or ASCII dashes should be used to underline headers. Task has a number of coloration rules. They correspond to a particular attribute of a task, such as it being due, or being active, and specifies the automatic coloring of that task. A list of valid color, depending on your terminal, can be obtained by running the command .RS .B task color .RE .RS The coloration rules and their defaults are: .RE .RS .RS .B color.overdue=bold_red The color for overdue tasks. .br .B color.due=bold_yellow The color of due tasks. .br .B color.pri.H=bold The color of priority:H tasks. .br .B color.pri.M=on_yellow The color of priority:M tasks. .br .B color.pri.L=on_green The color of priority:L tasks. .br .B color.pri.none=white on_blue The color of priority: tasks. .br .B color.active=bold_cyan The color of active tasks. .br .B color.tagged=yellow The color of tagged tasks. .br .B color.recurring=on_red The color for recurring tasks. .RE .RE .RS The value for the coloration rules may be one optional foreground color and one optional color. For example, the value may be .RE .RS .RS bold_red on_bright_yellow .RE .RE .RS Certain attributes like tags, projects and keywords can also have their own coloration rules. .RE .RS .TP .B color.tag.X=yellow Colors any task that has the tag X. .TP .B color.project.X=on_green Colors any task assigned to project X. .TP .B color.keyword.X=on_blue Colors any task where the description contains X. .TP .B color.header=green Colors any of the messages printed prior to the report output. .TP .B color.message=green Colors any of the messages printed after the report output. .TP .B color.footnote=green Colors any of the messages printed last. .TP .B color.calendar.today=black on cyan Color of today in calendar. .TP .B color.calendar.due=black on green Color of days with due tasks in calendar. .TP .B color.calendar.overdue=black on red Color of days with overdue tasks in calendar. .TP .B color.calendar.weekend=bright white on black Color of weekend days in calendar. .TP .B color.calendar.holiday=black on bright yellow Color of holidays in calendar. .TP .B color.calendar.weeknumber=black on white Color of weeknumbers in calendar. .RE .SS SHADOW FILE .TP .B shadow.file=$HOME/.task/shadow.txt If specified, designates a file path that will be automatically written to by task, whenever the task database changes. In other words, it is automatically kept up to date. The shadow.command configuration variable is used to determine which report is written to the shadow file. There is no color used in the shadow file. This feature can be useful in maintaining a current file for use by programs like GeekTool, Conky or Samurize. .TP .B shadow.command=list This is the command that is run to maintain the shadow file, determined by the .I shadow.file configuration variable. The format is identical to that of .I default.command \&. Please see the corresponding documentation for that command. .TP .B shadow.notify=on When this value is set to "on", task will display a message whenever the shadow file is updated by some task command. .SS DEFAULTS .TP .B default.project=foo Provides a default project name for the .I task add command. .TP .B default.priority=M Provides a default priority for the .I task add command. .TP .B default.command=list Provides a default command that is run every time task is invoked with no arguments. For example, if set to: .RS .RS default.command=list project:foo .RE .RE .RS then task will run the "list project:foo" command if no command is specified. This means that by merely typing .RE .RS .RS $ task .br [task list project:foo] .br \& .br ID Project Pri Description 1 foo H Design foo 2 foo Build foo .RE .RE .SS REPORTS The reports can be customized by using the following configuration variables. The output columns, their labels and the sort order can be set using the corresponding variables for each report. Each report name is used as a "command" name. For example .TP .B task overdue .TP .B report.X.description The description for report X when running the "task help" command. .TP .B report.X.columns The columns that will be used when generating the report X. Valid columns are: id, uuid, project, priority, entry, start, due, recur, recur_indicator, age, age_compact, active, tags, tag_indicator, description, description_only. The IDs are separated by commas. .TP .B report.X.labels The labels for each column that will be used when generating report X. The labels are a comma separated list. .TP .B report.X.sort The sort order of the tasks in the generated report X. The sort order is specified by using the column ids post-fixed by a "+" for ascending sort order or a "-" for descending sort order. The sort IDs are separated by commas .TP .B report.X.filter This adds a filter to the report X so that only tasks matching the filter criteria are displayed in the generated report. .TP .B report.X.dateformat This adds a dateformat to the report X that will be used by the "due date" column. If it is not set then reportdateformat and dateformat will be used in this order. See the .B DATES section for details on the sequence placeholders. .TP .B report.X.annotations GThis adds the possibility to control the output of annotations for a task in a report. See the .B annotations variable for details on the possible values. .TP .B report.X.limit An optional value to a report limiting the number of displayed tasks in the generated report. .TP Task comes with a number of predefined reports in its default configuration file. These reports are: .TP .B long Lists all task, all data, matching the specified criteria. .TP .B list Lists all tasks matching the specified criteria. .TP .B ls Minimal listing of all tasks matching the specified criteria. .TP .B newest Shows the newest tasks. .TP .B oldest Shows the oldest tasks. .TP .B overdue Lists overdue tasks matching the specified criteria. .TP .B active Lists active tasks matching the specified criteria. .TP .B completed Lists completed tasks matching the specified criteria. .TP .B recurring Lists recurring tasks matching the specified criteria. .TP .B waiting Lists all waiting tasks matching the specified criteria. .TP .B all Lists all tasks matching the specified criteria. .TP .B next Lists all tasks with upcoming due dates matching the specified criteria. .SH "CREDITS & COPYRIGHTS" task was written by P. Beckingham . .br Copyright (C) 2006 \- 2010 P. Beckingham This man page was originally written by Federico Hernandez. task is distributed under the GNU General Public License. See http://www.gnu.org/licenses/gpl-2.0.txt for more information. .SH SEE ALSO .BR task(1), .BR task-tutorial(5), .BR task-faq(5) .BR task-color(5) For more information regarding task, the following may be referenced: .TP The official site at .TP The official code repository at .TP You can contact the project by writing an email to .SH REPORTING BUGS .TP Bugs in task may be reported to the issue-tracker at