11.4.4 Filtering/limiting agenda items

Agenda built-in or custom commands are statically defined. Agenda filters and limits allow to flexibly narrow down the list of agenda entries.

Filters only change the visibility of items, are very fast and are mostly used interactively⁹⁸. You can switch quickly between different filters without having to recreate the agenda. Limits on the other hand take effect before the agenda buffer is populated, so they are mostly useful when defined as local variables within custom agenda commands.

Filtering in the agenda

The general filtering command is org-agenda-filter, bound to /. Before we introduce it, we describe commands for individual filter types. All filtering commands handle prefix arguments in the same way: A single C-u prefix negates the filter, so it removes lines selected by the filter. A double prefix adds the new filter condition to the one(s) already in place, so filter elements are accumulated.

\ (org-agenda-filter-by-tag)

Filter the agenda view with respect to a tag. You are prompted for a tag selection letter; SPC means any tag at all. Pressing TAB at that prompt offers 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. Pressing + or - at the prompt switches between filtering for and against the next tag. To clear the filter, press \ twice (once to call the command again, and once at the prompt).

< (org-agenda-filter-by-category)

Filter by category of the line at point, and show only entries with this category. When called with a prefix argument, hide all entries with the category at point. To clear the filter, call this command again by pressing <.

= (org-agenda-filter-by-regexp)

Filter the agenda view by a regular expression: only show agenda entries matching the regular expression the user entered. To clear the filter, call the command again by pressing =.

_ (org-agenda-filter-by-effort)

Filter the agenda view with respect to effort estimates, so select tasks that take the right amount of time. You first need to set up a list of 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 then restricts 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 are treated according to the value of org-sort-agenda-noeffort-is-high. To clear the filter, press _ twice (once to call the command again, and once at the first prompt).

^ (org-agenda-filter-by-top-headline)

Filter the current agenda view and only display items that fall under the same top-level headline as the current entry. To clear the filter, call this command again by pressing ^.

/ (org-agenda-filter)

This is the unified interface to four of the five filter methods described above. At the prompt, specify different filter elements in a single string, with full completion support. For example,

+work-John+<0:10-/plot/

selects entries with category ‘work’ and effort estimates below 10 minutes, and deselects entries with tag ‘John’ or matching the regexp ‘plot’. You can leave ‘+’ out if that does not lead to ambiguities. The sequence of elements is arbitrary. The filter syntax assumes that there is no overlap between categories and tags. Otherwise, tags take priority. If you reply to the prompt with the empty string, all filtering is removed. If a filter is specified, it replaces all current filters. But if you call the command with a double prefix argument, or if you add an additional ‘+’ (e.g., ‘++work’) to the front of the string, the new filter elements are added to the active ones. A single prefix argument applies the entire filter in a negative sense.

| (org-agenda-filter-remove-all)

Remove all filters in the current agenda view.

Computed tag filtering

If the variable org-agenda-auto-exclude-function is set to a user-defined function, that function can select tags that should be used as a tag filter when requested. The function will be called with lower-case versions of all tags represented in the current view. The function should return ‘"-tag"’ if the filter should remove entries with that tag, ‘"+tag"’ if only entries with this tag should be kept, or ‘nil’ if that tag is irrelevant. 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 my-auto-exclude-fn (tag)
  (when (cond ((string= tag "net")
               (/= 0 (call-process "/sbin/ping" nil nil nil
                                   "-c1" "-q" "-t1" "mail.gnu.org")))
              ((member tag '("errand" "call"))
               (let ((hr (nth 2 (decode-time))))
                 (or (< hr 8) (> hr 21)))))
    (concat "-" tag)))

(setq org-agenda-auto-exclude-function #'my-auto-exclude-fn)

You can apply this self-adapting filter by using a triple prefix argument to org-agenda-filter, i.e. press C-u C-u C-u /, or by pressing RET in org-agenda-filter-by-tag.

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

org-agenda-max-entries

Limit the number of entries.

org-agenda-max-effort

Limit the duration of accumulated efforts (as minutes).

org-agenda-max-todos

Limit the number of entries with TODO keywords.

org-agenda-max-tags

Limit the number of tagged entries.

When set to a positive integer, each option excludes entries from other categories: for example, ‘(setq org-agenda-max-effort 100)’ limits 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 displays 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 are lost when rebuilding the agenda:

~ (org-agenda-limit-interactively)

This prompts for the type of limit to apply and its value.