Skip to content

Commit e9d2cf0

Browse files
authored
docs: Overhaul the Filters documentation (#828)
* docs: Add 'days ago' to filter date examples. Based on feedback in #819. Also make yyyy-mm-dd example unambiguous. And add 'yesterday', for completion. * docs: Divide filters list logically & note OR workaround The list of available filters had become long and a little hard to read and find patterns in. This groups related filters together, for readability and structure. * docs: Make 'done' and 'not done' more prominent in docs They were previously only listed under 'done date' which was useful, but not entirely accurate. * docs: Sort sub-headings alphabetically, for readability * docs: Add brief intros to the new sections
1 parent 748eb75 commit e9d2cf0

File tree

1 file changed

+59
-44
lines changed

1 file changed

+59
-44
lines changed

docs/queries/filters.md

Lines changed: 59 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,13 @@ parent: Queries
2525
`<date>` filters can be given in natural language or in formal notation.
2626
The following are some examples of valid `<date>` filters as inspiration:
2727

28-
- `2021-05-05`
28+
- `2021-05-25`
29+
- `yesterday`
2930
- `today`
3031
- `tomorrow`
3132
- `next monday`
3233
- `last friday`
34+
- `14 days ago`
3335
- `in two weeks`
3436

3537
Note that if it is Wednesday and you write `tuesday`, Tasks assumes you mean "yesterday", as that is the closest Tuesday.
@@ -39,7 +41,7 @@ When the day changes, relative dates like `due today` are re-evaluated so that t
3941

4042
---
4143

42-
## Matching
44+
## Matching - Workaround for Boolean OR
4345

4446
All filters of a query have to match in order for a task to be listed.
4547
This means you cannot show tasks that have "GitHub in the path and have no due date or are due after 2021-04-04".
@@ -61,7 +63,7 @@ Instead you would have two queries, one for each condition:
6163

6264
---
6365

64-
## List of Available Filters
66+
## Filters for Dates in Tasks
6567

6668
### Done Date
6769

@@ -73,22 +75,21 @@ Instead you would have two queries, one for each condition:
7375

7476
> `no done date` and `has done date` were introduced in Tasks 1.7.0.
7577
76-
### Priority
78+
### Due Date
7779

78-
- `priority is (above|below)? (low|none|medium|high)`
80+
- `no due date`
81+
- `has due date`
82+
- `due (before|after|on) <date>`
7983

80-
#### Examples
84+
> `has due date` was introduced in Tasks 1.6.0.
8185
82-
{: .no_toc }
86+
### Scheduled Date
8387

84-
```tasks
85-
not done
86-
priority is above none
87-
```
88+
- `no scheduled date`
89+
- `has scheduled date`
90+
- `scheduled (before|after|on) <date>`
8891

89-
```tasks
90-
priority is high
91-
```
92+
> `has scheduled date` was introduced in Tasks 1.6.0.
9293
9394
### Start Date
9495

@@ -108,22 +109,6 @@ Such filter could be:
108109
starts before tomorrow
109110
```
110111

111-
### Scheduled Date
112-
113-
- `no scheduled date`
114-
- `has scheduled date`
115-
- `scheduled (before|after|on) <date>`
116-
117-
> `has scheduled date` was introduced in Tasks 1.6.0.
118-
119-
### Due Date
120-
121-
- `no due date`
122-
- `has due date`
123-
- `due (before|after|on) <date>`
124-
125-
> `has due date` was introduced in Tasks 1.6.0.
126-
127112
### Happens
128113

129114
- `happens (before|after|on) <date>`
@@ -140,29 +125,42 @@ because the tasks starts before tomorrow. Only one of the dates needs to match.
140125

141126
> `no happens date` and `has happens date` were introduced in Tasks 1.7.0.
142127
143-
### Recurrence
128+
## Filters for Other Task Properties
144129

145-
- `is recurring`
146-
- `is not recurring`
147-
148-
### File Path
149-
150-
- `path (includes|does not include) <path>`
151-
- Matches case-insensitive (disregards capitalization).
130+
As well as the date-related searches above, these filters search other properties in individual tasks.
152131

153132
### Description
154133

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

159-
### Heading
138+
### Priority
160139

161-
- `heading (includes|does not include) <string>`
162-
- Whether or not the heading preceding the task includes the given string.
163-
- Always tries to match the closest heading above the task, regardless of heading level.
164-
- `does not include` will match a task that does not have a preceding heading in its file.
165-
- Matches case-insensitive (disregards capitalization).
140+
- `priority is (above|below)? (low|none|medium|high)`
141+
142+
#### Examples
143+
144+
{: .no_toc }
145+
146+
```tasks
147+
not done
148+
priority is above none
149+
```
150+
151+
```tasks
152+
priority is high
153+
```
154+
155+
### Recurrence
156+
157+
- `is recurring`
158+
- `is not recurring`
159+
160+
### Status
161+
162+
- `done`
163+
- `not done`
166164

167165
### Sub-Items
168166

@@ -183,3 +181,20 @@ because the tasks starts before tomorrow. Only one of the dates needs to match.
183181

184182
- `tags include #todo`
185183
- `tags do not include #todo`
184+
185+
## Filters for File Properties
186+
187+
These filters allow searching for tasks in particular files and sections of files.
188+
189+
### File Path
190+
191+
- `path (includes|does not include) <path>`
192+
- Matches case-insensitive (disregards capitalization).
193+
194+
### Heading
195+
196+
- `heading (includes|does not include) <string>`
197+
- Whether or not the heading preceding the task includes the given string.
198+
- Always tries to match the closest heading above the task, regardless of heading level.
199+
- `does not include` will match a task that does not have a preceding heading in its file.
200+
- Matches case-insensitive (disregards capitalization).

0 commit comments

Comments
 (0)