Link Search Menu Expand Document (external link)

Filters

Table of contents
  1. Filters
    1. Dates
    2. Matching multiple filters
    3. Filters for Dates in Tasks
      1. Done Date
      2. Due Date
      3. Scheduled Date
      4. Start Date
      5. Happens
    4. Filters for Other Task Properties
      1. Description
      2. Priority
        1. Examples
      3. Recurrence
      4. Status
      5. Sub-Items
      6. Tags
        1. Tag Query Examples
    5. Filters for File Properties
      1. File Path
      2. Heading

Dates

<date> filters can be given in natural language or in formal notation. The following are some examples of valid <date> filters as inspiration:

  • 2021-05-25
  • yesterday
  • today
  • tomorrow
  • next monday
  • last friday
  • 14 days ago
  • in two weeks

Note that if it is Wednesday and you write tuesday, Tasks assumes you mean “yesterday”, as that is the closest Tuesday. Use next tuesday instead if you mean “next tuesday”.

When the day changes, relative dates like due today are re-evaluated so that the list stays up-to-date.


Matching multiple filters

Boolean combinations were introduced in Tasks 1.9.0

Each line of a query has to match in order for a task to be listed. In other words, lines are considered to have an ‘AND’ operator between them. Within each line, you can use the boolean operators NOT, AND, OR, AND NOT, OR NOT and XOR, as long as individual filters are wrapped in parentheses:

```tasks
(no due date) OR (due after 2021-04-04)
path includes GitHub
```

```tasks
due after 2021-04-04
(path includes GitHub) AND NOT (tags include #todo)
```

For full details of combining filters with boolean operators, see Combining Filters.


Filters for Dates in Tasks

Done Date

  • done
  • not done
  • no done date
  • has done date
  • done (before|after|on) <date>

no done date and has done date were introduced in Tasks 1.7.0.

Due Date

  • no due date
  • has due date
  • due (before|after|on) <date>

has due date was introduced in Tasks 1.6.0.

Scheduled Date

  • no scheduled date
  • has scheduled date
  • scheduled (before|after|on) <date>

has scheduled date was introduced in Tasks 1.6.0.

Start Date

  • no start date
  • has start date
  • starts (before|after|on) <date>

has start date was Introduced in Tasks 1.6.0.

When filtering queries by start date, the result will include tasks without a start date. This way, you can use the start date as a filter to filter out any tasks that you cannot yet work on.

Such filter could be:

```tasks
starts before tomorrow
```

Happens

  • happens (before|after|on) <date>

happens returns any task for a matching start date, scheduled date, or due date. For example, happens before tomorrow will return all tasks that are starting, scheduled, or due earlier than tomorrow. If a task starts today and is due in a week from today, happens before tomorrow will match, because the tasks starts before tomorrow. Only one of the dates needs to match.

  • no happens date
    • Return tasks where none of start date, scheduled date, and due date are set.
  • has happens date
    • Return tasks where any of start date, scheduled date, or due date are set.

no happens date and has happens date were introduced in Tasks 1.7.0.

Filters for Other Task Properties

As well as the date-related searches above, these filters search other properties in individual tasks.

Description

  • description (includes|does not include) <string>
    • Matches case-insensitive (disregards capitalization).
    • Disregards the global filter when matching.

Priority

  • priority is (above|below)? (low|none|medium|high)

Examples

```tasks
not done
priority is above none
```

```tasks
priority is high
```

Recurrence

  • is recurring
  • is not recurring

Status

  • done
  • not done

Sub-Items

  • exclude sub-items
    • When this is set, the result list will only include tasks that are not indented in their file. It will only show tasks that are top level list items in their list.

Tags

Introduced in Tasks 1.6.0.

  • tags (include|do not include) <tag> (Alternative grammar tag (includes|does not include) <tag> matching description syntax)
    • Matches case-insensitive (disregards capitalization).
    • Disregards the global filter when matching.
    • The # is optional on the tag so #home and home will work to match #home.
    • The match is partial so tags include foo will match #foo/bar and #foo-bar.

Tag Query Examples

  • tags include #todo
  • tags do not include #todo

Filters for File Properties

These filters allow searching for tasks in particular files and sections of files.

File Path

  • path (includes|does not include) <path>
    • Matches case-insensitive (disregards capitalization).

Heading

  • heading (includes|does not include) <string>
    • Whether or not the heading preceding the task includes the given string.
    • Always tries to match the closest heading above the task, regardless of heading level.
    • does not include will match a task that does not have a preceding heading in its file.
    • Matches case-insensitive (disregards capitalization).