org: Filtering/limiting agenda items
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: _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.
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. 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)’
Narrow the current agenda filter by an additional condition. When
called with prefix arg, remove the entries that _do_ have the tag,
or that do match the effort criterion. You can achieve the same
effect by pressing ‘+’ or ‘-’ as the first key after the ‘/’
command.
‘[ ] { }’
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.
You can add a filter preset through the option
‘org-agenda-category-filter-preset’ (see below.)
‘^ (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 through the option
‘org-agenda-category-filter-preset’ (see below.)
‘| (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
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 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 limits(2):
‘~ (org-agenda-limit-interactively)’
This prompts for the type of limit to apply and its value.
---------- Footnotes ----------
(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.
Info Catalog
org: Sorting agenda items
org: Presentation and sorting