Skip to main content Link Search Menu Expand Document (external link)

Filters

Table of contents
  1. Filters
    1. Dates
      1. Finding Tasks with Invalid Dates
    2. Text filters
    3. Matching multiple filters
    4. Filters for Dates in Tasks
      1. Done Date
      2. Due Date
      3. Scheduled Date
      4. Start Date
      5. Happens
    5. Filters for Other Task Properties
      1. Description
      2. Priority
        1. Examples
      3. Recurrence
      4. Status
      5. Sub-Items
      6. Tags
        1. Tag Query Examples
    6. Filters for File Properties
      1. File Path
      2. File Name
      3. 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.

Finding Tasks with Invalid Dates

Validation of dates was introduced in Tasks 1.16.0.

It is possible to accidentally use a non-existent date on a task signifier, such as 📅 2022-02-30. February has at most 29 days.

Such tasks look like they have a date, but that date will never be found. When viewed in Reading mode, the date will be shown as Invalid date.

Any such mistakes can be found systematically with this search:

```tasks
(done date is invalid) OR (due date is invalid) OR (scheduled date is invalid) OR (start date is invalid)
```

Warning

If the above search finds any tasks with invalid dates, they are best fixed by clicking on the backlink to navigate to the incorrect line, and fixing it by directly typing in the new date.

If you use the ‘Create or edit Task’ Modal, it will discard the broken date, and there will be no information about the original, incorrect value.


Text filters

Filters that search for text strings have two flavours.

In the following examples, we describe the heading filter, but these comments apply to all the text filters.

  1. heading (includes|does not include) <search text>
    • It matches all tasks in a section whose heading contains the string <search text> at least once.
      • That is, it is a sub-string search.
      • So heading includes Day Planner will match tasks in sections ## Monday Day Planner and ## Day Planner for typical day.
    • It ignores capitalization. Searches are case-insensitive.
      • So heading includes Day Planner will match tasks in sections ## Day Planner and ## DAY PLANNER.
    • Any quote characters (' and ") are included in the search text.
      • So heading includes "Day Planner" will match a section## "Day Planner".
      • But will not match tasks with headings like ## Day Planner.
  2. heading (regex matches|regex does not match) /<JavaScript-style Regex>/
    • Does regular expression match (case-sensitive by default).
    • Regular expression (or ‘regex’) searching is a powerful but advanced feature.
    • It requires thorough knowledge in order to use successfully, and not miss intended search results.
    • It is easy to write a regular expression that looks correct, but which has a special character with a non-obvious meaning.
    • Essential reading: Regular Expression Searches.

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>
  • done date is invalid

no done date and has done date were introduced in Tasks 1.7.0.
done date is invalid was introduced in Tasks 1.16.0.

Due Date

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

has due date was introduced in Tasks 1.6.0.
due date is invalid was introduced in Tasks 1.16.0.

Scheduled Date

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

has scheduled date was introduced in Tasks 1.6.0.
scheduled date is invalid was introduced in Tasks 1.16.0.

Start Date

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

has start date was Introduced in Tasks 1.6.0.
start date is invalid was introduced in Tasks 1.16.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.
  • description (regex matches|regex does not match) /<JavaScript-style Regex>/

regex matches and regex does not match were introduced in Tasks 1.12.0.

For precise searches, it may help to know that description:

  • first removes all each task’s signifier emojis and their values,
  • then removes any global filter,
  • then removes an trailing spaces
  • and then searches the remaining text

For example:

Global Filter Task line Text searched by description
No global filter '- [ ] Do stuff ⏫ #tag1 ✅ 2022-08-12 #tag2/sub-tag ' 'Do stuff #tag1 #tag2/sub-tag'
#task '- [ ] #task Do stuff ⏫ #tag1 ✅ 2022-08-12 #tag2/sub-tag ' 'Do stuff #tag1 #tag2/sub-tag'
global-filter '- [ ] global-filter Do stuff ⏫ #tag1 ✅ 2022-08-12 #tag2/sub-tag ' 'Do stuff #tag1 #tag2/sub-tag'

Priority

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

The available priorities are (from high to low):

  1. ⏫ for high priority
  2. 🔼 for medium priority
  3. use no signifier to indicate no priority
  4. 🔽 for low priority

For more information, see Priorities .

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> or
  • tag (includes|does not include) <tag>
    • 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.
    • If the # is given, it must be present, so searching for #home will match #home but not #location/home.
    • The match is partial so tags include foo will match #foo/bar and #foo-bar.
  • tags (regex matches|regex does not match) /<JavaScript-style Regex>/ or
  • tag (regex matches|regex does not match) /<JavaScript-style Regex>/
    • Does regular expression match (case-sensitive by default).
    • Essential reading: Regular Expression Searches.
    • This enables tag searches that avoid sub-tags, by putting a $ character at the end of the regular expression. See examples below.
    • If searching for sub-tags, remember to escape the slashes in regular expressions: \/

regex matches and regex does not match were introduced in Tasks 1.13.0.

Tag Query Examples

  • tags include #todo
  • tags do not include #todo
  • tag regex matches /#t$/
    • Searches for a single-character tag #t, with no sub-tags, because $ matches the end of the tag text.
  • tag regex matches /#book$/i
    • The trailing i means case-insensitive.
    • Searches for tags such as #book, #Book, #BOOK and the $ prevents matching of #books, #book/literature, etc.

Filters for File Properties

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

File Path

Note that the path includes the .md extension.

  • path (includes|does not include) <path>
    • Matches case-insensitive (disregards capitalization).
  • path (regex matches|regex does not match) /<JavaScript-style Regex>/

regex matches and regex does not match were introduced in Tasks 1.12.0.

File Name

Introduced in Tasks 1.13.0.

Note that the file name includes the .md extension.

  • filename (includes|does not include) <filename>
    • Matches case-insensitive (disregards capitalization).
  • filename (regex matches|regex does not match) /<JavaScript-style Regex>/

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).
  • heading (regex matches|regex does not match) /<JavaScript-style Regex>/
    • Whether or not the heading preceding the task includes the given regular expression (case-sensitive by default).
    • Always tries to match the closest heading above the task, regardless of heading level.
    • regex does not match will match a task that does not have a preceding heading in its file.
    • Essential reading: Regular Expression Searches.

regex matches and regex does not match were introduced in Tasks 1.12.0.