From 3a035a7d1d3531999f4ccc66fcd047a82a57461b Mon Sep 17 00:00:00 2001 From: Paul Beckingham Date: Sun, 5 Apr 2015 23:37:43 -0400 Subject: [PATCH] TW-1590: syntax of rcfile not documented (whitespace, line continuation) - Updated top of the taskrc(5) man page with a description of the file syntax. (thanks to Scott M). --- AUTHORS | 1 + ChangeLog | 2 ++ doc/man/taskrc.5.in | 59 +++++++++++++++++++++++++++------------------ 3 files changed, 39 insertions(+), 23 deletions(-) diff --git a/AUTHORS b/AUTHORS index 61e6b2bad..eabaaf26d 100644 --- a/AUTHORS +++ b/AUTHORS @@ -246,3 +246,4 @@ suggestions: Taisuke Hachimura Martin Alexandre de Verteuil + Scott M diff --git a/ChangeLog b/ChangeLog index 5c68e9f8c..fca16dee7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -21,6 +21,8 @@ (thanks to Jochen Sprickerhof). - TW-1588 Most Export scripts cannot deal with new export format (thanks to Scott Carter). +- TW-1590 syntax of rcfile not documented (whitespace, line continuation) + (thanks to Scott M). - Setting 'bulk' to zero is interpreted as infinity, which means there is no amount of changes that is considered dangerous (thanks to Tomas Babej). - Disable hooks in bash completion script. Hooks were previously able to diff --git a/doc/man/taskrc.5.in b/doc/man/taskrc.5.in index e6e593f11..c72e09e32 100644 --- a/doc/man/taskrc.5.in +++ b/doc/man/taskrc.5.in @@ -11,7 +11,7 @@ taskrc \- Configuration details for the task(1) command .B TASKRC=/.taskrc task ... .SH DESCRIPTION -.B taskwarrior +.B Taskwarrior obtains its configuration data from a file called .I .taskrc \&. This file is normally located in the user's home directory: @@ -55,37 +55,50 @@ default, sample .I .taskrc file in the user's home directory. -The taskwarrior configuration file consists of a series of assignments in each -line. The assignments have the syntax: +The .taskrc file follows a very simply syntax defining name/value pairs: .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. - -The configuration file supports UTF8 as well as JSON encoding, such as \\uNNNN. +There may be whitespace around , '=' and , and it is ignored. +Whitespace within the is left intact. +Whitespace is not permitted in comma-separated lists. +The entry must be on a single line, no continuations. +Values support UTF8 as well as JSON encoding, such as \\uNNNN. Note that taskwarrior is flexible about the values used to represent Boolean items. You can use "on", "yes", "y", "1" and "true". Anything else means "off". +.RS +include +.RE + +There may be whitespace around 'include' and . The file may be an +absolute or relative path, and the special character '~' is expanded to mean +$HOME. +The entry must be on a single line, no continuations. + +.RS +# +.RE + +A comment consists of the character '#', and extends from the '#' to the end +of the line. There is no way to comment a multi-line block. There may be +blank lines. + +Almost every value has a default setting, and an empty .taskrc file is one +that makes use of every default. The contents of the .taskrc file therefore +represent overrides of the default values. To remove a default value completely +there must be an entry like this: + +.RS + = +.RE + +This entry overrides the default value with a blank value. + .SH EDITING You can edit your .taskrc file by hand if you wish, or you can use the 'config' command. To permanently set a value in your .taskrc file, use this command: