Next: , Previous: Archiving, Up: Document structure

2.7 Sparse trees

An important feature of Org-mode is the ability to construct sparse trees for selected information in an outline tree. A sparse tree means that the entire document is folded as much as possible, but the selected information is made visible along with the headline structure above it1. Just try it out and you will see immediately how it works.

Org-mode contains several commands creating such trees. The most basic one is org-occur:

C-c /
Occur. Prompts for a regexp and shows a sparse tree with all matches. If the match is in a headline, the headline is made visible. If the match is in the body of an entry, headline and body are made visible. In order to provide minimal context, also the full hierarchy of headlines above the match is shown, as well as the headline following the match. Each match is also highlighted; the highlights disappear when the buffer is changes an editing command, or by pressing C-c C-c. When called with a C-u prefix argument, previous highlights are kept, so several calls to this command can be stacked.
For frequently used sparse trees of specific search strings, you can use the variable org-agenda-custom-commands to define fast keyboard access to specific sparse trees. These commands will then be accessible through the agenda dispatcher (see Agenda dispatcher). For example: 
     (setq org-agenda-custom-commands
           '(("f" occur-tree "FIXME")))

will define the key C-c a f as a shortcut for creating a sparse tree matching the string `FIXME'.

Other commands use sparse trees as well. For example C-c C-v creates a sparse TODO tree (see TODO basics).

To print a sparse tree, you can use the Emacs command ps-print-buffer-with-faces which does not print invisible parts of the document 2. Or you can use the command C-c C-e v to export only the visible part of the document and print the resulting file.

Footnotes

[1] See also the variables org-show-hierarchy-above, org-show-following-heading, and org-show-siblings for detailed control on how much context is shown around each match.

[2] This does not work under XEmacs, because XEmacs uses selective display for outlining, not text properties.