This is the official manual for the latest Org-mode release.
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: fitlers and limits. Filters only act on the display of the items, while limits take effect before the list of agenda entries is built. Filter are more often used interactively, while limits are mostly useful when defined as local variables within custom agenda commands.
org-agenda-filter-by-tag
)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. If the first key you press is either + or -, the previous filter will be narrowed by requiring or forbidding the selected additional tag. Instead of pressing + or - after /, you can also immediately use the \ command.
In order to filter for effort estimates, you should 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. If the digits 0–9 are not used
as fast access keys to tags, you can also simply press the index digit
directly without an operator. In this case, < will be assumed. For
application of the operator, entries without a defined effort will be treated
according to the value of org-sort-agenda-noeffort-is-high
. To filter
for tasks without effort definition, press ? as the operator.
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" "mail.gnu.org"))) ((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-tag-refine
)org-agenda-filter-by-category
)<
another time will remove this filter. You can add
a filter preset through the option org-agenda-category-filter-preset
(see below.)
org-agenda-filter-by-top-headline
)org-agenda-filter-by-regexp
)org-agenda-category-filter-preset
(see below.)
org-agenda-filter-remove-all
)Here is a list of options that you can set, either globally, or locally in your custom agenda viewssee Custom agenda views.
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 as 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 limits2:
org-agenda-limit-interactively
)[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.
[2] Those temporary limits are lost when rebuilding the agenda.