This is the official manual for the latest Org-mode release.
Org provides a special hook that can be used to narrow down the selection
made by these agenda views:
tags-tree. You may
specify a function that is used at each match to verify if the match should
indeed be part of the agenda view, and if not, how much should be skipped.
You can specify a global condition that will be applied to all agenda views,
this condition would be stored in the variable
org-agenda-skip-function-global. More commonly, such a definition is
applied only to specific custom searches, using
Let's say you want to produce a list of projects that contain a WAITING tag anywhere in the project tree. Let's further assume that you have marked all tree headings that define a project with the TODO keyword PROJECT. In this case you would run a TODO search for the keyword PROJECT, but skip the match unless there is a WAITING tag anywhere in the subtree belonging to the project line.
To achieve this, you must write a function that searches the subtree for
the tag. If the tag is found, the function must return
indicate that this match should not be skipped. If there is no such
tag, return the location of the end of the subtree, to indicate that
search should continue from there.
(defun my-skip-unless-waiting () "Skip trees that are not waiting" (let ((subtree-end (save-excursion (org-end-of-subtree t)))) (if (re-search-forward ":waiting:" subtree-end t) nil ; tag found, do not skip subtree-end))) ; tag not found, continue after end of subtree
Now you may use this function in an agenda custom command, for example like this:
(org-add-agenda-custom-command '("b" todo "PROJECT" ((org-agenda-skip-function 'my-skip-unless-waiting) (org-agenda-overriding-header "Projects waiting for something: "))))
Note that this also binds
org-agenda-overriding-header to get a
meaningful header in the agenda view.
A general way to create custom searches is to base them on a search for
entries with a certain level limit. If you want to study all entries with
your custom search function, simply do a search for
‘LEVEL>0’2, and then use
org-agenda-skip-function to select the entries
you really want to have.
You may also put a Lisp form into
particular, you may use the functions
org-agenda-skip-subtree-if in this form, for example:
(org-agenda-skip-entry-if 'scheduled 'deadline)
(org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))
(org-agenda-skip-entry-if 'todo 'done)
(org-agenda-skip-entry-if 'regexp "regular expression")
(org-agenda-skip-entry-if 'notregexp "regular expression")
(org-agenda-skip-subtree-if 'regexp "regular expression")
Therefore we could also have written the search for WAITING projects like this, even without defining a special function:
(org-add-agenda-custom-command '("b" todo "PROJECT" ((org-agenda-skip-function '(org-agenda-skip-subtree-if 'regexp ":waiting:")) (org-agenda-overriding-header "Projects waiting for something: "))))
agenda* view is the same than
agenda except that it only
considers appointments, i.e., scheduled and deadline items that have a
[h]h:mm in their time-stamps.
 Note that, when using
level number corresponds to order in the hierarchy, not to the number of