Previous: , Up: Presentation and Sorting   [Contents][Index]

10.4.4 Filtering/limiting agenda times

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

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. When called with prefix argument, remove the entries that do have the tag. A second / at the prompt turns off the filter and shows 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)
< (org-agenda-filter-by-category)

Filter the current agenda view with respect to the category of the item at point. Pressing < another time removes 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 filters out entries matching the regexp. Called in a regexp-filtered agenda view, remove the filter, unless there are two universal prefix arguments, in which case filters are cumulated.

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

When called with a prefix argument, it removes entries matching the condition. With two universal prefix arguments, it clears 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 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.



Custom commands can preset a filter by binding the variable org-agenda-tag-filter-preset as an option. This filter is then applied to the view and persists 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.

Previous: , Up: Presentation and Sorting   [Contents][Index]