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 interactively98. 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.
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.
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).
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 <.
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 =.
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).
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 ^.
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,
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.
Remove all filters in the current agenda view.
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
org-agenda-filter, i.e. press C-u C-u C-u /,
or by pressing RET in
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
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:
This prompts for the type of limit to apply and its value.
Custom agenda commands can preset a filter by binding one of
org-agenda-regexp-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