Sparse trees and the match syntax

A sparse tree folds the buffer so that only the entries you are looking for stay visible, together with the headlines above them (their "context"). The matches are highlighted and collected in the window's location list, so you can jump from one to the next. Nothing in the file changes: a sparse tree is only a way of looking at it.

This file has two halves:

• the Playground, a small task list (an office move, a household, side projects) that every exercise searches, and
• one heading per kind of sparse tree and per part of the match syntax, each with examples, exercises (Try:) and the exact result (Expect:).

Working through it:

• The file starts folded (#+STARTUP: overview). Put the cursor on a heading and press <Tab> to open it; <S-Tab> cycles the whole buffer.
• <prefix> means <leader>o (the default prefix), so <prefix>/ is <leader>o/. With examples/minimal_init.lua the leader is <Space>.
• Press g? at any time to list every keymap of the buffer.
• Sparse trees don't edit anything, but if you do change the Playground, u undoes and git checkout examples/10-sparse-trees.org restores it. The expected results below assume the Playground is unchanged.
• Coming from Emacs? C-c / and C-c \ work too (:h org-emacs-keys).

Start Neovim from the root of the repository with the bundled config:

nvim -u examples/minimal_init.lua examples/10-sparse-trees.org

examples/minimal_init.lua loads org.nvim from this checkout, sets <Space> as the leader, points the agenda at examples/*.org and sends captures to a scratch directory. Sparse trees only look at the current buffer, so none of that matters here except the leader key.

Every sparse tree prints a message like 4 matches for +urgent. That number is the easiest thing to check, so each Expect: gives it.

Today is Mon 2026-09-28 in these examples. Only the deadline tree (d) and the relative dates (<today>, <+1w>) depend on the real date; their Expect: lines say so.

This is the data the exercises search. Open it once with <Tab> (and <Tab> again for everything) to see what is there. Notice:

• the TODO keywords (#+TODO: TODO NEXT WAITING | DONE CANCELLED),
• the tags, some of them inherited from a parent headline,
• the Effort, COST and ASSIGNEE properties,
• the CATEGORY of each group, and
• the SCHEDULED / DEADLINE / CLOSED lines and plain timestamps.

All the level-3 headlines of this file are here, so LEVEL=3 finds exactly the tasks of the Playground.

<prefix>/ opens a small menu; each key builds a different sparse tree. The simplest one is t: every headline with a TODO keyword that is not done (TODO, NEXT and WAITING here; DONE and CANCELLED are done states because they come after the | in #+TODO:).

What happens:

1. the whole buffer is folded to its top-level headlines (OVERVIEW),
2. each matching headline is shown with all its ancestors,
3. the matching headlines are highlighted (the Search colour), and
4. the location list of the window is filled with the matches, and the cursor goes to the first one.

Try: press <prefix>/ then t.

Expect: the message 11 matches for TODO entries. Under "Playground" you see the three groups and, under them, these headlines highlighted:

• Office move: Sign the new lease, Book the movers, Quote from the cleaning company, Pack the archive room
• Home: Fix the leaking tap, Paint the fence, Buy groceries, Call the plumber back
• Side projects: Write a blog post…, Submit the conference talk, Library book reservation

"Choose the new office" (DONE), "Repaint the garage" (CANCELLED), "Team meeting about the move" and "Idea: a garden planner app" (no keyword) are hidden. The other top-level headings of this file stay folded.

T asks for one or more keywords, with completion on the keywords of the buffer. Separate several keywords with | (or spaces). Done keywords are allowed here, unlike with t.

NEXT

2 matches: Book the movers, Call the plumber back

NEXT|WAITING

4 matches: the two above, Quote from the cleaning company, Library book reservation

DONE CANCELLED

3 matches: Choose the new office, Repaint the garage, Renew the car insurance

Try: <prefix>/ T, type NEXT|WAITING and press <CR>.

Expect: 4 matches for NEXT|WAITING: Book the movers, Quote from the cleaning company, Call the plumber back and Library book reservation.

Try: <prefix>/ T and type DONE.

Expect: 2 matches for DONE: Choose the new office and Renew the car insurance. The keyword is compared exactly: done finds nothing.

/ (or r) asks for a regular expression and highlights every line that matches, anywhere in the buffer: headlines, body text, drawers and these explanations too. Each match shows the lines of its entry and the headlines above it. Only the matching part of the line is highlighted.

In the <prefix>/ menu the regexp is a Vim regexp (:h pattern), and it is case-sensitive: add \c to ignore case. (Emacs uses an Emacs regexp and ignores case; see Differences from Emacs.)

Try: <prefix>/ /, type [i]nvoice and press <CR>.

Expect: 2 matches for /[i]nvoice/. The body lines of "Book the movers" and "Call the plumber back" are visible under their headlines, with the word highlighted. The capitalised word in the body of "Sign the new lease" is not a match, because the pattern is case-sensitive.

Try: the same with \c[i]nvoice.

Expect: 3 matches for /\c[i]nvoice/: the two lines above plus the body line of "Sign the new lease".

Try: <prefix>/ r and type SCHEDULED: <2026-1[0].

Expect: 3 matches: the SCHEDULED lines of Pack the archive room, Paint the fence and Library book reservation. Press ]l to walk through them; :lopen lists the three lines.

m asks for a match string (a tags / property / TODO query, the same syntax as the agenda's m view and clock tables) and shows every headline that it selects. M does the same but keeps only open TODO entries. <C-c>\ skips the menu and asks for the match directly (Emacs org-match-sparse-tree). To keep only open TODO entries there, end the match with /! (see the TODO part).

Headlines are matched, not lines: the whole headline is highlighted.

Try: <prefix>/ m, type +urgent and press <CR>.

Expect: 4 matches for +urgent: Sign the new lease, Fix the leaking tap, Call the plumber back and Submit the conference talk.

Try: <C-c>\ and type +work, then <C-c>\ again with +work/!.

Expect: first 7 matches for +work (Office move and every task under it, because tags are inherited), then 4 matches: Sign the new lease, Book the movers, Quote from the cleaning company and Pack the archive room. The DONE task and the meeting (no keyword) are left out.

The next sections go through the match syntax piece by piece. Use <C-c>\ (or <prefix>/ m) for every example.

A match string is a list of terms. For tags:

work

tagged work (the + is optional)

+work

tagged work

-work

not tagged work

+a+b

tagged a AND b

a:b and a&b

the same: : and & also mean AND

a|b

tagged a OR b

{regexp}

a tag matching an (Emacs) regexp

Rules worth remembering:

• AND binds tighter than OR: a+b|c is "(a and b) or c". There are no parentheses.
• Tags are inherited: a child has the tags of its parents (and of #+FILETAGS:). tags_exclude_from_inheritance and use_tag_inheritance change that.
• Tag names are compared exactly: Work does not find work. Regexps in {...} ignore case.
• A term cannot contain spaces. Text that does not start a new term ends the match silently, as in Emacs: work -urgent is the same as work.

Everything after the last / is matched against the TODO keyword.

/NEXT

keyword is NEXT

/NEXT|WAITING

NEXT or WAITING

/-DONE

keyword is not DONE (entries without a keyword match too)

/!

only open TODO entries (a not-done keyword)

/!-WAITING

open TODO entries, except WAITING

/{^W}

a keyword matching an Emacs regexp

TAGS/TODO-PART

both parts must match

Examples (the number is the match count):

/NEXT

2: Book the movers, Call the plumber back

/NEXT|WAITING

4: the two above, Quote…, Library book reservation

/DONE|CANCELLED

3: Choose…, Repaint…, Renew…

/!

11: the same as <prefix>/ t

/!-WAITING

9: the 11 open entries minus the 2 WAITING ones

/{^W}

2: Quote…, Library book reservation

+home/!

4: Fix…, Paint…, Buy groceries, Call…

+work/-DONE

6: the Office move group, minus Choose the new office

+urgent/TODO

3: Sign…, Fix…, Submit the conference talk

-home/!

7: the open entries outside Home

Try: <C-c>\ with +home/!.

Expect: 4 matches for +home/!: Fix the leaking tap, Paint the fence, Buy groceries and Call the plumber back. The DONE and CANCELLED tasks and the Home headline itself (no keyword) are not shown.

Try: <C-c>\ with +work/-DONE.

Expect: 6 matches: Office move, Sign the new lease, Book the movers, Quote from the cleaning company, Pack the archive room and Team meeting about the move. -DONE keeps headlines without any keyword; use /! when you only want open tasks.

A term can also compare a property: NAME OPERATOR VALUE.

Operators: = (or ==), <> (or != or /=), <, <=, >, >=. The value decides the kind of comparison:

• "text" in double quotes: a string comparison,
• a number (100, 2.5): a numeric comparison,
• {regexp}: an Emacs regexp, ignoring case (<> means "does not match"),
• "[2026-10-01 Thu]", "<today>" …: a date comparison (next section).

A missing property counts as the empty string "" in string comparisons and as 0 in numeric ones. Add * after the operator (<*, >=*, <>*, …) to match only entries that have the property.

Properties are not inherited in matches unless use_property_inheritance says so (it is false by default). CATEGORY is special: it always comes from the nearest :CATEGORY: above, or from #+CATEGORY:.

Put a date in double quotes, inside angle or square brackets, and the property is compared as a date. Works with SCHEDULED, DEADLINE, CLOSED, TIMESTAMP (the first active timestamp of the entry), TIMESTAMP_IA (the first inactive one) and any property holding a timestamp. An entry without the date never matches.

Angle brackets work as well as square ones (the Emacs manual uses angle brackets, like "<today>" below). The examples use square brackets: written in this file, an angle-bracket date would itself be an active timestamp of the explanation headings, and date searches would find them.

p is a shortcut for a single property: type NAME=value and it builds the match NAME"value"= for you (quotes are added when missing).

Try: <prefix>/ p and type ASSIGNEE=Bob.

Expect: 2 matches for ASSIGNEE"Bob"=: Book the movers and Pack the archive room.

Try: <prefix>/ p and type COST=450.

Expect: 1 match: Book the movers. (The comparison is a string one, so COST=450.0 finds nothing.)

d shows the open entries whose deadline is past or inside its warning period: deadline_warning_days (14 by default) before the date, or the entry's own -Nd cookie (the -40d in the DEADLINE of "Submit the conference talk" warns 40 days ahead). Done entries are never shown.

Try: <prefix>/ d.

Expect: on Mon 2026-09-28, 3 matches for deadlines:

• Sign the new lease (due in 4 days),
• Fix the leaking tap (3 days overdue),
• Submit the conference talk (due in 32 days, but the -40d cookie warns 40 days ahead).

Not shown: Write a blog post (Nov 20 is 53 days away), Choose the new office and Renew the car insurance (done). On a later date more entries fall inside their warning period.

b, a and D open the calendar to pick a date (D asks twice: from, to). In the calendar, h l j k move by day / week, < > by month, . goes to today, i lets you type a date (like 2026-10-01, +3d or fri), and <CR> selects.

An entry matches when its SCHEDULED, DEADLINE or one of its active timestamps is:

• b: strictly before the date,
• a: strictly after the date,
• D: between the two dates, both included.

CLOSED dates and inactive timestamps (like the one under the Idea) are not used.

Try: <prefix>/ b; in the calendar press i, type 2026-10-01 and press <CR> (the typed date is taken at once).

Expect: 6 matches for before 2026-10-01: Book the movers (Sep 29), Choose the new office (deadline Sep 20), Team meeting about the move (Sep 30), Fix the leaking tap (Sep 25), Buy groceries (Sep 28) and Renew the car insurance (deadline Sep 30).

Try: <prefix>/ a, then i, 2026-10-15, <CR>.

Expect: 3 matches for after 2026-10-15: Paint the fence (Oct 17), Write a blog post (Nov 20) and Submit the conference talk (Oct 30).

Try: <prefix>/ D, then i, 2026-10-01, <CR> (the first calendar) and i, 2026-10-12, <CR> (the second one).

Expect: 3 matches for between 2026-10-01 and 2026-10-12: Sign the new lease (Oct 2), Pack the archive room (Oct 12, the last day is included) and Library book reservation (Oct 5).

work -urgent

same as work: the space ends the match. Write work-urgent.

Work

0 matches: tags are compared exactly. Write work (or {^work$}, which ignores case).

(a|b)+c

parentheses are not part of the syntax. Write a+c|b+c.

COST<100

entries without a COST match too (a missing number is 0). Write COST<*100.

Effort<"1:00"

entries without an Effort match too ("" < "1:00"). Write Effort<*"1:00".

Effort<1:30

read as Effort<1 AND a tag named 30: 0 matches. Write Effort<*"1:30".

ASSIGNEE=Bob

without quotes it is not a comparison: a search for the tag ASSIGNEE that stops at =, so 0 matches. Write ASSIGNEE"Bob"=.

[i]nvoice in the / menu

a case-sensitive Vim regexp. Write \c[i]nvoice to ignore case.

Try: <C-c>\ with Effort<*"1:00".

Expect: 3 matches: Book the movers ("0:30"), Quote from the cleaning company ("0:15") and Fix the leaking tap ("0:45").

• In the <prefix>/ menu, / and r take a Vim regexp and are case-sensitive (Emacs: an Emacs regexp, ignoring case). \c makes it ignore case. Links with ::/regexp/ and occur_tree commands take an Emacs regexp.
• c in the menu clears the highlights. In Emacs c cycles the kind of date used by b, a and D (scheduled/deadline, all timestamps, only deadlines, …). Here b, a and D always look at SCHEDULED, DEADLINE and the active timestamps of each entry, and match whole headlines.
• p asks for NAME=value in one prompt (Emacs asks for the property, then the value).

• :h org-sparse-tree — the menu and <C-c>\
• :h org-match-syntax — the whole match syntax
• :h org-tag-groups — group tags in matches
• :h org-agenda-custom-commands — tags_tree, todo_tree, occur_tree
• :h org-hidden-lines — how the folds of a sparse tree are made
• :h org-read-date — what you can type in the calendar with i
• 05-tags.org and 06-properties-columns.org: tags and properties themselves
• 09-agenda.org: the same match syntax in the agenda