This is the official manual for the latest Org-mode release.
Org provides a special hook to further limit items in agenda views:
tags-tree. Specify a custom function that tests
inclusion of every matched item in the view. This function can also
skip as much as is needed.
For a global condition applicable to agenda views, use the
org-agenda-skip-function-global variable. Org uses a global condition
org-agenda-skip-function for custom searching.
This example defines a function for a custom view showing TODO items with WAITING status. Manually this is a multi step search process, but with a custom view, this can be automated as follows:
The custom function searches the subtree for the WAITING tag and returns
nil on match. Otherwise it gives the location from where the search
(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
To use this custom function in a custom agenda command:
(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 a more
meaningful string suitable for the agenda view.
Search for entries with a limit set on levels for the custom search. This is
a general appraoch to creating custom searches in Org. To include all
levels, use ‘LEVEL>0’2. Then to selectively pick the
matched entries, use
org-agenda-skip-function, which also accepts Lisp
forms, such as
org-agenda-skip-subtree-if. 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")
The following is an example of a search for ‘WAITING’ without the 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 as
agenda except that it only considers appointments, i.e.,
scheduled and deadline items that have a time specification ‘[h]h:mm’ in
 Note that, for
org-odd-levels-only, a level number corresponds to order in the
hierarchy, not to the number of stars.