Skip to main content

2.5 Sparse Trees

An important feature of Org mode is the ability to construct sparse trees for selected information in an outline tree, so 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, all these commands can be accessed through a dispatcher:

C-c / (org-sparse-tree)​

This prompts for an extra key to select a sparse-tree creating command.

C-c / r or C-c / / (org-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 changed by an editing command, or by pressing C-c C-c2. When called with a C-u prefix argument, previous highlights are kept, so several calls to this command can be stacked.

M-g n or M-g M-n (next-error)​

Jump to the next sparse tree match in this buffer.

M-g p or M-g M-p (previous-error)​

Jump to the previous sparse tree match in this buffer.

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")))

defines the key f as a shortcut for creating a sparse tree matching the string ‘FIXME’.

The other sparse tree commands select headings based on TODO keywords, tags, or properties and are discussed later in this manual.

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. Or you can use the command C-c C-e C-v to export only the visible part of the document and print the resulting file.

  1. See also the variable org-show-context-detail to decide how much context is shown around each match.↩
  2. This depends on the option org-remove-highlights-with-change.↩