Next: Todo Filtered Items Mode Commands, Up: Todo Filtered Items Mode [Contents]

### 10.1 Filtering Items

Todo mode provides three ways to filter items: a general filter for items matching a user-entered regular expression, as with the search command; and two specific filters, one for diary-displayable items (i.e., those lacking `todo-nondiary-marker`) and one for top priority items (more on the latter below). The commands for each filter come in pairs, one for filtering just the current todo file and one for filtering a user-specified list of todo files. Thus, there are six item filtering commands:9

- `F x x` (`todo-filter-regexp-items`)
- `F x m` (`todo-filter-regexp-items-multifile`)
- `F y y` (`todo-filter-diary-items`)
- `F y m` (`todo-filter-diary-items-multifile`)
- `F t t` (`todo-filter-top-priorities`)
- `F t m` (`todo-filter-top-priorities-multifile`)

There are two ways to specify which files the multifile filtering commands apply to. If there are files you want to filter every time you use these commands, customize the option `todo-filter-files`. If you leave this option empty (the default), invoking a multifile filtering command pops up a buffer similar to the Customization buffer for `todo-filter-files`, in which you can select files to filter just for this invocation.

Diary and top priority items are by definition non-done todo items, but when filtering by regular expression, you can extend the scope of the command to done items by enabling the option `todo-filter-done-items`. Then `F x x` and `F x m` will gather both matching todo and matching done items (including done items from any archive files corresponding to the selected todo files) into the virtual category of filtered items.

There are several ways to specify how many items in each category count as top priorities and hence get filtered by `F t t` and `F t m`:

- The option `todo-top-priorities` specifies a single default number for all categories and all todo files; its default value is 1, which means just the highest priority item in every category is filtered, unless otherwise specified.
- The option `todo-top-priorities-overrides` lists file-wide overrides of `todo-top-priorities` as well as category-specific overrides. It is empty by default. However, using the Custom facility to set this option would be tedious and error-prone, so instead you should use the commands `F t s` and `C t s`. The former sets (i.e., overrides) the default number of top priorities for all categories in the current todo file, and the latter sets the number of top priorities for the current category. To exclude a category or file from filtering by `F t t` and `F t m`, set the number to ‘`0`’.
- You can invoke `F t t` and `F t m` with a numeric prefix argument, which specifies the number of top priorities in each category just for this invocation, overriding both `todo-top-priorities-overrides` and `todo-top-priorities`.

#### Footnotes

### (9)

The use of `F` in the key sequences of these commands naturally recalls “filter”, but is also consistent with the Todo mode mnemonic key binding convention, since the commands involve one or more whole files.

Next: Todo Filtered Items Mode Commands, Up: Todo Filtered Items Mode [Contents]