Work in Progress

This design document is a work in progress, and subject to change. Once finalized, the feature will be scheduled for an upcoming release.

CLI Syntax Update

The Taskwarrior command line syntax is being updated to allow more consistent and predictable results, while making room for new features.

Adding support for arbitrary expressions on the command line has become complicated because of the relaxed syntax of Taskwarrior. While the relaxed syntax allows for a very expressive command line, it also creates ambiguity for the parser, which needs to be reduced.

With some limited and careful changes it will be possible to have a clear and unambiguous command line syntax, which means a predictable and deterministic experience.

It should be stated that for straightforward and even current usage patterns, the command line will likely not change for you. Another goal is to not require changes to 3rd-party software, where possible. Only the more advanced and as-yet unintroduced features will require a more strict syntax. This is why now is an ideal time to tighten the requirements.

Argument Types

The argument types supported remain the same, adding some new constructs.

Config file override rc:<file>
Configuration override rc:<name>:<value> Literal value
rc:<name>=<value> Literal value
rc:<name>:=<value> Calculated value
Tag +<tag>
'+tag one' Multi-word tag
Attribute modifier rc:<name>.<modifier>:<value>
Modifier is one of:
Search pattern /<pattern>/
Substitution /<from>/<to>/
Command add
Separator --
ID Ranges <id>[-<id>][,<id>[-<id>]...]
UUID <uuid>
Everything Else <word>
'<word> <word> ...'

New Command Line Rules

Certain command line constructs will no longer be supported, and this is imposed by the new rules:

  1. Each command line argument may contain only one instance of one argument type, unless that type is <word>.
    task add project:Home +tag Repair the thing     # Good
    task add project:Home +tag 'Repair the thing'   # Good
    task add 'project:Home +tag Repair the thing'   # Bad
    Putting two arguments into one quoted arg makes that arg a <word>.
  2. If an argument type contains spaces, it must either be quoted or escaped.
    task add project:'Home & Garden' ...    # Good
    task add 'project:Home & Garden' ...    # Good
    task add project:Home\ \&\ Garden ...   # Good
    task add project:Home' & 'Garden ...    # Good
    task add project:Home \& Garden ...     # Bad
    The parser will not combine multiple arguments, for example:
    task '/one two/' list   # Good
    task /one two/ list     # Bad
    task /'one two'/ list   # Bad, unless ' is part of the pattern
  3. By default, no calculations are made, unless the := eval operator is used, and if so, the whole argument may need to be quoted or escaped to satisfy Rule 1.
    task add project:3.project+x         # Literal
    task add project:=3.project+x        # DOM reference + concatenation
  4. Bare word search terms are no longer supported. Use the pattern type argument instead.
    task /foo/ list     # Good
    task foo list       # Bad
  5. Expressions must be a series of arguments, not a quoted string.
    task urgency \< 5.0 list     # Good
    task 'urgency < 5.0 list'    # Bad

Other Changes

Aside from the command line parser, there are other changes needed:

  • Many online documents will need to be modified.
  • Filters will be automatically parenthesized, so that every command line will now looke like:
    task [overrides] [(cli-filter)] [(context-filter)] [(report-filter)] command [modifications]
  • There will be more errors when the command line is not understood.
  • Ambiguous ISO date formats are dropped.
    YYYYMMDD     # Bad
    YYYY-MM-DD   # Good
    hhmmss       # Bad
    hh:mm:ss     # Good
  • The tutorial videos will be even more out of date, and will be replaced by a large number of smaller demo 'movies'.