GothenburgBitFactory/taskwarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/taskwarrior.git synced 2025-06-26 10:54:26 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Properly tag monospaced text in man pages. (Improves HTML rendering) (#3509)

Browse source 
This would be immediately useful to improve the rendering of the man
pages in third-party websites such as manned.org and the arch man pagesk
- https://mankier.com/1/task
- https://man.archlinux.org/man/task.1

The regular console output, or websites which render the manpage in
monospaced fonts, will not be affected by this change.

This change could also help with eventually rendering the manpages in
the documentation website, and having a mix of monospaced and variable
width fonts.

To test the HTML output:
```bash
git clone git@github.com:jacksonp/manner.git # used by ManKier
./manner/manner.php task.1.in >| task.1.html && $BROWSER task.1.html
```

Co-authored-by: Sebastian Carlos <sebastiancarlos@gmail.com>
This commit is contained in:
Sebastian Carlos 2024-06-24 15:00:12 -03:00 • committed by GitHub
parent 71becf0185
commit 910860ae1c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 436 additions and 313 deletions
Download patch file Download diff file Expand all files Collapse all files

74
doc/man/task-color.5.in
View file

@ -8,14 +8,18 @@ It should be mentioned that Taskwarrior is aware of whether its output is going
to a terminal, or to a file or through a pipe. When Taskwarrior output goes to to a terminal, or to a file or through a pipe. When Taskwarrior output goes to
a terminal, color is desirable, but consider the following command: a terminal, color is desirable, but consider the following command:
.nf
$ task list > file.txt $ task list > file.txt
.fi
Do we really want all those color control codes in the file? Taskwarrior Do we really want all those color control codes in the file? Taskwarrior
assumes that you do not, and temporarily sets color to 'off' while generating assumes that you do not, and temporarily sets color to 'off' while generating
the output. This explains the output from the following command: the output. This explains the output from the following command:
.nf
$ task show | grep '^color ' $ task show | grep '^color '
color off color off
.fi
it always returns 'off', no matter what the setting, because the output is being it always returns 'off', no matter what the setting, because the output is being
sent to a pipe. sent to a pipe.
@ -23,20 +27,26 @@ sent to a pipe.
If you wanted those color codes, you can override this behavior by setting the If you wanted those color codes, you can override this behavior by setting the
_forcecolor variable to on, like this: _forcecolor variable to on, like this:
.nf
$ task config _forcecolor on $ task config _forcecolor on
$ task config | grep '^color ' $ task config | grep '^color '
color on color on
.fi
or by temporarily overriding it like this: or by temporarily overriding it like this:
.nf
$ task rc._forcecolor=on config | grep '^color ' $ task rc._forcecolor=on config | grep '^color '
color on color on
.fi
.SH AVAILABLE COLORS .SH AVAILABLE COLORS
Taskwarrior has a 'color' command that will show all the colors it is capable of Taskwarrior has a 'color' command that will show all the colors it is capable of
displaying. Try this: displaying. Try this:
.nf
$ task color $ task color
.fi
The output cannot be replicated here in a man page, but you should see a set of The output cannot be replicated here in a man page, but you should see a set of
color samples. How many you see depends on your terminal program's ability to color samples. How many you see depends on your terminal program's ability to
@ -48,7 +58,9 @@ You should at least see the Basic colors and Effects - if you do, then you have
.SH 16-COLOR SUPPORT .SH 16-COLOR SUPPORT
The basic color support is provided through named colors: The basic color support is provided through named colors:
.nf
black, red, blue, green, magenta, cyan, yellow, white black, red, blue, green, magenta, cyan, yellow, white
.fi
Foreground color (for text) is simply specified as one of the above colors, or Foreground color (for text) is simply specified as one of the above colors, or
not specified at all to use the default terminal text color. not specified at all to use the default terminal text color.
@ -56,37 +68,49 @@ not specified at all to use the default terminal text color.
Background color is specified by using the word 'on', and one of the above Background color is specified by using the word 'on', and one of the above
colors. Some examples: colors. Some examples:
.nf
green # green text, default background color green # green text, default background color
green on yellow # green text, yellow background green on yellow # green text, yellow background
on yellow # default text color, yellow background on yellow # default text color, yellow background
.fi
These colors can be modified further, by making the foreground bold, or by These colors can be modified further, by making the foreground bold, or by
making the background bright. Some examples: making the background bright. Some examples:
.nf
bold green bold green
bold white on bright red bold white on bright red
on bright cyan on bright cyan
.fi
The order of the words is not important, so the following are equivalent: The order of the words is not important, so the following are equivalent:
.nf
bold green bold green
green bold green bold
.fi
But the 'on' is important - colors before the 'on' are foreground, and colors But the 'on' is important - colors before the 'on' are foreground, and colors
after 'on' are background. after 'on' are background.
There is an additional 'underline' attribute that may be used: There is an additional 'underline' attribute that may be used:
.nf
underline bold red on black underline bold red on black
.fi
And an 'inverse' attribute: And an 'inverse' attribute:
.nf
inverse red inverse red
.fi
Taskwarrior has a command that helps you visualize these color combinations. Taskwarrior has a command that helps you visualize these color combinations.
Try this: Try this:
.nf
$ task color underline bold red on black $ task color underline bold red on black
.fi
You can use this command to see how the various color combinations work. You You can use this command to see how the various color combinations work. You
will also see some sample colors displayed, like the ones above, in addition to will also see some sample colors displayed, like the ones above, in addition to
@ -103,11 +127,13 @@ Using 256 colors follows the same form, but the names are different, and some
colors can be referenced in different ways. First there is by color ordinal, colors can be referenced in different ways. First there is by color ordinal,
which is like this: which is like this:
.nf
color0 color0
color1 color1
color2 color2
... ...
color255 color255
.fi
This gives you access to all 256 colors, but doesn't help you much. This range This gives you access to all 256 colors, but doesn't help you much. This range
is a combination of 8 basic colors (color0 - color7), then 8 brighter variations is a combination of 8 basic colors (color0 - color7), then 8 brighter variations
@ -119,31 +145,43 @@ be addressed via RGB values from 0 to 5 for each component color. A value of 0
means none of this component color, and a value of 5 means the most intense means none of this component color, and a value of 5 means the most intense
component color. For example, a bright red is specified as: component color. For example, a bright red is specified as:
.nf
rgb500 rgb500
.fi
And a darker red would be: And a darker red would be:
.nf
rgb300 rgb300
.fi
Note that the three digits represent the three component values, so in this Note that the three digits represent the three component values, so in this
example the 5, 0 and 0 represent red=5, green=0, blue=0. Combining intense red example the 5, 0 and 0 represent red=5, green=0, blue=0. Combining intense red
with no green and no blue yields red. Similarly, blue and green are: with no green and no blue yields red. Similarly, blue and green are:
.nf
rgb005 rgb005
rgb050 rgb050
.fi
Another example - bright yellow - is a mix of bright red and bright green, but Another example - bright yellow - is a mix of bright red and bright green, but
no blue component, so bright yellow is addressed as: no blue component, so bright yellow is addressed as:
.nf
rgb550 rgb550
.fi
A soft pink would be addressed as: A soft pink would be addressed as:
.nf
rgb515 rgb515
.fi
See if you agree, by running: See if you agree, by running:
.nf
$ task color black on rgb515 $ task color black on rgb515
.fi
You may notice that the large color block is represented as 6 squares. All You may notice that the large color block is represented as 6 squares. All
colors in the first square have a red value of 0. All colors in the 6th square colors in the first square have a red value of 0. All colors in the 6th square
@ -163,7 +201,9 @@ will be disappointed, perhaps even appalled.
There is some limited color mapping - for example, if you were to specify this There is some limited color mapping - for example, if you were to specify this
combination: combination:
.nf
red on gray3 red on gray3
.fi
you are mixing a 16-color and 256-color specification. Taskwarrior will map red you are mixing a 16-color and 256-color specification. Taskwarrior will map red
to color1, and proceed. Note that red and color1 are not quite the same tone. to color1, and proceed. Note that red and color1 are not quite the same tone.
@ -175,7 +215,9 @@ colors, but there is still underline available.
Taskwarrior will show examples of all defined colors used in your .taskrc, or Taskwarrior will show examples of all defined colors used in your .taskrc, or
theme, if you run this command: theme, if you run this command:
.nf
$ task color legend $ task color legend
.fi
This gives you an example of each of the colors, so you can see the effect, This gives you an example of each of the colors, so you can see the effect,
without necessarily creating a set of tasks that meet each of the rule criteria. without necessarily creating a set of tasks that meet each of the rule criteria.
@ -185,20 +227,26 @@ Taskwarrior supports colorization rules. These are configuration values that
specify a color, and the conditions under which that color is used. By example, specify a color, and the conditions under which that color is used. By example,
let us add a few tasks: let us add a few tasks:
.nf
$ task add project:Home priority:H pay the bills (1) $ task add project:Home priority:H pay the bills (1)
$ task add project:Home clean the rug (2) $ task add project:Home clean the rug (2)
$ task add project:Garden clean out the garage (3) $ task add project:Garden clean out the garage (3)
.fi
We can add a color rule that uses a blue background for all tasks in the Home We can add a color rule that uses a blue background for all tasks in the Home
project: project:
.nf
$ task config color.project.Home 'on blue' $ task config color.project.Home 'on blue'
.fi
We use quotes around 'on blue' because there are two words, but they represent We use quotes around 'on blue' because there are two words, but they represent
one value in the .taskrc file. Now suppose we wish to use a bold yellow text one value in the .taskrc file. Now suppose we wish to use a bold yellow text
color for all cleaning work: color for all cleaning work:
.nf
$ task config color.keyword.clean 'bold yellow' $ task config color.keyword.clean 'bold yellow'
.fi
Now what happens to task 2, which belongs to project Home (blue background), and Now what happens to task 2, which belongs to project Home (blue background), and
is also a cleaning task (bold yellow foreground)? The colors are combined, and is also a cleaning task (bold yellow foreground)? The colors are combined, and
@ -219,7 +267,9 @@ color blending.
The precedence for the color rules is determined by the configuration The precedence for the color rules is determined by the configuration
variable 'rule.precedence.color', which by default contains: variable 'rule.precedence.color', which by default contains:
.nf
deleted,completed,active,keyword.,tag.,project.,overdue,scheduled,due.today,due,blocked,blocking,recurring,tagged,uda. deleted,completed,active,keyword.,tag.,project.,overdue,scheduled,due.today,due,blocked,blocking,recurring,tagged,uda.
.fi
These are just the color rules with the 'color.' prefix removed. The These are just the color rules with the 'color.' prefix removed. The
rule 'color.deleted' has the highest precedence, and 'color.uda.' the lowest. rule 'color.deleted' has the highest precedence, and 'color.uda.' the lowest.
@ -238,50 +288,38 @@ be included.
To get a good idea of what a color theme looks like, try adding this entry to To get a good idea of what a color theme looks like, try adding this entry to
your .taskrc file: your .taskrc file:
.RS .nf
include dark-256.theme include dark-256.theme
.RE .fi
You can use any of the standard Taskwarrior themes: You can use any of the standard Taskwarrior themes:
.RS .nf
dark-16.theme dark-16.theme
.br
dark-256.theme dark-256.theme
.br
dark-blue-256.theme dark-blue-256.theme
.br
dark-gray-256.theme dark-gray-256.theme
.br
dark-green-256.theme dark-green-256.theme
.br
dark-red-256.theme dark-red-256.theme
.br
dark-violets-256.theme dark-violets-256.theme
.br
dark-yellow-green.theme dark-yellow-green.theme
.br
light-16.theme light-16.theme
.br
light-256.theme light-256.theme
.br
solarized-dark-256.theme solarized-dark-256.theme
.br
solarized-light-256.theme solarized-light-256.theme
.br
dark-default-16.theme dark-default-16.theme
.br
dark-gray-blue-256.theme dark-gray-blue-256.theme
.br
no-color.theme no-color.theme
.RE .fi
Bear in mind that if you are using a terminal with a dark background, you will Bear in mind that if you are using a terminal with a dark background, you will
see better results using a dark theme. see better results using a dark theme.
You can also see how the theme will color the various tasks with the command: You can also see how the theme will color the various tasks with the command:
.nf
$ task color legend $ task color legend
.fi
Better yet, create your own, and share it. We will gladly host the theme file Better yet, create your own, and share it. We will gladly host the theme file
on <https://taskwarrior.org>. on <https://taskwarrior.org>.

20
doc/man/task-sync.5.in
View file

@ -35,7 +35,9 @@ This is the default, and is appropriate for local synchronization.
For synchronization to a server, a better solution is to run For synchronization to a server, a better solution is to run
.nf
$ task sync $ task sync
.fi
periodically, such as via periodically, such as via
.BR cron (8) . .BR cron (8) .
@ -52,7 +54,9 @@ For most of these, you will need an encryption secret used to encrypt and
decrypt your tasks. This can be any secret string, and must match for all decrypt your tasks. This can be any secret string, and must match for all
replicas sharing tasks. replicas sharing tasks.
.nf
$ task config sync.encryption_secret <encryption_secret> $ task config sync.encryption_secret <encryption_secret>
.fi
Tools such as Tools such as
.BR pwgen (1) .BR pwgen (1)
@ -70,8 +74,10 @@ information from the server administrator:
Configure Taskwarrior with these details: Configure Taskwarrior with these details:
.nf
$ task config sync.server.origin <origin> $ task config sync.server.origin <origin>
$ task config sync.server.client_id <client_id> $ task config sync.server.client_id <client_id>
.fi
Note that the origin must include the scheme, such as 'http://' or 'https://'. Note that the origin must include the scheme, such as 'http://' or 'https://'.
@ -83,12 +89,16 @@ the bucket are adequate.
Authenticate to the project with: Authenticate to the project with:
.nf
$ gcloud config set project $PROJECT_NAME $ gcloud config set project $PROJECT_NAME
$ gcloud auth application-default login $ gcloud auth application-default login
.fi
Then configure Taskwarrior with: Then configure Taskwarrior with:
.nf
$ task config sync.gcp.bucket <bucket-name> $ task config sync.gcp.bucket <bucket-name>
.fi
However you can bring your own service account credentials if your However you can bring your own service account credentials if your
`application-default` is already being used by some other application `application-default` is already being used by some other application
@ -124,8 +134,10 @@ Select the following permissions:
Then configure Taskwarrior with: Then configure Taskwarrior with:
.nf
$ task config sync.gcp.bucket <bucket-name> $ task config sync.gcp.bucket <bucket-name>
$ task config sync.gcp.credential_path <absolute-path-to-downloaded-credentials> $ task config sync.gcp.credential_path <absolute-path-to-downloaded-credentials>
.fi
.SS Local Synchronization .SS Local Synchronization
@ -133,7 +145,9 @@ In order to take advantage of synchronization's side effect of saving disk
space without setting up a remote server, it is possible to sync tasks locally. space without setting up a remote server, it is possible to sync tasks locally.
To configure local sync: To configure local sync:
.nf
$ task config sync.local.server_dir /path/to/sync $ task config sync.local.server_dir /path/to/sync
.fi
The default configuration is to sync to a database in the task directory The default configuration is to sync to a database in the task directory
("data.location"). ("data.location").
@ -162,11 +176,15 @@ invent their own "encryption_secret".
If you run multiple clients that sync to the same server, you will need to run If you run multiple clients that sync to the same server, you will need to run
this command on your primary client (the one you use most often): this command on your primary client (the one you use most often):
.nf
$ task config recurrence on $ task config recurrence on
.fi
And on the other clients, run: And on the other clients, run:
.nf
$ task config recurrence off $ task config recurrence off
.fi
This protects you against the effects of a sync/duplication bug. This protects you against the effects of a sync/duplication bug.
@ -185,7 +203,9 @@ modifying the same task on two machines, without an intervening sync.
Setup simply involves creating the directory and modifying your data.location Setup simply involves creating the directory and modifying your data.location
configuration variable like this: configuration variable like this:
.nf
$ task config data.location /path/to/shared/directory $ task config data.location /path/to/shared/directory
.fi
Strengths: Strengths:
.br .br

221
doc/man/task.1.in
View file

@ -24,18 +24,24 @@ descriptors), project groups, etc.
The <filter> consists of zero or more search criteria that select tasks. For The <filter> consists of zero or more search criteria that select tasks. For
example, to list all pending tasks belonging to the 'Home' project: example, to list all pending tasks belonging to the 'Home' project:
.nf
task project:Home list task project:Home list
.fi
You can specify multiple filter terms, each of which further restricts the You can specify multiple filter terms, each of which further restricts the
result: result:
.nf
task project:Home +weekend garden list task project:Home +weekend garden list
.fi
This example applies three filters: the 'Home' project, the 'weekend' tag, and This example applies three filters: the 'Home' project, the 'weekend' tag, and
the description or annotations must contain the character sequence 'garden'. the description or annotations must contain the character sequence 'garden'.
In this example, 'garden' is translated internally to: In this example, 'garden' is translated internally to:
.nf
description.contains:garden description.contains:garden
.fi
as a convenient shortcut. The 'contains' here is an attribute modifier, which as a convenient shortcut. The 'contains' here is an attribute modifier, which
is used to exert more control over the filter than simply absence or presence. is used to exert more control over the filter than simply absence or presence.
@ -45,24 +51,30 @@ Note that a filter may have zero terms, which means that all tasks apply to the
command. This can be dangerous, and this special case is confirmed, and command. This can be dangerous, and this special case is confirmed, and
cannot be overridden. For example, this command: cannot be overridden. For example, this command:
.nf
task modify +work task modify +work
This command has no filter, and will modify all tasks. Are you sure? (yes/no) This command has no filter, and will modify all tasks. Are you sure? (yes/no)
.fi
will add the 'work' tag to all tasks, but only after confirmation. will add the 'work' tag to all tasks, but only after confirmation.
More filter examples: More filter examples:
.nf
task <command> <mods> task <command> <mods>
task 28 <command> <mods> task 28 <command> <mods>
task +weekend <command> <mods> task +weekend <command> <mods>
task +bills due.by:eom <command> <mods> task +bills due.by:eom <command> <mods>
task project:Home due.before:today <command> <mods> task project:Home due.before:today <command> <mods>
task ebeeab00-ccf8-464b-8b58-f7f2d606edfb <command> <mods> task ebeeab00-ccf8-464b-8b58-f7f2d606edfb <command> <mods>
.fi
By default filter elements are combined with an implicit 'and' operator, By default filter elements are combined with an implicit 'and' operator,
but 'or' and 'xor' may also be used, provided parentheses are included: but 'or' and 'xor' may also be used, provided parentheses are included:
.nf
task '( /[Cc]at|[Dd]og/ or /[0-9]+/ )' <command> <mods> task '( /[Cc]at|[Dd]og/ or /[0-9]+/ )' <command> <mods>
.fi
The parentheses isolate the logical term from any default command filter or The parentheses isolate the logical term from any default command filter or
implicit report filter which would be combined with an implicit 'and'. implicit report filter which would be combined with an implicit 'and'.
@ -71,10 +83,12 @@ A filter may target specific tasks using ID or UUID numbers. To specify
multiple tasks use one of these forms (space-separated list of ID numbers, multiple tasks use one of these forms (space-separated list of ID numbers,
UUID numbers or ID ranges): UUID numbers or ID ranges):
.nf
task 1 2 3 delete task 1 2 3 delete
task 1-3 info task 1-3 info
task 1 2-5 19 modify pri:H task 1 2-5 19 modify pri:H
task 4-7 ebeeab00-ccf8-464b-8b58-f7f2d606edfb info task 4-7 ebeeab00-ccf8-464b-8b58-f7f2d606edfb info
.fi
Note that it may be necessary to properly escape special characters as well as Note that it may be necessary to properly escape special characters as well as
quotes in order to avoid their special meanings in the shell. See also the quotes in order to avoid their special meanings in the shell. See also the
@ -85,11 +99,13 @@ section 'SPECIFYING DESCRIPTIONS' for more information.
The <mods> consist of zero or more changes to apply to the selected tasks, such The <mods> consist of zero or more changes to apply to the selected tasks, such
as: as:
.nf
task <filter> <command> project:Home task <filter> <command> project:Home
task <filter> <command> +weekend +garden due:tomorrow task <filter> <command> +weekend +garden due:tomorrow
task <filter> <command> Description/annotation text task <filter> <command> Description/annotation text
task <filter> <command> /from/to/ <- replace first match task <filter> <command> /from/to/ <- replace first match
task <filter> <command> /from/to/g <- replace all matches task <filter> <command> /from/to/g <- replace all matches
.fi
.SH SUBCOMMANDS .SH SUBCOMMANDS
@ -188,6 +204,7 @@ wish to save it, or pipe it to another command or script to convert it to
another format. You'll find these example scripts online at another format. You'll find these example scripts online at
<https://taskwarrior.org/tools/>: <https://taskwarrior.org/tools/>:
.nf
export-csv.pl export-csv.pl
export-sql.py export-sql.py
export-xml.py export-xml.py
@ -198,6 +215,7 @@ another format. You'll find these example scripts online at
export-ical.pl export-ical.pl
export-xml.pl export-xml.pl
export-yad.pl export-yad.pl
.fi
.TP .TP
.B task <filter> ghistory.annual .B task <filter> ghistory.annual
@ -243,12 +261,16 @@ Applies the filter then extracts only the task IDs and presents them as
a space-separated list. This is useful as input to a task command, to achieve a space-separated list. This is useful as input to a task command, to achieve
this: this:
.nf
task $(task project:Home ids) modify priority:H task $(task project:Home ids) modify priority:H
.fi
This example first gets the IDs for the project:Home filter, then sets This example first gets the IDs for the project:Home filter, then sets
the priority to H for each of those tasks. This can also be achieved directly: the priority to H for each of those tasks. This can also be achieved directly:
.nf
task project:Home modify priority:H task project:Home modify priority:H
.fi
This command is mainly of use to external scripts. This command is mainly of use to external scripts.
@ -258,7 +280,9 @@ Applies the filter on all tasks (even deleted and completed tasks)
then extracts only the task UUIDs and presents them as a space-separated list. then extracts only the task UUIDs and presents them as a space-separated list.
This is useful as input to a task command, to achieve this: This is useful as input to a task command, to achieve this:
.nf
task $(task project:Home status:completed uuids) modify status:pending task $(task project:Home status:completed uuids) modify status:pending
.fi
This example first gets the UUIDs for the project:Home and status:completed This example first gets the UUIDs for the project:Home and status:completed
filters, then makes each of those tasks pending again. filters, then makes each of those tasks pending again.
@ -385,8 +409,10 @@ if import is to be used in automated workflows. See taskrc(5).
For importing other file formats, the standard task release comes with a For importing other file formats, the standard task release comes with a
few example scripts, such as: few example scripts, such as:
.nf
import-todo.sh.pl import-todo.sh.pl
import-yaml.pl import-yaml.pl
.fi
.TP .TP
.B task log <mods> .B task log <mods>
@ -423,14 +449,20 @@ parses and evaluates the expression given on the command line.
Examples: Examples:
.nf
task calc 1 + 1 task calc 1 + 1
2 2
.fi
.nf
task calc now + 8d task calc now + 8d
2015-03-26T18:06:57 2015-03-26T18:06:57
.fi
.nf
task calc eom task calc eom
2015-03-31T23:59:59 2015-03-31T23:59:59
.fi
.TP .TP
.B task config [<name> [<value> | '']] .B task config [<name> [<value> | '']]
@ -438,16 +470,22 @@ Add, modify and remove settings directly in the Taskwarrior configuration.
This command either modifies the 'name' setting with a new value of 'value', This command either modifies the 'name' setting with a new value of 'value',
or adds a new entry that is equivalent to 'name=value': or adds a new entry that is equivalent to 'name=value':
.nf
task config name value task config name value
.fi
This command sets a blank value. This has the effect of suppressing any This command sets a blank value. This has the effect of suppressing any
default value: default value:
.nf
task config name '' task config name ''
.fi
Finally, this command removes any 'name=...' entry from the .taskrc file: Finally, this command removes any 'name=...' entry from the .taskrc file:
.nf
task config name task config name
.fi
.TP .TP
.B task context <name> .B task context <name>
@ -455,7 +493,9 @@ Sets the currently active context. See the CONTEXT section.
Example: Example:
.nf
task context work task context work
.fi
.TP .TP
.B task context delete <name> .B task context delete <name>
@ -464,7 +504,9 @@ set as active, it will be unset.
Example: Example:
.nf
task context delete work task context delete work
.fi
.TP .TP
.B task context define <name> <filter> .B task context define <name> <filter>
@ -473,9 +515,11 @@ does not affect the currently set context, just adds a new context definition.
Examples: Examples:
.nf
task context define work project:Work task context define work project:Work
task context define home project:Home or +home task context define home project:Home or +home
task context define superurgent due:today and +urgent task context define superurgent due:today and +urgent
.fi
.TP .TP
.B task context list .B task context list
@ -543,11 +587,15 @@ The sync command synchronizes data with the Taskserver, if configured.
Note: If you use multiple sync clients, make sure this setting (which is the default) Note: If you use multiple sync clients, make sure this setting (which is the default)
is on your primary client: is on your primary client:
.nf
recurrence=on recurrence=on
.fi
and on all other clients (this is not the default): and on all other clients (this is not the default):
.nf
recurrence=off recurrence=off
.fi
This is a workaround to avoid a recurrence bug that duplicates recurring tasks. This is a workaround to avoid a recurrence bug that duplicates recurring tasks.
@ -607,7 +655,9 @@ by third-party applications.
Reports a unique set of attribute values. For example, to see all the active Reports a unique set of attribute values. For example, to see all the active
projects: projects:
.nf
task +PENDING _unique project task +PENDING _unique project
.fi
.TP .TP
.B task <filter> _uuids .B task <filter> _uuids
@ -654,6 +704,7 @@ Shows the UUIDs and descriptions of matching tasks.
Accesses and displays the DOM reference(s). Used to extract individual values Accesses and displays the DOM reference(s). Used to extract individual values
from tasks, or the system. Supported DOM references are: from tasks, or the system. Supported DOM references are:
.nf
rc.<name> rc.<name>
tw.syncneeded tw.syncneeded
tw.program tw.program
@ -669,6 +720,7 @@ from tasks, or the system. Supported DOM references are:
system.os system.os
<id>.<attribute> <id>.<attribute>
<uuid>.<attribute> <uuid>.<attribute>
.fi
Note that the 'rc.<name>' reference may need to be escaped using '--' to prevent Note that the 'rc.<name>' reference may need to be escaped using '--' to prevent
the reference from being interpreted as an override. the reference from being interpreted as an override.
@ -679,8 +731,10 @@ missing value, the command exits with 1.
Additionally, some components of the attributes of particular types may be Additionally, some components of the attributes of particular types may be
extracted by DOM references. extracted by DOM references.
.nf
$ task _get 2.due.year $ task _get 2.due.year
2015 2015
.fi
For a full list of supported attribute-specific DOM references, consult For a full list of supported attribute-specific DOM references, consult
the online documentation at: the online documentation at:
@ -694,10 +748,11 @@ Tasks can be specified uniquely by IDs, which are simply the indexes of the
tasks in the database. The ID of a task may therefore change, but only when tasks in the database. The ID of a task may therefore change, but only when
a command is run that displays IDs. When modifying tasks, it is safe to a command is run that displays IDs. When modifying tasks, it is safe to
rely on the last displayed ID. Always run a report to check you have the right rely on the last displayed ID. Always run a report to check you have the right
ID for a task. IDs can be given to task as a sequence, for example, ID for a task. IDs can be given to task as a sequence, for example:
.br
.B .nf
task 1,4-10,19 delete task 1,4-10,19 delete
.fi
.TP .TP
.B +tag|-tag .B +tag|-tag
@ -708,15 +763,18 @@ Certain tags (called 'special tags'), can be used to affect the way tasks are
treated. For example, if a task has the special tag 'nocolor', then it is treated. For example, if a task has the special tag 'nocolor', then it is
exempt from all color rules. The supported special tags are: exempt from all color rules. The supported special tags are:
.nf
+nocolor Disable color rules processing for this task +nocolor Disable color rules processing for this task
+nonag Completion of this task suppresses all nag messages +nonag Completion of this task suppresses all nag messages
+nocal This task will not appear on the calendar +nocal This task will not appear on the calendar
+next Elevates task so it appears on 'next' report +next Elevates task so it appears on 'next' report
.fi
There are also virtual tags, which represent task metadata in tag form. These There are also virtual tags, which represent task metadata in tag form. These
tags do not exist, but can be used to filter tasks. The supported virtual tags tags do not exist, but can be used to filter tasks. The supported virtual tags
are: are:
.nf
ACTIVE Matches if the task is started ACTIVE Matches if the task is started
ANNOTATED Matches if the task has annotations ANNOTATED Matches if the task has annotations
BLOCKED Matches if the task is blocked BLOCKED Matches if the task is blocked
@ -748,6 +806,7 @@ are:
WEEK Matches if the task is due this week WEEK Matches if the task is due this week
YEAR Matches if the task is due this year YEAR Matches if the task is due this year
YESTERDAY Matches if the task was due sometime yesterday YESTERDAY Matches if the task was due sometime yesterday
.fi
.\" If you update the above list, update src/commands/CmdInfo.cpp and src/commands/CmdTags.cpp as well. .\" If you update the above list, update src/commands/CmdInfo.cpp and src/commands/CmdTags.cpp as well.
@ -853,9 +912,9 @@ calculated attributes:
For example: For example:
.RS .nf
task due.before:eom priority.not:L list task due.before:eom priority.not:L list
.RE .fi
The The
.I before .I before
@ -875,15 +934,21 @@ The
modifier is the same as 'before', except it also includes the moment in modifier is the same as 'before', except it also includes the moment in
question. For example: question. For example:
.nf
task add test due:eoy task add test due:eoy
.fi
will be found when using the inclusive filter 'by': will be found when using the inclusive filter 'by':
.nf
task due.by:eoy task due.by:eoy
.fi
but not when the non-inclusive filter 'before' is used: but not when the non-inclusive filter 'before' is used:
.nf
task due.before:eoy task due.before:eoy
.fi
this applies equally to other named dates such as 'eom', 'eod', etc; the this applies equally to other named dates such as 'eom', 'eod', etc; the
modifier compares using '<=' rather than '<' like 'before' does. modifier compares using '<=' rather than '<' like 'before' does.
@ -892,8 +957,10 @@ The
.I none .I none
modifier requires that the attribute does not have a value. For example: modifier requires that the attribute does not have a value. For example:
.nf
task priority: list task priority: list
task priority.none: list task priority.none: list
.fi
are equivalent, and list tasks that do not have a priority. are equivalent, and list tasks that do not have a priority.
@ -915,8 +982,10 @@ The
.I has .I has
modifier is used to search for a substring, such as: modifier is used to search for a substring, such as:
.nf
task description.has:foo list task description.has:foo list
task foo list task foo list
.fi
These are equivalent and will return any task that has 'foo' in the description These are equivalent and will return any task that has 'foo' in the description
or annotations. or annotations.
@ -931,13 +1000,17 @@ The
.I startswith .I startswith
modifier matches against the left, or beginning of an attribute, such that: modifier matches against the left, or beginning of an attribute, such that:
.nf
task project.startswith:H list task project.startswith:H list
task project:H list task project:H list
.fi
are equivalent and will match any project starting with 'H'. Matching all are equivalent and will match any project starting with 'H'. Matching all
projects not starting with 'H' is done with: projects not starting with 'H' is done with:
.nf
task project.not:H list task project.not:H list
.fi
The The
.I endswith .I endswith
@ -948,7 +1021,9 @@ The
modifier requires that the attribute contain the whole word specified, such modifier requires that the attribute contain the whole word specified, such
that this: that this:
.nf
task description.word:bar list task description.word:bar list
.fi
Will match the description 'foo bar baz' but does not match 'dog food'. Will match the description 'foo bar baz' but does not match 'dog food'.
@ -962,15 +1037,19 @@ modifier.
You can use the following operators in filter expressions: You can use the following operators in filter expressions:
.nf
and or xor ! Logical operators and or xor ! Logical operators
< <= = == != !== >= > Relational operators < <= = == != !== >= > Relational operators
( ) Precedence ( ) Precedence
.fi
For example: For example:
.nf
task due.before:eom priority.not:L list task due.before:eom priority.not:L list
task '( due < eom or priority != L )' list task '( due < eom or priority != L )' list
task '! ( project:Home or project:Garden )' list task '! ( project:Home or project:Garden )' list
.fi
The The
.I = .I =
@ -994,32 +1073,44 @@ Note that the parentheses are required when using a logical operator other than
the 'and' operator. The reason is that some reports contain filters that must the 'and' operator. The reason is that some reports contain filters that must
be combined with the command line. Consider this example: be combined with the command line. Consider this example:
.nf
task project:Home or project:Garden list task project:Home or project:Garden list
.fi
While this looks correct, it is not. The 'list' report contains a filter of: While this looks correct, it is not. The 'list' report contains a filter of:
.nf
task show report.list.filter task show report.list.filter
Config Variable Value Config Variable Value
----------------- -------------- ----------------- --------------
report.list.filter status:pending report.list.filter status:pending
.fi
Which means the example is really: Which means the example is really:
.nf
task status:pending project:Home or project:Garden list task status:pending project:Home or project:Garden list
.fi
The implied 'and' operator makes it: The implied 'and' operator makes it:
.nf
task status:pending and project:Home or project:Garden list task status:pending and project:Home or project:Garden list
.fi
This is a precedence error - the 'and' and 'or' need to be grouped using This is a precedence error - the 'and' and 'or' need to be grouped using
parentheses, like this: parentheses, like this:
.nf
task status:pending and ( project:Home or project:Garden ) list task status:pending and ( project:Home or project:Garden ) list
.fi
The original example therefore must be entered as: The original example therefore must be entered as:
.nf
task '( project:Home or project:Garden )' list task '( project:Home or project:Garden )' list
.fi
This includes quotes to escape the parentheses, so that the shell doesn't This includes quotes to escape the parentheses, so that the shell doesn't
interpret them and hide them from Taskwarrior. interpret them and hide them from Taskwarrior.
@ -1027,11 +1118,13 @@ interpret them and hide them from Taskwarrior.
There is redundancy between operators, attribute modifiers and other syntactic There is redundancy between operators, attribute modifiers and other syntactic
sugar. For example, the following are all equivalent: sugar. For example, the following are all equivalent:
.nf
task foo list task foo list
task /foo/ list task /foo/ list
task description.contains:foo list task description.contains:foo list
task description.has:foo list task description.has:foo list
task 'description ~ foo' list task 'description ~ foo' list
.fi
.SH SPECIFYING DATES AND FREQUENCIES .SH SPECIFYING DATES AND FREQUENCIES
@ -1045,92 +1138,83 @@ configuration variable
.RS .RS
.TP .TP
Exact specification Exact specification
.nf
task ... due:7/14/2008 task ... due:7/14/2008
.fi
.TP .TP
ISO-8601 ISO-8601
.nf
task ... due:2013-03-14T22:30:00Z task ... due:2013-03-14T22:30:00Z
.fi
.TP .TP
Relative wording Relative wording
.nf
task ... due:now task ... due:now
.br
task ... due:today task ... due:today
.br
task ... due:yesterday task ... due:yesterday
.br
task ... due:tomorrow task ... due:tomorrow
.fi
.TP .TP
Day number with ordinal Day number with ordinal
.nf
task ... due:23rd task ... due:23rd
.br
task ... due:3wks task ... due:3wks
.br
task ... due:1day task ... due:1day
.br
task ... due:9hrs task ... due:9hrs
.fi
.TP .TP
Start of next (work) week (Monday), calendar week (Sunday or Monday), month, quarter and year Start of next (work) week (Monday), calendar week (Sunday or Monday), month, quarter and year
.br .nf
task ... due:sow task ... due:sow
.br
task ... due:soww task ... due:soww
.br
task ... due:socw task ... due:socw
.br
task ... due:som task ... due:som
.br
task ... due:soq task ... due:soq
.br
task ... due:soy task ... due:soy
.fi
.TP .TP
End of current (work) week (Friday), calendar week (Saturday or Sunday), month, quarter and year End of current (work) week (Friday), calendar week (Saturday or Sunday), month, quarter and year
.br .nf
task ... due:eow task ... due:eow
.br
task ... due:eoww task ... due:eoww
.br
task ... due:eocw task ... due:eocw
.br
task ... due:eom task ... due:eom
.br
task ... due:eoq task ... due:eoq
.br
task ... due:eoy task ... due:eoy
.fi
.TP .TP
At some point or later At some point or later
.br .nf
task ... wait:later task ... wait:later
.br
task ... wait:someday task ... wait:someday
.fi
This sets the wait date to 12/30/9999. This sets the wait date to 12/30/9999.
.TP .TP
Next occurring weekday Next occurring weekday
.nf
task ... due:fri task ... due:fri
.fi
.TP .TP
Predictable holidays Predictable holidays
.nf
task ... due:goodfriday task ... due:goodfriday
.br
task ... due:easter task ... due:easter
.br
task ... due:eastermonday task ... due:eastermonday
.br
task ... due:ascension task ... due:ascension
.br
task ... due:pentecost task ... due:pentecost
.br
task ... due:midsommar task ... due:midsommar
.br
task ... due:midsommarafton task ... due:midsommarafton
.br
task ... due:juhannus task ... due:juhannus
.fi
.RE .RE
.SS FREQUENCIES .SS FREQUENCIES
@ -1181,7 +1265,8 @@ Context is a user-defined query, which is automatically applied to all commands
that filter the task list and to commands that create new tasks (add, log). For that filter the task list and to commands that create new tasks (add, log). For
example, any report command will have its result affected by the current example, any report command will have its result affected by the current
active context. Here is a list of the commands that are affected: active context. Here is a list of the commands that are affected:
.IP
.nf
add add
burndown burndown
count count
@ -1199,33 +1284,44 @@ active context. Here is a list of the commands that are affected:
stop stop
summary summary
tags tags
.fi
All other commands are NOT affected by the context. All other commands are NOT affected by the context.
.nf
$ task list $ task list
ID Age Project Description Urg ID Age Project Description Urg
1 2d Sport Run 5 miles 1.42 1 2d Sport Run 5 miles 1.42
2 1d Home Clean the dishes 1.14 2 1d Home Clean the dishes 1.14
.fi
.nf
$ task context home $ task context home
Context 'home' set. Use 'task context none' to remove. Context 'home' set. Use 'task context none' to remove.
.fi
.nf
$ task list $ task list
ID Age Project Description Urg ID Age Project Description Urg
2 1d Home Clean the dishes 1.14 2 1d Home Clean the dishes 1.14
Context 'home' set. Use 'task context none' to remove. Context 'home' set. Use 'task context none' to remove.
.fi
Task list got automatically filtered for project:Home. Task list got automatically filtered for project:Home.
.nf
$ task add Vaccuum the carpet $ task add Vaccuum the carpet
Created task 3. Created task 3.
Context 'home' set. Use 'task context none' to remove. Context 'home' set. Use 'task context none' to remove.
.fi
.nf
$ task list $ task list
ID Age Project Description Urg ID Age Project Description Urg
2 1d Home Clean the dishes 1.14 2 1d Home Clean the dishes 1.14
3 5s Home Vaccuum the carpet 1.14 3 5s Home Vaccuum the carpet 1.14
Context 'home' set. Use 'task context none' to remove. Context 'home' set. Use 'task context none' to remove.
.fi
Note that the newly added task "Vaccuum the carpet" has "project:Home" set Note that the newly added task "Vaccuum the carpet" has "project:Home" set
automatically. automatically.
@ -1236,22 +1332,28 @@ new context's name to the 'context' command.
To unset any context, use the 'none' subcommand. To unset any context, use the 'none' subcommand.
.nf
$ task context none $ task context none
Context unset. Context unset.
.fi
.nf
$ task list $ task list
ID Age Project Description Urg ID Age Project Description Urg
1 2d Sport Run 5 miles 1.42 1 2d Sport Run 5 miles 1.42
2 1d Home Clean the dishes 1.14 2 1d Home Clean the dishes 1.14
3 7s Home Vaccuum the carpet 1.14 3 7s Home Vaccuum the carpet 1.14
.fi
Context can be defined using the 'define' subcommand, specifying both the name Context can be defined using the 'define' subcommand, specifying both the name
of the new context, and it's assigned filter. of the new context, and it's assigned filter.
.nf
$ task context define home project:Home $ task context define home project:Home
Are you sure you want to add 'context.home.read' with a value of 'project:Home'? (yes/no) yes Are you sure you want to add 'context.home.read' with a value of 'project:Home'? (yes/no) yes
Are you sure you want to add 'context.home.write' with a value of 'project:Home'? (yes/no) yes Are you sure you want to add 'context.home.write' with a value of 'project:Home'? (yes/no) yes
Context 'home' successfully defined. Context 'home' successfully defined.
.fi
Note that you were separately prompted to set the 'read' and 'write' context. Note that you were separately prompted to set the 'read' and 'write' context.
This allows you to specify contexts that only work for reporting commands or This allows you to specify contexts that only work for reporting commands or
@ -1259,13 +1361,16 @@ only for commands that create tasks.
To remove the definition, use the 'delete' subcommand. To remove the definition, use the 'delete' subcommand.
.nf
$ task context delete home $ task context delete home
Are you sure you want to remove 'context.home.read'? (yes/no) yes Are you sure you want to remove 'context.home.read'? (yes/no) yes
Are you sure you want to remove 'context.home.write'? (yes/no) yes Are you sure you want to remove 'context.home.write'? (yes/no) yes
Context 'home' deleted. Context 'home' deleted.
.fi
To check what is the currently active context, use the 'show' subcommand. To check what is the currently active context, use the 'show' subcommand.
.nf
$ task context show $ task context show
Context 'home' with Context 'home' with
@ -1273,13 +1378,16 @@ To check what is the currently active context, use the 'show' subcommand.
* write filter: '+home' * write filter: '+home'
is currently applied. is currently applied.
.fi
Contexts can store arbitrarily complex filters. Contexts can store arbitrarily complex filters.
.nf
$ task context define family project:Family or +paul or +nancy $ task context define family project:Family or +paul or +nancy
Are you sure you want to add 'context.family.read' with a value of 'project:Family or +paul or +nancy'? (yes/no) yes Are you sure you want to add 'context.family.read' with a value of 'project:Family or +paul or +nancy'? (yes/no) yes
Are you sure you want to add 'context.family.write' with a value of 'project:Family or +paul or +nancy'? (yes/no) no Are you sure you want to add 'context.family.write' with a value of 'project:Family or +paul or +nancy'? (yes/no) no
Context 'family' successfully defined. Context 'family' successfully defined.
.fi
Contexts are permanent, and the currently set context name is stored in the Contexts are permanent, and the currently set context name is stored in the
"context" configuration variable. The context definition is stored in the "context" configuration variable. The context definition is stored in the
@ -1292,13 +1400,17 @@ filter as writeable context. The reason for this decision is that the complex
filter in the example does not directly translate to a modification. In fact, filter in the example does not directly translate to a modification. In fact,
if such a context is used as a writeable context, the following happens: if such a context is used as a writeable context, the following happens:
.nf
$ task add Call Paul $ task add Call Paul
Created task 4. Created task 4.
Context 'family' set. Use 'task context none' to remove. Context 'family' set. Use 'task context none' to remove.
.fi
.nf
$ task 4 list $ task 4 list
ID Age Project Tags Description Urg ID Age Project Tags Description Urg
4 9min Family nancy paul or or Call Paul 0 4 9min Family nancy paul or or Call Paul 0
.fi
There is no clear mapping between the complex filter used and the modifications There is no clear mapping between the complex filter used and the modifications
@ -1307,16 +1419,20 @@ operators being present in the description. Taskwarrior does not try to guess
the user intention here, and instead, the user is expected to set the the user intention here, and instead, the user is expected to set the
"context.<name>.write" variable to make their intention explicit, for example: "context.<name>.write" variable to make their intention explicit, for example:
.nf
$ task config context.family.write project:Family $ task config context.family.write project:Family
Are you sure you want to change the value of 'context.family.write' from 'project:Family or +paul or +nancy' to 'project:Family'? (yes/no) yes Are you sure you want to change the value of 'context.family.write' from 'project:Family or +paul or +nancy' to 'project:Family'? (yes/no) yes
Config file /home/tbabej/.config/task/taskrc modified. Config file /home/tbabej/.config/task/taskrc modified.
.fi
.nf
$ task context $ task context
Name Type Definition Active Name Type Definition Active
family read project:Family or +paul or +nancy yes family read project:Family or +paul or +nancy yes
write project:Family yes write project:Family yes
home read +home no home read +home no
write +home no write +home no
.fi
Note how read and write contexts differ for context "family", while for context Note how read and write contexts differ for context "family", while for context
"home" they stay the same. "home" they stay the same.
@ -1325,74 +1441,75 @@ In addition, every configuration parameter can be overridden for the current
context, by specifying context.<name>.rc.<parameter>. For example, if the default context, by specifying context.<name>.rc.<parameter>. For example, if the default
command for the family context should be displaying the family_report: command for the family context should be displaying the family_report:
.nf
$ task config context.family.rc.default.command family_report $ task config context.family.rc.default.command family_report
.fi
.SH COMMAND ABBREVIATION .SH COMMAND ABBREVIATION
All Taskwarrior commands may be abbreviated as long as a unique prefix is used, All Taskwarrior commands may be abbreviated as long as a unique prefix is used,
for example: for example:
.RS .nf
$ task li $ task li
.RE .fi
is an unambiguous abbreviation for is an unambiguous abbreviation for
.RS .nf
$ task list $ task list
.RE .fi
but but
.RS .nf
$ task l $ task l
.RE .fi
could be list, ls or long. could be list, ls or long.
Note that you can restrict the minimum abbreviation size using the configuration Note that you can restrict the minimum abbreviation size using the configuration
setting: setting:
.RS .nf
abbreviation.minimum=3 abbreviation.minimum=3
.RE .fi
.SH SPECIFYING DESCRIPTIONS .SH SPECIFYING DESCRIPTIONS
Some task descriptions need to be escaped because of the shell and the special Some task descriptions need to be escaped because of the shell and the special
meaning of some characters to the shell. This can be done either by adding meaning of some characters to the shell. This can be done either by adding
quotes to the description or escaping the special character: quotes to the description or escaping the special character:
.RS .nf
$ task add "quoted ' quote" $ task add "quoted ' quote"
.br
$ task add escaped \\' quote $ task add escaped \\' quote
.RE .fi
The argument \-\- (a double dash) tells Taskwarrior to treat all other args The argument \-\- (a double dash) tells Taskwarrior to treat all other args
as description: as description:
.RS .nf
$ task add -- project:Home needs scheduling $ task add -- project:Home needs scheduling
.RE .fi
In other situations, the shell sees spaces and breaks up arguments. For In other situations, the shell sees spaces and breaks up arguments. For
example, this command: example, this command:
.RS .nf
$ task 123 modify /from this/to that/ $ task 123 modify /from this/to that/
.RE .fi
is broken up into several arguments, which is corrected with quotes: is broken up into several arguments, which is corrected with quotes:
.RS .nf
$ task 123 modify "/from this/to that/" $ task 123 modify "/from this/to that/"
.RE .fi
It is sometimes necessary to force the shell to pass quotes to Taskwarrior It is sometimes necessary to force the shell to pass quotes to Taskwarrior
intact, so you can use: intact, so you can use:
.RS .nf
$ task add project:\\'Three Word Project\\' description $ task add project:\\'Three Word Project\\' description
.RE .fi
Taskwarrior supports Unicode using only the UTF8 encoding. Taskwarrior supports Unicode using only the UTF8 encoding.

188
doc/man/taskrc.5.in
View file

@ -18,43 +18,43 @@ obtains its configuration data from a file called
.I .taskrc .I .taskrc
\&. This file is normally located in the user's home directory: \&. This file is normally located in the user's home directory:
.RS .nf
$HOME/.taskrc $HOME/.taskrc
.RE .fi
The default location can be overridden using the The default location can be overridden using the
.I rc: .I rc:
attribute when running task: attribute when running task:
.RS .nf
$ task rc:<directory-path>/.taskrc ... $ task rc:<directory-path>/.taskrc ...
.RE .fi
or using the TASKRC environment variable: or using the TASKRC environment variable:
.RS .nf
$ TASKRC=/tmp/.taskrc task ... $ TASKRC=/tmp/.taskrc task ...
.RE .fi
Additionally, if no ~/.taskrc exists, taskwarrior will check if the XDG_CONFIG_HOME environment variable is defined: Additionally, if no ~/.taskrc exists, taskwarrior will check if the XDG_CONFIG_HOME environment variable is defined:
.RS .nf
$ XDG_CONFIG_HOME=~/.config task ... $ XDG_CONFIG_HOME=~/.config task ...
.RE .fi
Individual options can be overridden by using the Individual options can be overridden by using the
.I rc.<name>: .I rc.<name>:
attribute when running task: attribute when running task:
.RS .nf
$ task rc.<name>:<value> ... $ task rc.<name>:<value> ...
.RE .fi
or or
.RS .nf
$ task rc.<name>=<value> ... $ task rc.<name>=<value> ...
.RE .fi
If If
.B Taskwarrior .B Taskwarrior
@ -65,9 +65,9 @@ file in the user's home directory.
The .taskrc file follows a very simple syntax defining name/value pairs: The .taskrc file follows a very simple syntax defining name/value pairs:
.RS .nf
<name> = <value> <name> = <value>
.RE .fi
There may be whitespace around <name>, '=' and <value>, and it is ignored. There may be whitespace around <name>, '=' and <value>, and it is ignored.
Whitespace within the <value> is left intact. Whitespace within the <value> is left intact.
@ -79,9 +79,9 @@ Note that Taskwarrior is flexible about the values used to represent Boolean
items. You can use "1" to enable, anything else is interpreted as disabled. items. You can use "1" to enable, anything else is interpreted as disabled.
The values "on", "yes", "y" and "true" are currently supported but deprecated. The values "on", "yes", "y" and "true" are currently supported but deprecated.
.RS .nf
include <file> include <file>
.RE .fi
There may be whitespace around 'include' and <file>. The file may be an There may be whitespace around 'include' and <file>. The file may be an
absolute or relative path, and the special character '~' is expanded to mean absolute or relative path, and the special character '~' is expanded to mean
@ -95,9 +95,9 @@ respect to the following directories (listed in order of precedence):
Note that environment variables are also expanded in paths (and any other Note that environment variables are also expanded in paths (and any other
taskrc variables). taskrc variables).
.RS .nf
# <comment> # <comment>
.RE .fi
A comment consists of the character '#', and extends from the '#' to the end 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 of the line. There is no way to comment a multi-line block. There may be
@ -108,9 +108,9 @@ 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 represent overrides of the default values. To remove a default value completely
there must be an entry like this: there must be an entry like this:
.RS .nf
<name> = <name> =
.RE .fi
This entry overrides the default value with a blank value. This entry overrides the default value with a blank value.
@ -118,28 +118,28 @@ This entry overrides the default value with a blank value.
You can edit your .taskrc file by hand if you wish, or you can use the 'config' 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: command. To permanently set a value in your .taskrc file, use this command:
.RS .nf
$ task config nag "You have more urgent tasks." $ task config nag "You have more urgent tasks."
.RE .fi
To delete an entry, use this command: To delete an entry, use this command:
.RS .nf
$ task config nag $ task config nag
.RE .fi
Taskwarrior will then use the default value. To explicitly set a value to Taskwarrior will then use the default value. To explicitly set a value to
blank, and therefore avoid using the default value, use this command: blank, and therefore avoid using the default value, use this command:
.RS .nf
$ task config nag "" $ task config nag ""
.RE .fi
Taskwarrior will also display all your settings with this command: Taskwarrior will also display all your settings with this command:
.RS .nf
$ task show $ task show
.RE .fi
and in addition, will also perform a check of all the values in the file, and in addition, will also perform a check of all the values in the file,
warning you of anything it finds amiss. warning you of anything it finds amiss.
@ -149,20 +149,19 @@ The .taskrc can include other files containing configuration settings by using t
.B include .B include
statement: statement:
.RS .nf
include <path/to/the/configuration/file/to/be/included> include <path/to/the/configuration/file/to/be/included>
.RE .fi
By using include files you can divide your main configuration file into several By using include files you can divide your main configuration file into several
ones containing just the relevant configuration data like colors, etc. ones containing just the relevant configuration data like colors, etc.
There are two excellent uses of includes in your .taskrc, shown here: There are two excellent uses of includes in your .taskrc, shown here:
.RS .nf
include holidays.en-US.rc include holidays.en-US.rc
.br
include dark-16.theme include dark-16.theme
.RE .fi
This includes two standard files that are distributed with Taskwarrior, which This includes two standard files that are distributed with Taskwarrior, which
define a set of US holidays, and set up a 16-color theme to use, to color the define a set of US holidays, and set up a 16-color theme to use, to color the
@ -299,6 +298,7 @@ is most readily parsed and used by shell scripts.
Alternatively, you can specify a comma-separated list of verbosity tokens that Alternatively, you can specify a comma-separated list of verbosity tokens that
control specific occasions when output is generated. This list may contain: control specific occasions when output is generated. This list may contain:
.nf
blank Inserts extra blank lines in output, for clarity blank Inserts extra blank lines in output, for clarity
header Messages that appear before report output (this includes .taskrc/.task overrides and the "[task next]" message) header Messages that appear before report output (this includes .taskrc/.task overrides and the "[task next]" message)
footnote Messages that appear after report output (mostly status messages and change descriptions) footnote Messages that appear after report output (mostly status messages and change descriptions)
@ -315,6 +315,7 @@ control specific occasions when output is generated. This list may contain:
override Notification when configuration options are overridden override Notification when configuration options are overridden
recur Notification when a new recurring task instance is created recur Notification when a new recurring task instance is created
default Notifications about taskwarrior choosing to perform a default action. default Notifications about taskwarrior choosing to perform a default action.
.fi
The tokens "affected", "new-id", "new-uuid", "project", "override" and "recur" The tokens "affected", "new-id", "new-uuid", "project", "override" and "recur"
imply "footnote". imply "footnote".
@ -326,14 +327,20 @@ and the "nothing" setting is equivalent to none of the tokens being specified.
Here are the shortcut equivalents: Here are the shortcut equivalents:
.nf
verbose=on verbose=on
verbose=blank,header,footnote,label,new-id,affected,edit,special,project,sync,filter,override,recur verbose=blank,header,footnote,label,new-id,affected,edit,special,project,sync,filter,override,recur
.fi
.nf
verbose=0 verbose=0
verbose=blank,label,new-id,edit verbose=blank,label,new-id,edit
.fi
.nf
verbose=nothing verbose=nothing
verbose= verbose=
.fi
Those additional comments are sent to the standard error for header, footnote Those additional comments are sent to the standard error for header, footnote
and project. The others are sent to standard output. and project. The others are sent to standard output.
@ -584,51 +591,29 @@ are formatted according to dateformat.
The default value is the ISO-8601 standard: Y-M-D. The string can contain the The default value is the ISO-8601 standard: Y-M-D. The string can contain the
characters: characters:
.RS .nf
.RS
m minimal-digit month, for example 1 or 12 m minimal-digit month, for example 1 or 12
.br
d minimal-digit day, for example 1 or 30 d minimal-digit day, for example 1 or 30
.br
y two-digit year, for example 09 or 12 y two-digit year, for example 09 or 12
.br
D two-digit day, for example 01 or 30 D two-digit day, for example 01 or 30
.br
M two-digit month, for example 01 or 12 M two-digit month, for example 01 or 12
.br
Y four-digit year, for example 2009 or 2015 Y four-digit year, for example 2009 or 2015
.br
a short name of weekday, for example Mon or Wed a short name of weekday, for example Mon or Wed
.br
A long name of weekday, for example Monday or Wednesday A long name of weekday, for example Monday or Wednesday
.br
b short name of month, for example Jan or Aug b short name of month, for example Jan or Aug
.br
B long name of month, for example January or August B long name of month, for example January or August
.br
v minimal-digit week, for example 3 or 37 v minimal-digit week, for example 3 or 37
.br
V two-digit week, for example 03 or 37 V two-digit week, for example 03 or 37
.br
h minimal-digit hour, for example 3 or 21 h minimal-digit hour, for example 3 or 21
.br
n minimal-digit minutes, for example 5 or 42 n minimal-digit minutes, for example 5 or 42
.br
s minimal-digit seconds, for example 7 or 47 s minimal-digit seconds, for example 7 or 47
.br
H two-digit hour, for example 03 or 21 H two-digit hour, for example 03 or 21
.br
N two-digit minutes, for example 05 or 42 N two-digit minutes, for example 05 or 42
.br
S two-digit seconds, for example 07 or 47 S two-digit seconds, for example 07 or 47
.br
J three-digit Julian day, for example 023 or 365 J three-digit Julian day, for example 023 or 365
.br
j Julian day, for example 23 or 365 j Julian day, for example 23 or 365
.br
w Week day, for example 0 for Monday, 5 for Friday w Week day, for example 0 for Monday, 5 for Friday
.RE .fi
.RE
.RS .RS
The characters 'v', 'V', 'a' and 'A' can only be used for formatting printed The characters 'v', 'V', 'a' and 'A' can only be used for formatting printed
@ -640,37 +625,24 @@ The string may also contain other characters to act as spacers, or formatting.
Examples for other values of dateformat: Examples for other values of dateformat:
.RE .RE
.RS .nf
.RS
.br
d/m/Y would use for input and output 24/7/2009 d/m/Y would use for input and output 24/7/2009
.br
yMD would use for input and output 090724 yMD would use for input and output 090724
.br
M-D-Y would use for input and output 07-24-2009 M-D-Y would use for input and output 07-24-2009
.RE .fi
.RE
.RS .RS
Examples for other values of dateformat.report: Examples for other values of dateformat.report:
.RE .RE
.RS .nf
.RS
.br
a D b Y (V) would emit "Fri 24 Jul 2009 (30)" a D b Y (V) would emit "Fri 24 Jul 2009 (30)"
.br
A, B D, Y would emit "Friday, July 24, 2009" A, B D, Y would emit "Friday, July 24, 2009"
.br
wV a Y-M-D would emit "w30 Fri 2009-07-24" wV a Y-M-D would emit "w30 Fri 2009-07-24"
.br
yMD.HN would emit "110124.2342" yMD.HN would emit "110124.2342"
.br
m/d/Y H:N would emit "1/24/2011 10:42" m/d/Y H:N would emit "1/24/2011 10:42"
.br
a D b Y H:N:S would emit "Mon 24 Jan 2011 11:19:42" a D b Y H:N:S would emit "Mon 24 Jan 2011 11:19:42"
.RE .fi
.RE
.RS .RS
Undefined fields are put to their minimal valid values (1 for month and day and Undefined fields are put to their minimal valid values (1 for month and day and
@ -679,14 +651,10 @@ field that is set. Otherwise, they are set to the corresponding values of
"now". For example: "now". For example:
.RE .RE
.RS .nf
.RS
.br
8/1/2013 with m/d/Y implies August 1, 2013 at midnight (inferred) 8/1/2013 with m/d/Y implies August 1, 2013 at midnight (inferred)
.br
8/1 20:40 with m/d H:N implies August 1, 2013 (inferred) at 20:40 8/1 20:40 with m/d H:N implies August 1, 2013 (inferred) at 20:40
.RE .fi
.RE
.TP .TP
.B date.iso=1 .B date.iso=1
@ -780,28 +748,19 @@ Holidays are entered either directly in the .taskrc file or via an include file
that is specified in .taskrc. For single-day holidays the name and the date is that is specified in .taskrc. For single-day holidays the name and the date is
required to be given: required to be given:
.RS .nf
.RS
.br
holiday.towel.name=Day of the towel holiday.towel.name=Day of the towel
.br
holiday.towel.date=20100525 holiday.towel.date=20100525
.RE .fi
.RE
For holidays that span a range of days (i.e. vacation), you can use a start date For holidays that span a range of days (i.e. vacation), you can use a start date
and an end date: and an end date:
.RS .nf
.RS
.br
holiday.sysadmin.name=System Administrator Appreciation Week holiday.sysadmin.name=System Administrator Appreciation Week
.br
holiday.sysadmin.start=20100730 holiday.sysadmin.start=20100730
.br
holiday.sysadmin.end=20100805 holiday.sysadmin.end=20100805
.RE .fi
.RE
.RS .RS
Dates are to be entered according to the setting in the dateformat.holiday Dates are to be entered according to the setting in the dateformat.holiday
@ -814,24 +773,17 @@ Easter (easter), Easter Monday (eastermonday), Ascension (ascension), Pentecost
(pentecost). The date for these holidays is the given keyword: (pentecost). The date for these holidays is the given keyword:
.RE .RE
.RS .nf
.RS
.br
holiday.eastersunday.name=Easter holiday.eastersunday.name=Easter
.br
holiday.eastersunday.date=easter holiday.eastersunday.date=easter
.RE .fi
.RE
Note that the Taskwarrior distribution contains example holiday files that can Note that the Taskwarrior distribution contains example holiday files that can
be included like this: be included like this:
.RS .nf
.RS
.br
include holidays.en-US.rc include holidays.en-US.rc
.RE .fi
.RE
.SS DEPENDENCIES .SS DEPENDENCIES
@ -919,10 +871,9 @@ Task is deleted.
.RS .RS
To disable a coloration rule for which there is a default, set the value to To disable a coloration rule for which there is a default, set the value to
nothing, for example: nothing, for example:
.RS .nf
.B color.tagged= color.tagged=
.RE .fi
.RE
.RS .RS
By default, colors produced by rules blend. This has the advantage of By default, colors produced by rules blend. This has the advantage of
@ -1257,30 +1208,23 @@ default.command=next
Provides a default command that is run every time Taskwarrior is invoked with no Provides a default command that is run every time Taskwarrior is invoked with no
arguments. For example, if set to: arguments. For example, if set to:
.RS .nf
.RS
default.command=project:foo list default.command=project:foo list
.RE .fi
.RE
.RS .RS
then Taskwarrior will run the "project:foo list" command if no command is then Taskwarrior will run the "project:foo list" command if no command is
specified. This means that by merely typing specified. This means that by merely typing
.RE .RE
.RS .nf
.RS
$ task $ task
.br
[task project:foo list] [task project:foo list]
.br
\&
.br
ID Project Pri Description ID Project Pri Description
1 foo H Design foo 1 foo H Design foo
2 foo Build foo 2 foo Build foo
.RE .fi
.RE
.SS REPORTS .SS REPORTS
@ -1319,12 +1263,16 @@ 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. or a "-" for descending sort order. The sort IDs are separated by commas.
For example: For example:
.nf
report.list.sort=due+,priority-,start.active-,project+ report.list.sort=due+,priority-,start.active-,project+
.fi
Additionally, after the "+" or "-", there can be a solidus "/" which indicates Additionally, after the "+" or "-", there can be a solidus "/" which indicates
that there are breaks after the column values change. For example: that there are breaks after the column values change. For example:
.nf
report.minimal.sort=project+/,description+ report.minimal.sort=project+/,description+
.fi
This sort order now specifies that there is a listing break between each This sort order now specifies that there is a listing break between each
project. A listing break is simply a blank line, which provides a visual project. A listing break is simply a blank line, which provides a visual