6.3 Tag searches

Once a system of tags has been set up, it can be used to collect related information into special lists.

C-c \

C-c / T

Create a sparse tree with all headlines matching a tags search. With a C-u prefix argument, ignore headlines that are not a TODO line.

C-c a m

Create a global list of tag matches from all agenda files. See Matching tags and properties.

C-c a M

Create a global list of tag matches from all agenda files, but check only TODO items and force checking subitems (see variable org-tags-match-list-sublevels).

A tags search string can use Boolean operators ‘&’ for AND and ‘|’ for OR. ‘&’ binds more strongly than ‘|’. Parenthesis are currently not implemented. A tag may also be preceded by ‘-’, to select against it, and ‘+’ is syntactic sugar for positive selection. The AND operator ‘&’ is optional when ‘+’ or ‘-’ is present. Examples:

‘+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:’.

You may also test for TODO keywords (see TODO extensions) and properties (see Properties and Columns) at the same time as matching tags. For a guide on how to match properties, see Property searches. To match a specific TODO keyword, include an expression like ‘+TODO="NEXT"’ as one of the terms in a tags search.

There is also the possibility to end the tags part of the match (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 the tag matches, but should be applied with consideration: For example, a positive selection on several TODO keywords can not 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 ‘!’. 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.

‘work/WAITING’

Same as the first example.

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

Any element of the tag/todo match can be a regular expression - in this case it must be enclosed in curly braces. For example, ‘work+{^boss.*}’ matches headlines that contain the tag ‘:work:’ and any tag starting with ‘boss’. You may also use a regular expression in ‘TODO={^W}’ which would match TODO keywords starting with the letter ‘W’.

You can also require a headline to be of a certain level or category, by writing instead of any TAG an expression like ‘LEVEL=3’ or ‘CATEGORY="work"’, respectively. For example, a search ‘+LEVEL=3+boss/-DONE’ lists all level three headlines that have the tag ‘boss’ and are not marked with the TODO keyword DONE.

Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing any other properties will slow down the search.