org: Storing searches
10.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-c a C’. You can also directly set it with Emacs
Lisp in ‘.emacs’. 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 ‘C-c a’ in order to access the command.
Usually this will be 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 key(1). 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:
‘C-c a x’
as a global search for agenda entries planned(2) this week/day.
‘C-c a y’
as a global search for agenda entries planned this week/day, but
only those with an hour specification like ‘[h]h:mm’—think of them
as appointments.
‘C-c a w’
as a global search for TODO entries with ‘WAITING’ as the TODO
keyword
‘C-c a W’
as the same search, but only in the current buffer and displaying
the results as a sparse tree
‘C-c a u’
as a global tags search for headlines marked ‘:boss:’ but not
‘:urgent:’
‘C-c a v’
as the same search as ‘C-c a u’, but limiting the search to
headlines that are also TODO items
‘C-c a U’
as the same search as ‘C-c a u’, but only in the current buffer and
displaying the result as a sparse tree
‘C-c a f’
to create a sparse tree (again: current buffer only) with all
entries containing the word ‘FIXME’
‘C-c a h’
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 the ‘*-tree’ agenda views need to be called from an Org
buffer as they operate on the current buffer only.
---------- Footnotes ----------
(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 will be taken into account.