11.3.3 Matching tags and properties

If headlines in the agenda files are marked with tags (see Tags), or have properties (see Properties and Columns), you can select headlines based on this metadata and collect them into an agenda buffer. The match syntax described here also applies when creating sparse trees with C-c / m.

M-x org-agenda m (org-tags-view)

Produce a list of all headlines that match a given set of tags. The command prompts for a selection criterion, which is a boolean logic expression with tags, like ‘+work+urgent-withboss’ or ‘work|home’ (see Tags). If you often need a specific search, define a custom command for it (see The Agenda Dispatcher).

M-x org-agenda M (org-tags-view)

Like m, but only select headlines that are also TODO items and force checking subitems (see the variable org-tags-match-list-sublevels). To exclude scheduled/deadline items, see the variable org-agenda-tags-todo-honor-ignore-options. Matching specific TODO keywords together with a tags match is also possible, see Tag Searches.

The commands available in the tags list are described in Commands in the Agenda Buffer.

A search string can use Boolean operators ‘&’ for AND and ‘|’ for OR. ‘&’ binds more strongly than ‘|’. Parentheses are currently not implemented. Each element in the search is either a tag, a regular expression matching tags, or an expression like ‘PROPERTY OPERATOR VALUE’ with a comparison operator, accessing a property value. Each element may be preceded by ‘-’ to select against it, and ‘+’ is syntactic sugar for positive selection. The AND operator ‘&’ is optional when ‘+’ or ‘-’ is present. Here are some examples, using only tags.

+work-boss

Select headlines tagged ‘work’, but discard those also tagged ‘boss’.

work|laptop

Selects lines tagged ‘work’ or ‘laptop’.

work|laptop+night

Like before, but require the ‘laptop’ lines to be tagged also ‘night’.

Instead of a tag, you may also specify a regular expression enclosed in curly braces (see Regular Expressions). For example, ‘work+{^boss.*}’ matches headlines that contain the tag ‘:work:’ and any tag starting with ‘boss’.

Group tags (see Tag Hierarchy) are expanded as regular expressions. E.g., if ‘work’ is a group tag for the group ‘:work:lab:conf:’, then searching for ‘work’ also searches for ‘{\(?:work\|lab\|conf\)}’ and searching for ‘-work’ searches for all headlines but those with one of the tags in the group (i.e., ‘-{\(?:work\|lab\|conf\)}’).

You may also test for properties (see Properties and Columns) at the same time as matching tags. The properties may be real properties, or special properties that represent other metadata (see Special Properties). For example, the property ‘TODO’ represents the TODO keyword of the entry. Or, the property ‘LEVEL’ represents the level of an entry. So searching ‘+LEVEL=3+boss-TODO​="DONE"’ lists all level three headlines that have the tag ‘boss’ and are not marked with the TODO keyword ‘DONE’. In buffers with org-odd-levels-only set, ‘LEVEL’ does not count the number of stars, but ‘LEVEL=2’ corresponds to 3 stars etc.

Here are more examples:

work+TODO​="WAITING"

Select ‘work’-tagged TODO lines with the specific TODO keyword ‘WAITING’.

work+TODO​="WAITING"|home+TODO​="WAITING"

Waiting tasks both at work and at home.

When matching properties, a number of different operators can be used to test the value of a property. Here is a complex example:

+work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2
         +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>"

The type of comparison depends on how the comparison value is written:

So the search string in the example finds entries tagged ‘work’ but not ‘boss’, which also have a priority value ‘A’, a ‘Coffee’ property with the value ‘unlimited’, an ‘EFFORT’ property that is numerically smaller than 2, a ‘With’ property that is matched by the regular expression ‘Sarah\|Denny’, and that are scheduled on or after October 11, 2008.

You can configure Org mode to use property inheritance during a search, but beware that this can slow down searches considerably. See Property Inheritance, for details.

For backward compatibility, and also for typing speed, there is also a different way to test TODO states in a search. For this, terminate the tags/property part of the search string (which may include several terms connected with ‘|’) with a ‘/’ and then specify a Boolean expression just for TODO keywords. The syntax is then similar to that for tags, but should be applied with care: for example, a positive selection on several TODO keywords cannot meaningfully be combined with boolean AND. However, negative selection combined with AND can be meaningful. To make sure that only lines are checked that actually have any TODO keyword (resulting in a speed-up), use M-x org-agenda M, or equivalently start the TODO part after the slash with ‘!’. Using M-x org-agenda M or ‘/!’ does not match TODO keywords in a DONE state. Examples:

work/WAITING

Same as ‘work+TODO​="WAITING"’.

work/!-WAITING-NEXT

Select ‘work’-tagged TODO lines that are neither ‘WAITING’ nor ‘NEXT’.

work/!+WAITING|+NEXT

Select ‘work’-tagged TODO lines that are either ‘WAITING’ or ‘NEXT’.