Skip to main content

11.6.1 Storing searches

The first application of custom searches is the definition of keyboard shortcuts for frequently used searches, either creating an agenda buffer, or a sparse tree (the latter covering of course only the current buffer).

Custom commands are configured in the variable org-agenda-custom-commands. You can customize this variable, for example by pressing C from the agenda dispatcher (see Agenda Dispatcher). You can also directly set it with Emacs Lisp in the Emacs init file. The following example contains all valid agenda views:

(setq org-agenda-custom-commands
'(("x" agenda)
("y" agenda*)
("w" todo "WAITING")
("W" todo-tree "WAITING")
("u" tags "+boss-urgent")
("v" tags-todo "+boss-urgent")
("U" tags-tree "+boss-urgent")
("f" occur-tree "\\<FIXME\\>")
("h" . "HOME+Name tags searches") ;description for "h" prefix
("hl" tags "+home+Lisa")
("hp" tags "+home+Peter")
("hk" tags "+home+Kim")))

The initial string in each entry defines the keys you have to press after the dispatcher command in order to access the command. Usually this is just a single character, but if you have many similar commands, you can also define two-letter combinations where the first character is the same in several combinations and serves as a prefix key1. The second parameter is the search type, followed by the string or regular expression to be used for the matching. The example above will therefore define:


as a global search for agenda entries planned2 this week/day.


as the same search, but only for entries with an hour specification like β€˜[h]h:mm’—think of them as appointments.


as a global search for TODO entries with β€˜WAITING’ as the TODO keyword.


as the same search, but only in the current buffer and displaying the results as a sparse tree.


as a global tags search for headlines tagged β€˜boss’ but not β€˜urgent’.


The same search, but limiting it to headlines that are also TODO items.


as the same search, but only in the current buffer and displaying the result as a sparse tree.


to create a sparse tree (again, current buffer only) with all entries containing the word β€˜FIXME’.


as a prefix command for a β€˜HOME’ tags search where you have to press an additional key (l, p or k) to select a name (Lisa, Peter, or Kim) as additional tag to match.

Note that *-tree agenda views need to be called from an Org buffer as they operate on the current buffer only.

  1. You can provide a description for a prefix key by inserting a cons cell with the prefix and the description.↩
  2. Planned means here that these entries have some planning information attached to them, like a time-stamp, a scheduled or a deadline string. See org-agenda-entry-types on how to set what planning information is taken into account.↩