Previous: Sorting agenda items, Up: Presentation and sorting

10.4.4 Filtering/limiting agenda items

Agenda built-in or customized commands are statically defined. Agenda filters and limits provide two ways of dynamically narrowing down the list of agenda entries: filters and limits. Filters only act on the display of the items, while limits take effect before the list of agenda entries is built. Filters are more often used interactively, while limits are mostly useful when defined as local variables within custom agenda commands.

Filtering in the agenda

/     (org-agenda-filter-by-tag)
Filter the agenda view with respect to a tag and/or effort estimates. The difference between this and a custom agenda command is that filtering is very fast, so that you can switch quickly between different filters without having to recreate the agenda.1

You will be prompted for a tag selection letter; <SPC> will mean any tag at all. Pressing <TAB> at that prompt will offer use completion to select a tag (including any tags that do not have a selection character). The command then hides all entries that do not contain or inherit this tag. When called with prefix arg, remove the entries that do have the tag. A second / at the prompt will turn off the filter and unhide any hidden entries. Pressing + or - switches between filtering and excluding the next tag.

Org also supports automatic, context-aware tag filtering. If the variable org-agenda-auto-exclude-function is set to a user-defined function, that function can decide which tags should be excluded from the agenda automatically. Once this is set, the / command then accepts <RET> as a sub-option key and runs the auto exclusion logic. For example, let's say you use a Net tag to identify tasks which need network access, an Errand tag for errands in town, and a Call tag for making phone calls. You could auto-exclude these tags based on the availability of the Internet, and outside of business hours, with something like this:

          (defun org-my-auto-exclude-function (tag)
            (and (cond
                  ((string= tag "Net")
                   (/= 0 (call-process "/sbin/ping" nil nil nil
                                       "-c1" "-q" "-t1" "")))
                  ((or (string= tag "Errand") (string= tag "Call"))
                   (let ((hour (nth 2 (decode-time))))
                     (or (< hour 8) (> hour 21)))))
                 (concat "-" tag)))
          (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)

[ ] { }
in search view
add new search words ([ and ]) or new regular expressions ({ and }) to the query string. The opening bracket/brace will add a positive search term prefixed by ‘+’, indicating that this search term must occur/match in the entry. The closing bracket/brace will add a negative search term which must not occur/match in the entry for it to be selected.

<     (org-agenda-filter-by-category)
Filter the current agenda view with respect to the category of the item at point. Pressing < another time will remove this filter. When called with a prefix argument exclude the category of the item at point from the agenda.

You can add a filter preset in custom agenda commands through the option org-agenda-category-filter-preset. See Setting options.

^     (org-agenda-filter-by-top-headline)
Filter the current agenda view and only display the siblings and the parent headline of the one at point.

=     (org-agenda-filter-by-regexp)
Filter the agenda view by a regular expression: only show agenda entries matching the regular expression the user entered. When called with a prefix argument, it will filter out entries matching the regexp. With two universal prefix arguments, it will remove all the regexp filters, which can be accumulated.

You can add a filter preset in custom agenda commands through the option org-agenda-regexp-filter-preset. See Setting options.

_     (org-agenda-filter-by-effort)
Filter the agenda view with respect to effort estimates. You first need to set up allowed efforts globally, for example
          (setq org-global-properties
              '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))

You can then filter for an effort by first typing an operator, one of <, >, and =, and then the one-digit index of an effort estimate in your array of allowed values, where 0 means the 10th value. The filter will then restrict to entries with effort smaller-or-equal, equal, or larger-or-equal than the selected value. For application of the operator, entries without a defined effort will be treated according to the value of org-sort-agenda-noeffort-is-high.

When called with a prefix argument, it will remove entries matching the condition. With two universal prefix arguments, it will clear effort filters, which can be accumulated.

You can add a filter preset in custom agenda commands through the option org-agenda-effort-filter-preset. See Setting options.

|     (org-agenda-filter-remove-all)
Remove all filters in the current agenda view.
Setting limits for the agenda

Here is a list of options that you can set, either globally, or locally in your custom agenda views (see Custom agenda views).

Limit the number of entries.
Limit the duration of accumulated efforts (as minutes).
Limit the number of entries with TODO keywords.
Limit the number of tagged entries.

When set to a positive integer, each option will exclude entries from other categories: for example, (setq org-agenda-max-effort 100) will limit the agenda to 100 minutes of effort and exclude any entry that has no effort property. If you want to include entries with no effort property, use a negative value for org-agenda-max-effort.

One useful setup is to use org-agenda-max-entries locally in a custom command. For example, this custom command will display the next five entries with a NEXT TODO keyword.

     (setq org-agenda-custom-commands
           '(("n" todo "NEXT"
              ((org-agenda-max-entries 5)))))

Once you mark one of these five entry as DONE, rebuilding the agenda will again the next five entries again, including the first entry that was excluded so far.

You can also dynamically set temporary limits, which will be lost when rebuilding the agenda:

~     (org-agenda-limit-interactively)
This prompts for the type of limit to apply and its value.


[1] Custom commands can preset a filter by binding the variable org-agenda-tag-filter-preset as an option. This filter will then be applied to the view and persist as a basic filter through refreshes and more secondary filtering. The filter is a global property of the entire agenda view—in a block agenda, you should only set this in the global options section, not in the section of an individual block.