Grouping
Table of contents
Basics
Introduced in Tasks 1.6.0.
By default, Tasks displays tasks in a single list.
To divide the matching tasks up with headings, you can add group by
lines to the query.
Available grouping properties
You can group by the following properties:
File locations:
path
(the path to the file that contains the task, that is, the folder and the filename)root
(the top-level folder of the file that contains the task, that is, the first directory in the path, which will be/
for files in root of the vault)folder
(the folder to the file that contains the task, which will be/
for files in root of the vault)filename
(the filename of the file that contains the task, without the.md
extension)- Note that tasks from different notes with the same file name will be grouped together in the same group.
root
grouping option was introduced in Tasks 1.11.0.
File contents:
backlink
(the text that would be shown in the task’s backlink, combining the task’s file name and heading, but with no link added)heading
(the heading preceding the task, or(No heading)
if there are no headings in the file)
Task date properties:
start
- The start date of the task, including the week-day, or
No start date
.
- The start date of the task, including the week-day, or
scheduled
- The scheduled date of the task, including the week-day, or
No scheduled date
.
- The scheduled date of the task, including the week-day, or
due
- The due date of the task, including the week-day, or
No due date
.
- The due date of the task, including the week-day, or
done
- The done date of the task, including the week-day, or
No done date
.
- The done date of the task, including the week-day, or
happens
- The earliest of start date, scheduled date, and due date, including the week-day, or
No happens date
if none of those are set.
- The earliest of start date, scheduled date, and due date, including the week-day, or
happens
grouping option was introduced in Tasks 1.11.0.
Task properties - other:
status
(Done or Todo, which is capitalized for visibility in the headings)- Note that the Done group is displayed before the Todo group, which differs from the Sorting ordering of this property.
priority
- The priority of the task, namely one of:
Priority 1: High
Priority 2: Medium
Priority 3: None
Priority 4: Low
- The priority of the task, namely one of:
recurring
- Whether the task is recurring: either
Recurring
orNot Recurring
.
- Whether the task is recurring: either
recurrence
- The recurrence rule of the task, for example
every week on Sunday
, orNone
for non-recurring tasks. - Note that the text displayed is generated programmatically and standardised, and so may not exactly match the text in any manually typed tasks. For example, a task with
🔁 every Sunday
is grouped inevery week on Sunday
.
- The recurrence rule of the task, for example
tags
- The tags of the tasks or
(No tags)
. If the task has multiple tags, it will show up under every tag.
- The tags of the tasks or
start
,scheduled
,due
anddone
grouping options were introduced in Tasks 1.7.0.
tags
grouping option was introduced in Tasks 1.10.0.
priority
,recurring
andrecurrence
grouping options were introduced in Tasks 1.11.0.
Multiple groups
You can add multiple group by
query options, each on an extra line. This will create nested groups. The first group has the highest priority.
Each subsequent group by
will generate a new heading-level within the existing grouping:
- First
group by
is displayed ash4
headings - Second
group by
is displayed ash5
headings - Third and subsequent
group by
are displayed ash6
headings
See the screenshots below for how this looks in practice.
Info
Headings are displayed in case-sensitive alphabetical order, not the original order.
Info
The order of operations ensures that grouping does not modify which tasks are displayed, for example when the limit
option is used:
- all the filter instructions are run
- then any sorting instructions are run
- then any
limit
instructions are run - then finally any grouping instructions are run
Screenshots
Before
Here is an example Tasks result, without any group by
commands:
Tasks not grouped.
After
And here is what this might look like, when grouped by folder, filename and heading:
Tasks grouped.
Examples
```tasks
not done
group by folder
group by filename
group by heading
```