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. 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:

• If the comparison value is a plain number, a numerical comparison is done, and the allowed operators are ‘<’, ‘=’, ‘>’, ‘<=’, ‘>=’, and ‘<>’. As a synonym for the equality operator ‘=’, there is also ‘==’; ‘!=’ and ‘/=’ are synonyms of the inequality operator ‘<>’.
• If the comparison value is enclosed in double-quotes, a string comparison is done, and the same operators are allowed.
• If the comparison value is enclosed in double-quotes and angular brackets (like ‘DEADLINE<​="<2008-12-24 18:30>"’), both values are assumed to be date/time specifications in the standard Org way, and the comparison is done accordingly. Valid values also include ‘"<now>"’ for now (including time), ‘"<today>"’, and ‘"<tomorrow>"’ for these days at 0:00 hours, i.e., without a time specification. You can also use strings like ‘"<+5d>"’ or ‘"<-2m>"’ with units ‘d’, ‘w’, ‘m’, and ‘y’ for day, week, month, and year, respectively.
• If the comparison value is enclosed in curly braces, a regexp match is performed, with ‘=’ meaning that the regexp matches the property value, and ‘<>’ meaning that it does not match.
• All operators may be optionally followed by an asterisk ‘*’, like in ‘<*’, ‘!=*’, etc. Such starred operators work like their regular, unstarred counterparts except that they match only headlines where the tested property is actually present. This is most useful for search terms that logically exclude results, like the inequality operator.

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.

Note that the test on the ‘EFFORT’ property uses operator ‘<*’, so that the search result will include only entries that actually have an ‘EFFORT’ property defined and with numerical value smaller than 2. With the regular ‘<’ operator, the search would handle entries without an ‘EFFORT’ property as having a zero effort and would include them in the result as well.

You can use all characters valid in property names when matching properties. However, you have to quote some characters in property names with backslashes when using them in search strings, namely all characters different from alphanumerics and underscores⁹⁵. For example, to search for all entries having a property ‘boss-prio’, ‘boss:prio’, or ‘boss\prio’, respectively, with value ‘C’, use search strings

boss\-prio="C"
boss\:prio="C"
boss\\prio="C"

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’.