obsidian-plugin-tasks

Important Prerequisites The Tasks plugin is an active task management system: unlike Dataview, the Tasks plugin directly modifies the contents of source files (for example, completing tasks and updating recurring tasks). All modifications follow strict rules to ensure data consistency. Query results support interaction (such as checkboxes), and checking them automatically updates the source files.

⚠️ Critical Data Safety Warning

Important Safety Notice

Direct File Modification: The Tasks plugin directly modifies source file contents, including operations such as automatic completion and recurring task generation
Backup Recommendations：
- Enable Obsidian's automatic backup feature (Settings → Core plugins → Backup)
- Configure Git version control and commit changes regularly
- Before enabling recurrence rules and automatic completion, ensure you have a reliable backup mechanism
- Important: Back up regularly .obsidian/plugins/obsidian-tasks/data.json file, which contains your custom status configuration
Data Recovery Procedure：
1. Close Obsidian
2. Delete.obsidian/plugins/obsidian-tasks/cachedirectory (safe operation)
3. Restart the app and wait for indexing to complete (a large vault may take 5-10 minutes)

🚨 Last Resort: Reset Plugin Configuration

Warning: This operation will cause all Custom Statuses configuration to be lost

Close Obsidian
You must back up first .obsidian/plugins/obsidian-tasks/data.json file
Delete in the vault directory.obsidian/plugins/obsidian-tasks/data.json
Restart the app and wait for indexing to complete

Consequences: data.json stores the definitions of all custom statuses. If you delete it without a backup, symbols such as [/] and [-] will lose the "logical properties" behind them, causing queries to fail.

Multi-User Environment Warning: In Git-synced or team-shared vaults, avoid editing the same task simultaneously on different devices. Automatic modifications by the Tasks plugin may cause merge conflicts

⚠️ Global Filter Trap

Feature Description: The Tasks plugin has a core setting — Global Filter (for example, #task)
Behavior: If Global Filter is enabled, all tasks must contain that tag
Serious Consequences：
- Tasks that do not contain the tag will not appear in queries
- ignore global query cannot skip this restriction (because the plugin simply does not index these lines)
- This is a limitation at the indexing level, not filtering at the query level

Global Filter Side Effects：

Automatic Tagging: After enabling the global filter, tasks generated by the task modal (Create or edit task) will automatically carry that tag
Instant Evaporation: If you manually delete the tag, the task will instantly vanish from all Tasks query results, without any error being reported
Migration Warning: After enabling the global filter, tags need to be added to all existing tasks, which is a migration process that requires careful operation

⚠️ Additional Data Safety Warning

Sync Conflicts

Risk: If you use Obsidian Sync or iCloud, the frequent file modifications by the Tasks plugin can easily produce .sync-conflict copies during synchronization
Recommendations：
- Disable the "automatic task status conversion" feature, or
- Ensure single-device editing, avoiding simultaneous operations on multiple devices
- Regularly check for and clean up sync conflict files

Version Control Conflicts

Git Considerations: When using Git version control, automatic modifications by Tasks may cause frequent merge conflicts
Best Practices: Use git pull --rebase to reduce conflicts, and commit changes regularly

Tasks Plugin User Guide

I. Basic Syntax

Basic Task Structure

- [ ] 基本任务
- [x] 已完成任务
- [/] 部分完成（进行中）
- [-] 已取消

Task Metadata Fields

Tasks store rich information through inline fields (end-of-line metadata), strictly following the format specifications:

- [ ] 任务文本 [元数据:: 值]

Core Metadata Fields

Field	Format	Description	Example
Due Date	📅 YYYY-MM-DD or due:: YYYY-MM-DD	Task due date	📅 2024-12-31
Scheduled Date	⏳ YYYY-MM-DD or scheduled:: YYYY-MM-DD	The date when the task should start being handled	⏳ 2024-12-25
Created Date	➕ YYYY-MM-DD or created:: YYYY-MM-DD	Task creation date	➕ 2024-12-20
Start Date	🛫 YYYY-MM-DD or start:: YYYY-MM-DD	The date when the task can start	🛫 2024-12-25
Priority	🔺 highest, ⏫ high, 🔼 medium, 🔽 low, ⏬ lowest or priority:: (highest	high	medium
Recurrence Rule	🔁 (every day	every week	every month
Dependency Task	⛔ task123 or dependsOn:: task123	Task dependency	⛔ task123
Task ID	🆔 task123	Task identifier, used for dependency references	🆔 task1
Completion Date	✅ YYYY-MM-DD	Task completion time	✅ 2024-12-31

Priority Markers (Official Standard)

Priority	Emoji Marker	Query Value	Numeric Mapping
Highest	🔺	highest	1
High	⏫	high	2
Medium	🔼	medium	3
Low	🔽	low	4
Lowest	⏬	lowest	5
None	(no symbol)	none	(no value)

Important：

Priority Emojis only have arrow symbols, and no 🔴🟡🟢 colored dots!
Parsing Logic: The Tasks plugin's parser parses metadata from the end of the line backward
- Priority can be placed before or after the date
- Absolutely must notbe placed in the middle of the description text
- It must be separated from other content by spaces
Unicode Character Difference Warning: These are Unicode characters, and their appearance will have subtle differences under different operating systems (iOS vs Windows) and fonts, making manual input extremely error-prone.
Strongly Recommended: Set the priority through the modal: use Tasks: Create or edit command opens a modal to avoid errors from manually entering Emoji.

Priority query syntax extension

Comparison queries

Syntax：
- priority is above medium(higher than medium priority)
- priority is below high(lower than high priority)
Priority order：Highest > High > Medium > Low > Lowest
Examples：
- priority is above medium matches Highest and High
- priority is below high matches Medium, Low, and Lowest

Detailed explanation of numeric mapping

Internal numeric value：
- Highest (1) < High (2) < Medium (3) < Low (4) < Lowest (5)
Comparison logic：
- priority is above medium actually queries tasks with numeric value < 3
- priority is below high actually queries tasks with numeric value > 2
Performance optimization: numeric comparisons are more efficient than string comparisons in large libraries

No-priority queries

Syntax：priority is none
Function: matches tasks with no priority set
Use case: used to find tasks with no priority set, so that they can be categorized by priority

Date type mapping (official standard)

Date type	Emoji identifier	Inline field	Description	Automatic behavior
Due	📅	due::	Task due date	Added manually
Scheduled	⏳	scheduled::	Task scheduled start date	Added manually
Start	🛫	start::	Task start date	Added manually
Created	➕	created::	Task creation date	Added manually
Completion	✅	completion::	Task completion date	Automatically added when the task is completed
Cancelled	❌	cancelled::	Task cancellation date	Automatically added when the task is cancelled (requires enabling Record date of cancellation in settings)

Difference between completion and done

Important difference：

completion (completion date): the completion date automatically added by the Tasks plugin, using the ✅ symbol, in the format✅ 2024-12-31, indicating the time the task was actually completed
- Automatically added: automatically added when completing a task, unless it is disabled in settings and Obsidian is restarted
done (completion status): indicates the completion status of a task, used in Tasks queries withdoneornot donefiltering, corresponding to thetask.completedboolean field in Dataview

Use cases：

Use thecompletionfield: when you need to query the specific completion time of a task, such ascompleted after last week
Use thedonestatus: when you only need to filter tasks by completion status and do not care about the specific completion time

Correspondence in Dataview：

task.completed(boolean): corresponds to the Tasksdonestatus
task.textmay contain✅ 2024-12-31: but it needs to be extracted from the text; Dataview does not have a directtask.completionfield

Date format and time zone notes

Date format：

Strictly use the YYYY-MM-DD format (no time, no [[wiki links]])
Invalid dates are silently ignored in queries

Time Zone Handling：

All dates are based on the local time zone, with no UTC support
Mismatched time zones across devices may cause date shifts
It is recommended that all collaborating devices use the same system time zone setting

Task IDs and Block References

Task ID (Official Standard)

Format: Use the 🆔 symbol, e.g.- [ ] 任务描述 🆔 task1
Inline field：id:: task1
Purpose: Used for dependency references and task identification
Dependency reference: Use the task ID value in dependencies, e.g.dependsOn:: task1or⛔ task1

Block reference (Obsidian standard feature)

Format：^block-id(Obsidian standard block reference format)
Characteristics: Composed of letters, numbers, hyphens, and underscores
Purpose: Used to reference a specific paragraph or task in Obsidian
Note: This is an Obsidian standard feature and is a different concept from the Tasks plugin's task ID

Important Distinction

Task ID: Unique to the Tasks plugin, used for dependencies, format is🆔 task123
Block ID: Obsidian standard feature, used for block references, format is^block-id
Dependency reference: Uses task ID values (e.g.task123), not block references (e.g.^block-id）

Detailed Mechanism of Task Dependencies

Dependency syntax：dependsOn:: task123 or use the ⛔ symbol (e.g. ⛔ task123）
Dependency target: Depends on a task ID, not a file block reference (^block-id)
Example：
- dependsOn:: abc123(inline field format)
- ⛔ abc123(Emoji format)
Dependency status：
- ⛔ When the dependency task is incomplete, the blocked task is shown as 'blocked'
- ✅ When the dependency task is completed, the blocked task automatically becomes available and is shown as 'unblocked' in queries
Dependency chaining: Supports multi-level dependency chains (task A depends on task B, task B depends on task C)
Cycle detection: The system detects and warns about dependency cycles to avoid deadlocks
- Display: Shows a ⚠️ icon next to the task; hovering shows "circular dependency"
- Handling: Automatically sets the status to "cannot-complete" and blocks the completion operation
- Resolution: Requires manually breaking the dependency chain by removing or modifying the dependency relationships that cause the cycle
Important Note: The dependency field is removed from the next recurring task

Dependency Query Syntax

Official query syntax：

depends on <id> - Query tasks that depend on a specific ID
is blocked - Query blocked tasks
is blocking - Query tasks that are blocking other tasks

Example：

is blocked
not done
sort by due

Strict Format Requirements

Date format: Must use ISO format (YYYY-MM-DD); other formats will be ignored Emoji date identifiers: The system only recognizes predefined emojis (📅⏳➕🛫); custom emojis are invalid Priority identifiers: Use arrow emojis (�⏫��⏬️), not colored dots

YAML frontmatter priority

Important: Fields in YAML frontmatter take precedence over inline metadata.

Example：

---
due: 2024-12-31
---
- [ ] 任务文本 📅 2025-01-15

Actual effect: The task's due date is 2024-12-31 (the YAML value overrides the inline value)

⚠️ The "read-only" trap of YAML Frontmatter

Key limitation: The Tasks plugin cannot automatically modify data in YAML

Serious consequences：

If you define due in YAML, when you check off a recurring task in the Tasks interface, the plugin will fail to update the date or generate an incorrect task because it cannot modify the YAML
This will break the normal workflow of recurring tasks

Strict prohibition: Do not use YAML metadata on tasks that require "interaction" (such as checking off or updating dates)

Recommended practice: For tasks that need to interact with the Tasks plugin, use inline metadata (such as 📅 2024-12-31) instead of YAML

Space requirements

Strict specification: There must be a separation boundary of at least one space between the metadata and the task text or tags; using two spaces is recommended to ensure parsing stability

Key reminder: In tasks with tags, if the metadata immediately follows the tag (such as #tag📅2023), the parser will 100% fail

# 推荐示例
- [ ] 任务文本  📅 2024-12-31
- [ ] 任务文本 #tag  📅 2024-12-31

# 也可工作但不推荐
- [ ] 任务文本 📅 2024-12-31

# 错误示例
- [ ] 任务文本📅 2024-12-31
- [ ] 任务文本 #tag📅2024-12-31

Recurring task rule engine

Recurrence syntax (official standard)

Important rule: All recurrence rules must start with every , which is the required syntax mandated by the official specification.

- [ ] 每日任务 🔁 every day
- [ ] 每周任务（完成时更新起始日期） 🔁 every week when done: start
- [ ] 每月15号 🔁 every month on the 15th
- [ ] 每季度首日 🔁 every 3 months on the 1st
- [ ] 每年生日 🔁 every year on December 31

Complete recurrence rule syntax table (all officially supported patterns)

Rule type	Syntax example	Description
Daily recurrence	🔁 every day	Repeat every day
Weekly recurrence	🔁 every week	Repeat every week
Monthly recurrence	🔁 every month	Repeat every month
Yearly recurrence	🔁 every year	Repeat every year
Weekday recurrence	🔁 every weekday	Repeat every weekday (Monday to Friday)
Interval recurrence	🔁 every 3 days	Repeat every 3 days
Interval recurrence	🔁 every 2 weeks	Repeat every 2 weeks
Interval recurrence	🔁 every 6 months	Repeat every 6 months
Specific day of week	🔁 every week on Sunday	Repeat every Sunday
Specific day of week	🔁 every week on Tuesday, Friday	Repeat every Tuesday and Friday
Interval specific day of week	🔁 every 2 weeks on Sunday	Repeat every 2 weeks on Sunday
Specific day of month	🔁 every month on the 15th	Repeat on the 15th of every month
Last day of month	🔁 every month on the last	Repeat on the last day of every month
Last specific day of month	🔁 every month on the last Friday	Repeat on the last Friday of every month
Second-to-last specific day of month	🔁 every month on the 2nd last Friday	Repeat on the second-to-last Friday of every month
Interval specific day of month	🔁 every 3 months on the 1st	Repeat on the 1st of every 3 months
Specific day in specific month	🔁 every January on the 15th	Repeat every year on January 15
Complex combination	🔁 every April and December on the 1st and 24th	Repeat every year on April 1, April 24, December 1, and December 24
Update on completion	🔁 every day when done: start	Update the start date on completion
Update on completion	🔁 every week when done: due	Update due date upon completion
Update upon completion	🔁 every month when done: both	Update both start and due dates upon completion

Recurring task lifecycle

Create: initial task creation
Complete: user checks off the task
- Important trigger point: the completion action must be triggered in the Tasks query results view or via a plugin command
- Note: if you manually change [ ] to [x] in pure editor mode, the plugin may not trigger the creation of a new task (depending on index status and settings)
Generate new task: the original task is marked as complete, and the system creates a brand-new task
Update: update date fields according to the rules
- when done: start: update only the start date
- when done: due: update only the due date
- when done: both: update both start and due dates
- Default behavior: if when doneis not specified, the "Relative to the original date" logic is used
  - Deep detail: calculated based on the original scheduled date, not the current date
  - Important warning: if the original task is 5 days overdue, the newly generated task will also be based on the original scheduled date, not today. This is critical for habit tracking
  - Key addition: if the task has no due date (Due Date), the recurrence rule will default to being calculated based on the "completion date" (Completion Date)

Anchor date logic: Tasks' default logic is determined by the priority of the existing date fields:

If there is a due date, offset based on the original due date
If there is no due date but there is a scheduled date, offset based on the original scheduled date
If there is no due date or scheduled date but there is a start date, offset based on the original start date
If there is no date field at all, when done is mandatory or it defaults to failure

Smart correction feature：

When using every weekday , even if the original task is on Saturday, the new task will automatically be corrected to Monday
The system intelligently avoids weekends, ensuring tasks fall on weekdays

Keep: the original task status changes to [x], and a completion date is added

Important warnings and limitations

Required condition: a recurring task must have at least one date field (due/scheduled/start) to work properly
Invalid date: an invalid date (such as February 30) causes the recurrence rule to disappear and no new task will be generated
Dependency handling: the dependency field (dependsOn) will be removed from the next recurring task
Daily note caution: using recurring tasks in daily notes is not recommended, as duplicate entries may be created
Feature limitation: "for x times" or "until date" syntax is not supported
Block ID retention: when a recurring task is generated, the plugin decides according to settings whether to retain the block ID (^block-id)
- Tasks 5.x default behavior: retain the block ID to maintain reference integrity
- Purpose: Ensure links and references to other notes remain valid
Infinite loop defense: When the task date exceeds 100 years, repetition automatically stops
History: The original task is not deleted, but marked as completed, preserving the full history
Timezone handling: All dates are based on the local timezone, with no UTC conversion

Timezone edge cases

Cross-timezone collaboration: All devices should be set to the same system timezone to avoid date calculation discrepancies
Recurring tasks: May be skipped or duplicated on timezone change days (such as daylight saving time transitions)
Mobile devices: Automatic timezone switching may cause date offsets
Query behavior：today Based on the current date in the local timezone, devices in different timezones may see different results

II. Standard queries

Query basic structure

not done
due after 2024-12-20
sort by due
limit 10

Must be marked as tasks in a code block, with one query instruction per line.

Basic query commands

Filter commands

Command	Description	Example
done/not done	Filter completed/incomplete tasks	not done
due [before	after] YYYY-MM-DD	Filter due date
scheduled [before	after] YYYY-MM-DD	Filter scheduled date
start [before	after] YYYY-MM-DD	Filter start date
created [before	after] YYYY-MM-DD	Filter created date
happens [before	after] YYYY-MM-DD	Compound date query (includes one of due, scheduled, or start)
priority is (highest	high	medium
priority is not (highest	high	medium
priority equals (highest	high	medium
path [includes	does not include] "text"	Filter by file path
root	Query only tasks in the root directory	root
folder/path	Query a specific folder	"Tasks/Work"
description [includes	does not include] "text"	Filter by task description
has [due	scheduled	start
no [due	scheduled	start
is recurring/is not recurring	Filter recurring/non-recurring tasks	is recurring

Path query instructions

root instruction

Function: Query only tasks in the root directory, excluding tasks in subfolders
Use case: When you only care about tasks in the root directory and do not need to view subfolder contents
Example：

root
not done
sort by due

folder instruction

Function: Query tasks in a specific folder
Syntax: Use a folder path, such as"Tasks/Work"
Use case: When you need to focus on tasks in a specific folder, such as work tasks, personal tasks, etc.
Example：

"Tasks/Work"
not done
sort by due

Date keywords

Basic dates: today, tomorrow, yesterday
Relative dates：
- in N days, N days ago
- in 2 weeks, 3 weeks ago
- in 1 month, 2 months ago
Week-related: this week, next week, last week
Month-related: this month, next month, last month
Quarter-related: this quarter, next quarter, last quarter
Year-related: this year, next year, last year

III. Advanced Features

Status Type Query System (Tasks 4.0+)

Status Type works with the custom status system to provide five categories of statuses:

Status Type	Match`not done`	Match`done`	Typical Symbol
TODO	✅	❌	[ ]
IN_PROGRESS	✅	❌	[/]
DONE	❌	✅	[x]
CANCELLED	❌	✅	[-]
NON_TASK	❌	✅	[~]

Query Syntax：

status.type is IN_PROGRESS
status.type is not CANCELLED

Important Distinctions：

status.type is TODO Only matches tasks that have not started
not done Matches both TODO and IN_PROGRESS statuses
status.type is DONE Only matches completed tasks
done Matches the three statuses DONE, CANCELLED, and NON_TASK

Custom Status Notes

Configuration Requirements：

Custom statuses need to be configured in Obsidian Settings → Plugins → Tasks → Statuses
Custom CSS may be needed to beautify the display

Default Behavior：

Unknown status symbols default to the TODO type
Status type matching in queries is case-insensitive (Tasks 5.0+)

⚠️ The 'forced symbol' trap in status transitions

nextStatus Configuration Risk：

If nextStatus is set to a space " ", clicking will cause the status to cycle and it will not work properly
It is recommended to set an explicit next status for each status

CSS Dependency Warning：

When using custom statuses (such as [/] IN_PROGRESS), if the corresponding CSS is not loaded, Obsidian's native renderer will render [/] as a checkbox with a slash, but it cannot be clicked or interacted with
Must remind: users need to install a CSS theme that supports custom statuses (such as Minimal) or add custom CSS
Compatibility: support for custom statuses on mobile is still poor, and icons may display abnormally

Dependency Management

Task Dependency Syntax

Dependency Syntax：dependsOn:: task123 Or use the ⛔ symbol (such as ⛔ task123）
Dependency Target: what is depended on is the task ID, not a file block reference
Example：
- dependsOn:: abc123(inline field format)
- ⛔ abc123(Emoji format)

Dependency Status

Blocked: when the dependency task is not completed, the blocked task is displayed with the 'blocked' status
Available: after the dependency task is completed, the blocked task automatically becomes available and is displayed as 'unblocked' in queries

Dependency Queries

Query blocked tasks：is blocked
Query unblocked tasks：is not blocked
Query tasks with dependencies：depends on task123

Circular Dependency Detection

Display: show a ⚠️ icon next to the task, with "circular dependency" shown on hover
Handling: automatically set the status to "cannot-complete" and prevent completion operations
Resolution: the dependency chain needs to be broken manually, removing or modifying the dependency relationships that cause the cycle

Custom Sorting and Grouping

Custom Sorting

Basic Sorting：sort by due、sort by priority, etc.
Custom Sort Functions：

not done
sort by function(task) {
  return task.description.length;
}

Nested Grouping

Multi-level Grouping: supports up to 3 levels of nested grouping
Example：

not done
happens in the next 7 days
group by folder
group by priority
sort by due

Group by Function

Function: Use JavaScript functions for custom grouping to implement complex grouping logic

Syntax：group by function <expression>

Example：

# 按任务描述长度分组
group by function task.description.length

# 按文件名后缀分组
group by function task.file.filename.split('.').pop()

# 按文件名大写形式分组
group by function task.file.filename.toUpperCase()

# 按文件所在文件夹分组
group by function task.file.folder.split('/').pop()

Nested task display (show tree)

Function: Display nested tasks in a tree structure, showing the hierarchical relationships of tasks

Syntax：show tree

Use cases: When you need to view the hierarchical structure of tasks, especially when dealing with complex projects that have subtasks

Example：

not done
path includes "Projects"
show tree
sort by due

Advanced Query Techniques

Complex Condition Combinations

not done
(due before tomorrow) OR (scheduled before tomorrow)
priority is high
path includes "Work"
sort by due
limit 5

Filter by Function

Function: Use JavaScript logic for extremely complex filtering, more powerful than ordinary filter instructions

Syntax：filter by function <expression>

Example：

filter by function task.description.length > 20
filter by function task.due && task.due.moment.isBefore(moment(), 'day')

Example：

not done
# 只显示描述中包含数字的任务
filter by function task.description.match(/\d+/) !== null

# 只显示描述长度超过20个字符的任务
filter by function task.description.length > 20

# 只显示截止日期在周末的任务 (Moment.js 语法)
filter by function task.due && [0, 6].includes(task.due.moment.day())

Advanced Guide to Script Filtering

Date handling must use Moment.js

Core Syntax：task.due.moment Returns a Moment object
Common Methods：
- task.due.moment.day() - Get the day of the week (0-6, Sunday is 0)
- task.due.moment.isBefore(moment(), 'day') - Check whether it is overdue
- task.due.moment.valueOf() - Get the timestamp (for sorting)

Example：

# 查询过期的任务
filter by function task.due && task.due.moment.isBefore(moment(), 'day')

# 查询本周内到期的任务
filter by function task.due && task.due.moment.isBetween(
  moment().startOf('week'), 
  moment().endOf('week')
)

Important Notes

task.description: Does not include metadata Emoji, only includes plain text description
Null Handling: Must handle task.due、task.priority and other cases that may be null
Performance Considerations: Complex filter functions will affect query speed; it is recommended to use them cautiously in large vaults

Grouping and Hiding Options Description

group by recurrence: Group by recurrence rule; some versions may have rendering issues

hide recurrence rule: Hide recurrence rules in query results; this option is still effective after Tasks 5.x

limit groups: Limit the number of tasks displayed per group to avoid groups that are too large

Example：

not done
group by folder
group by priority
limit groups 3  # 每个分组最多显示3个任务
sort by due

Mobile Notes

Mobile support for custom statuses is still poor, and icons may display abnormally
It is recommended to use standard status symbols on mobile for the best experience

Edge Case Warnings

Multiline Tasks：

The Tasks plugin has limited support for multiline list items
Metadata must be at the end of the first line; content on subsequent lines will not be parsed as metadata

List Indentation：

Tasks must be standard Markdown lists (using -, *, +)
Indentation must strictly follow Obsidian's hierarchy
Incorrect indentation may cause queries to miss subtasks

Example：

# 正确格式
- [ ] 任务描述  📅 2024-12-31
  - [ ] 子任务描述

# 错误格式（元数据不在第一行）
- [ ] 任务描述
  额外说明  📅 2024-12-31

Query Boolean Operation Rules

Important Rules：

Default Relationship: All query conditions use the AND relationship by default, meaning all conditions must be satisfied
OR Operation: Use uppercase OR for OR operations, such as(due before tomorrow) OR (scheduled before tomorrow)
Parentheses Grouping: Complex conditions need to be grouped with parentheses to ensure correct operator precedence
Negation Operation: The NOT prefix is not supported; the is not form must be used, such aspriority is not high
No Explicit AND: Explicitly writing AND is not supported (the default is the AND relationship)

Query Execution Order：

Global filtering (Settings) - Based on the Global Filter tag
Query Block - Basic filter conditions
Boolean logic (OR operations) - Complex condition combinations
Sort (sort by) - Result sorting
Group (group by) - Result grouping
Limit (limit) - Result quantity limit

Debugging and optimization

explain instruction

Function: Displays the parsing process of a query; an important tool for troubleshooting query issues
Use case: When query results are not as expected, add this instruction to see how the query is parsed
Example：

not done
due after today
explain

ignore global query instruction

Function: Ignores the global query conditions configured in the plugin settings
Use case: In complex queries, when you need to temporarily bypass the global query settings and use completely custom conditions
Example：
- Global setting is path includes "Tasks/", but you need to query tasks in other paths
- Global setting is not done, but you need to query completed tasks

Default query behavior

Default sorting：

Default order when no sort is specified: status > due > path
Priority: status > due date > file path

Global query behavior：

Global query conditions are automatically appended to all queries unless the ignore global query instruction is used
It is recommended to configure only general filter conditions in global settings (such as excluding archive folders)

Display control instructions

Display optimization：

short mode: Hides all metadata symbols at the end of the task line (date, recurrence, priority, etc.), showing only the text to keep the list clean
hide task count: Hides the task count statistics at the top of the query results
hide backlink: Hides the backlink to the source file
hide edit button: Hides the edit icon (pencil) at the end of the task
hide priority: Hides the priority symbol
hide created date: Hides the creation date
hide start date: Hides the start date
hide scheduled date: Hides the scheduled date
hide due date: Hides the due date
hide recurrence rule: Hides the recurrence rule

Example：

not done
due in the next 7 days
short mode
hide task count
hide edit button
hide priority
sort by due

Placeholders (supported in Tasks 5.0+)

Function: Use dynamic placeholders in queries to achieve intelligent queries based on the current context

Common placeholders：

{{query.file.path}}: The path of the current file
{{query.file.title}}: The title of the current file
{{query.file.folder}}: The folder where the current file is located

Example：

# 仅查询当前文件内的任务
path includes {{query.file.path}}
not done
sort by due

# 查询描述中包含当前文件名的任务
description includes {{query.file.title}}
not done
sort by due

Advanced query scenarios

Complex condition combinations

not done
(due before tomorrow) OR (scheduled before tomorrow)
priority equals high
path includes "Work"
sort by due
limit 5

Nested grouping

not done
happens in the next 7 days
group by folder
group by priority

Dynamic date calculation

not done
due after today
due before in 14 days
sort by due ascending

Task operations and interaction

Interaction behavior

Checkbox: Clicking the checkbox before a task will:
1. Update the task status ([ ] → [x])
2. Automatically add the completion date (✅ YYYY-MM-DD)
3. If there is a recurrence rule, generate a new task
4. If there are dependent tasks, update the dependency status
Edit: Click the task text to edit it in the source file
Context menu: Right-click a task to:
- Copy task
- Delete task
- Edit original content
- Go to source file

Task status transition rules

Initial status	Action	Resulting status	Additional behavior
[ ] Not started	Check	[x] Completed	Add completion date, handle recurrence
[/] In progress	Check	[x] Completed	Same as above
[-] Cancelled	Check	[x] Completed	Preserve cancelled status history
[x] Completed	Uncheck	[ ] Not started	Remove completion date

Dataview integration

Tasks as a Dataview data source

Method 1: Use TASK query (recommended)

const result = await dv.query(`
TASK FROM #tasks
WHERE !completed
SORT due ASC
`);
dv.taskList(result.value);

Recommended DataviewJS access method

// 推荐的DataviewJS访问方式
const tasks = dv.pages().file.tasks.filter(t => t.text.includes("📅") && !t.completed);
dv.taskList(tasks);

// 示例：只显示描述中包含数字的任务
const tasksWithNumbers = dv.pages().file.tasks.filter(t => 
  t.text.match(/\d+/) !== null && !t.completed
);
dv.taskList(tasksWithNumbers);

Method 2: Iterate over file.tasks (for custom logic)

// 遍历所有包含tasks标签的文件中的任务
for (let page of dv.pages('#tasks')) {
  for (let task of page.file.tasks) {
    // 访问任务属性
    // task.completed - 任务是否完成
    // task.due - 截止日期
    // task.text - 任务文本（包含标签）
    // task.section - 任务所在章节
    // task.position - 任务在文件中的位置
  }
}

Mixed query (Tasks + Dataview)

TABLE WITHOUT ID
  file.link AS "项目",
  choice(length(filter(file.tasks, (t) => !t.completed)) > 0, "✅", "⏳") AS "状态",
  dateformat(date(today) + dur("7 days"), "yyyy-MM-dd") AS "下周截止"
FROM "Projects"
WHERE contains(file.tasks.due, this.due)

Metadata mapping rules

Tasks field	Dataview equivalent field	Notes
📅 due	task.due	Must be correctly formatted to be parsed as a date
⏳ scheduled	task.scheduled	Same as above
➕ created	task.created	Same as above
🛫 start	task.start	Same as above
� priority	task.priority	High/medium/low map to numeric values
🔁 recurrence	task.recurring	Boolean value

Configuration options in detail

Global settings

Task completion time: Set the completion date format automatically added when completing a task
Recurrence rule settings: Configure the behavior of recurring tasks (which date to update, whether to preserve history, etc.)
Default priority: The default priority for new tasks
Date format: The format for displaying dates (does not affect the storage format)
Task status: Customize task status symbols and meanings
Default query sorting: The default order when no sorting is specified

Advanced configuration

Ignored folders: Specify folders not to scan
Ignored tags: Specify tags not to index
Status symbol mapping: Customize the mapping of status symbols to meanings

[
{"symbol": " ", "name": "todo"},
{"symbol": "/", "name": "in-progress"},
{"symbol": "x", "name": "done"},
{"symbol": "-", "name": "cancelled"}
]

Priority mapping: Customize the mapping of priority symbols to numeric values
Date inference rules: Configure how dates are inferred from task text

Custom task status system: The extended status system introduced in Tasks 5.0+

Configuration path: Obsidian settings → Plugins → Tasks → Statuses
Status symbol mapping example:

[
  {"symbol": " ", "name": "todo", "nextStatus": "in-progress"},
  {"symbol": "/", "name": "in-progress", "nextStatus": "done"},
  {"symbol": "x", "name": "done", "nextStatus": "todo"},
  {"symbol": "-", "name": "cancelled", "nextStatus": "todo"},
  {"symbol": "p", "name": "pending", "nextStatus": "in-progress"}
]

Workflow transition rules: You can configure the next default status for each status, supporting custom workflows
Query syntax:status is todo or status is not done

Performance and limitations

Strict performance guidelines

Index latency: After files are modified, the Tasks index update takes 1-3 seconds
Large Vault Optimization: According to official benchmarks, on standard hardware, path filtering is recommended when there are more than 2000 active tasks
- Performance Benchmarks (Intel i5/16GB RAM/SSD)：
  - 500 tasks: index time <0.5 seconds
  - 2000 tasks: index time ≈1.8 seconds
  - 5000+ tasks: using the exclude path parameter is recommended
Exclude Path Parameter: useexclude pathto reduce the indexing scope, based on string containment matching
- exclude path "Archived/" Exclude folders and subfolders containing Archived
- exclude path "Templates/" Exclude folders containing Templates
- exclude path "/Archive/" Stricter matching, to avoid false matches such as My Archive
- exclude path "Templates/" exclude path "Archive/" Exclude multiple paths at the same time
Performance Misconceptions：
- Tasks path filtering is based on string containment, not exact matching
- If your folder is called My Archive, it will also be exclude path "Archive" excluded
- For strict matching, it is recommended to use the exclude path "/Archive/" format
- Simple prefix matching is supported; support for complex glob patterns is limited
Performance Optimization for Large Vaults(more than 10,000 tasks)
- On-demand queries: avoid placing overly complex queries in notes that reside permanently in the sidebar
- Query strategy: place complex queries in dedicated notes that are opened only when needed
- Combined optimization: combineexclude pathandlimitinstructions to reduce the number of tasks in a single query
Avoid global queries: never use queries without filter conditions in a large vault
Query cache: complex query results are cached, but the cache is invalidated after the source file is modified

Hard Limits

Maximum query results: a single query is limited to returning 10,000 results
Nested grouping depth: supports up to 3 levels of nested grouping
Recurrence rule depth: by default, generates up to 50 recurring instances
- Limit adjustment: this limit can be adjusted by changing "Maximum number of recurring instances" in the plugin settings
- Performance impact: exceeding 100 may cause performance degradation, especially on mobile devices
- Best practice: set a reasonable value according to actual needs; for general projects, 50-100 instances are recommended
Query syntax limitations: regular expressions are not supported (unlike Dataview)
Time zone limitations: all dates are based on the system's local time zone; time zone conversion is not supported

Mobile Feature Limitations

iOS/Android interaction limitations：
- Tapping the task text may jump directly to the source file instead of edit mode
- Long-pressing a task displays the context menu, including options such as complete and edit
Auto-completion behavior：
- Mobile network latency may cause auto-completion actions to respond slowly
- Recurring task generation may execute in batches after network recovery
Performance Considerations：
- On mobile devices, it is recommended to limit the number of tasks for a single query (within 500)
- Reduce complex grouping and sorting operations to improve response speed
- Consider usingexclude pathExclude infrequently used folders
Mobile-Specific Limitations：
- Custom sorting/grouping functions are not supported
- Long-press a task instead of right-clicking to show the context menu
- Recurring task generation may be delayed until network recovery
- It is recommended to limit a single query to within 500

Best Practices and Pitfalls

Recommended Practices

File Organization: Store tasks in separate folders by project/context
Metadata Consistency: Consistently use Emoji or inline field syntax, avoid mixing
Query Optimization: First usepathNarrow the scope, then apply other filter conditions
Block ID Management: Add block IDs to key tasks to establish dependencies
History Retention: Regularly archive completed tasks to reduce the number of active tasks

Common Pitfalls

Incorrect Date Format: Non-ISO format dates (2024/12/31) will not be recognized
Missing Spaces: Missing two spaces between task text and metadata causes parsing failure
Conflicting Recurrence Rules: Multiple recurrence rules on the same task lead to unpredictable behavior
Dependency Cycles: Task A depends on Task B, and Task B depends on Task A, forming a deadlock
Moving Tasks: Moving a task to a new file breaks block ID dependencies
YAML Conflicts: Fields with the same name in YAML frontmatter override inline fields
Timezone Misunderstanding: When collaborating across timezones, local dates may cause inconsistencies

Real-World Scenario Examples

1. Daily To-Do List

not done
(due before today) OR (scheduled before today) OR (start before today)
priority is high
hide recurrence rule
sort by priority, due

2. Project Progress Tracking

path includes "Projects/Website"
not done
group by heading
group by priority
limit 20

3. Habit Tracker

is recurring
priority is low
scheduled after 7 days ago
group by recurrence
sort by scheduled

4. Dependent Task Management

depends on project-start
not done
sort by due

5. Weekly Review Template

Completed This Week

done
completed after last week
sort by completed

Incomplete Tasks

not done
due before next week
sort by due

New Tasks

created after last week
not done
sort by created

Troubleshooting Guide

Tasks not showing in query results?

Check whether the date format is strict ISO standard (YYYY-MM-DD)
Verify whether there are two spaces between the task text and metadata
Confirm whether the file is in the "ignored folders" configuration
Check whether the task is overridden by a field with the same name in YAML frontmatter

Recurring tasks not generating?

Verify whether the original task is completed
Check whether the recurrence rule syntax exactly matches the specification
Confirm whether timezone settings affect date calculations

Data Recovery Procedure

When query results are abnormal:
1. Close Obsidian
2. Delete .obsidian/plugins/obsidian-tasks/cache directory
3. Restart the app to trigger a full index rebuild

Version Migration Guide

Changes from 3.x to 4.x

Breaking Changes：
- Query syntax updated, some operators changed
- Recurrence rule engine refactored
- Performance optimizations led to indexing mechanism changes
Migration recommendations：
- Back up existing vaults
- Update query statements gradually
- Verify recurring task behavior

Changes from 4.x to 5.x

Extended status system: Introduced custom task statuses
Enhanced dependency mechanism: Added automatic status transitions
Performance parameter adjustments: Added exclude path parameter

Advanced customization features

Custom sorting functions (supported in Tasks 5.0+)

Basic example：

sort by function(task) {
  return task.description.length;
}

High-performance recommendations: Handle null cases to improve sorting performance

// 按截止日期排序，处理空值
return task.due ? task.due.moment.valueOf() : 0;

// 按优先级排序，处理空值
return task.priority ? task.priority : 999;

Custom renderer API

Used to modify task display format
Supports custom status icons
Extensible task property display

Custom renderer example

// 自定义渲染器配置示例
const customRenderer = (task, element) => {
  // 为高优先级任务添加红色边框和火焰图标
  if (task.priority === 'high') {
    element.style.borderColor = '#ff0000';
    element.style.borderWidth = '2px';
    element.style.borderStyle = 'solid';
    
    // 查找或创建优先级元素
    const priorityElement = element.querySelector('.task-priority');
    if (priorityElement) {
      priorityElement.innerHTML = '🔥';
      priorityElement.title = '高优先级';
    }
  }
  
  // 为接近截止日期的任务添加黄色背景
  if (task.due && task.due.diffNow().days <= 3) {
    element.style.backgroundColor = '#fff3cd';
  }
  
  // 为已完成任务添加绿色对勾
  if (task.status === 'done') {
    const statusElement = element.querySelector('.task-status');
    if (statusElement) {
      statusElement.innerHTML = '✅';
    }
  }
};

// 在插件设置中应用
// settings.customRenderer = customRenderer;

Reference resources

Official documentation: https://github.com/obsidian-tasks-group/obsidian-tasks
Query syntax details: https://publish.obsidian.md/tasks/Queries
Recurrence rule guide: https://publish.obsidian.md/tasks/Recurring+Tasks
Community forum: https://forum.obsidian.md/c/plugins/tasks/66
GitHub Issues: https://github.com/obsidian-tasks-group/obsidian-tasks/issues

Version compatibility

Minimum Obsidian version: 1.0.0
Recommended Obsidian version: 1.4.0+
Tasks plugin version requirement: 4.0.0+ (5.0.0+ recommended for full functionality)
Compatible Dataview version: Dataview 0.5.53+

Version feature correspondence：

Tasks 4.0+: Introduced the Status Type query system, refactored the recurrence rule engine
Tasks 5.0+: Extended status system, updated custom sorting function syntax, show tree feature

Important notes: The Tasks plugin is continuously updated, and new versions may introduce backward-incompatible changes. Before upgrading, please back up your vault and check the changelog. Some advanced features (such as custom status symbols and show tree) require the latest version for support.

About this skill

⚠️ Critical Data Safety Warning

Important Safety Notice

🚨 Last Resort: Reset Plugin Configuration

⚠️ Global Filter Trap

⚠️ Additional Data Safety Warning

Sync Conflicts

Version Control Conflicts

I. Basic Syntax

Basic Task Structure

Task Metadata Fields

Core Metadata Fields

Priority Markers (Official Standard)

Priority query syntax extension

Comparison queries

Detailed explanation of numeric mapping

No-priority queries

Date type mapping (official standard)

Difference between completion and done

Date format and time zone notes

Task IDs and Block References

Task ID (Official Standard)

Block reference (Obsidian standard feature)

Important Distinction

Detailed Mechanism of Task Dependencies

Dependency Query Syntax

Strict Format Requirements

YAML frontmatter priority

⚠️ The "read-only" trap of YAML Frontmatter

Space requirements

Recurring task rule engine

Recurrence syntax (official standard)

Complete recurrence rule syntax table (all officially supported patterns)

Recurring task lifecycle

Important warnings and limitations

Timezone edge cases

II. Standard queries

Query basic structure

Basic query commands

Filter commands

Path query instructions

root instruction

folder instruction

Date keywords

III. Advanced Features

Status Type Query System (Tasks 4.0+)

Custom Status Notes

⚠️ The 'forced symbol' trap in status transitions

Dependency Management

Task Dependency Syntax

Dependency Status

Dependency Queries

Circular Dependency Detection

Custom Sorting and Grouping

Custom Sorting

Nested Grouping

Group by Function

Nested task display (show tree)

Advanced Query Techniques

Complex Condition Combinations

Filter by Function

Advanced Guide to Script Filtering

Date handling must use Moment.js

Important Notes

Grouping and Hiding Options Description

Mobile Notes

Edge Case Warnings

Query Boolean Operation Rules

Debugging and optimization

explain instruction

ignore global query instruction

Default query behavior

Display control instructions

Placeholders (supported in Tasks 5.0+)

Advanced query scenarios

Complex condition combinations

Nested grouping

Dynamic date calculation

Task operations and interaction