- publishing free software manuals
The Org Mode 7 Reference Manual
by Carsten Dominik and others
Paperback (6"x9"), 282 pages
ISBN 9781906966089
RRP £9.95 ($14.95)

Sales of this book support the Org project! Get a printed copy>>>

10.3.3 Matching tags and properties

If headlines in the agenda files are marked with tags (see section 6 Tags), or have properties (see section 7 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.

C-c a m
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 section 6 Tags). If you often need a specific search, define a custom command for it (see section 10.2 The agenda dispatcher).
C-c a M
Like C-c a m, but only select headlines that are also TODO items in a not-DONE state and force checking subitems (see 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 section 6.3 Tag searches.

The commands available in the tags list are described in section 10.5 Commands in the agenda buffer.

Match syntax

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. For example, ‘work+{^boss.*}’ matches headlines that contain the tag ‘:work:’ and any tag starting with ‘boss’.

You may also test for properties (see section 7 Properties and columns) at the same time as matching tags. The properties may be real properties, or special properties that represent other metadata (see section 7.2 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 a search ‘+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’ will correspond 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 will depend 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.

Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing any other properties will slow down the search. However, once you have paid the price by accessing one property, testing additional properties is cheap again.

You can configure Org-mode to use property inheritance during a search, but beware that this can slow down searches considerably. See section 7.4 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 C-c a M, or equivalently start the TODO part after the slash with ‘!’. Using C-c a M or ‘/!’ will 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’.
ISBN 9781906966089The Org Mode 7 Reference ManualSee the print edition