org-tutorials/agenda-filters.org

   1 #+TITLE:      Agenda Filters and Limits
   2 #+AUTHOR:     Bastien Guerry
   3 #+EMAIL:      bzg AT gnu DOT org
   4 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
   5 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   6 #+LANGUAGE:   en
   7 #+PRIORITIES: A C B
   8 #+CATEGORY:   worg
   9 #+OrgVersion: 8.0
  10
  11 # This file is released by its authors and contributors under the GNU
  12 # Free Documentation license v1.3 or later, code examples are released
  13 # under the GNU General Public License v3 or later.
  14
  15 [[file:index.org][{Back to Worg's index}]]
  16
  17 * Introduction
  18
  19 This tutorial describes some useful agenda manipulations.
  20
  21 The central notions are /filters/ and /limits/.  Filters are a way to
  22 /hide/ some agenda entries (depending on tags, categories or regular
  23 expressions).  /Limits/ are a way to limit the list of agenda entries
  24 (depending on a number of tagged entries, a number of entries with =TODO=
  25 keywords, an effort value, or a number of entries.)
  26
  27 Filters only act on the /appearence/ of the agenda, limits act on the list
  28 of agenda entries itself.
  29
  30 * Agenda filters
  31 #+index: filtering, in agenda
  32
  33 ** Filtering by tags
  34 #+index: filtering, by tag
  35
  36 Here is a list of keybinding available in the agenda buffer:
  37
  38 - =/= :: Only show entries matching a tag.  This prompts for a tag to
  39      filter by, which you can choose by hitting a selection letter (if
  40      configured), or the first letter of the tag, or by hitting =TAB= and
  41      then expand a tag.
  42
  43 - =C-u /= :: Hide entries matching a tag.  You can successively call this
  44      command to hide several tags.
  45
  46 - =/ /= :: Reset tag filters: set tag filters to their default value, which
  47      is usually =nil=, unless a tag filter has been preset.
  48
  49 ** Filtering by category
  50 #+index: filtering, by category
  51
  52
  53 - =<= :: Only show agenda entries that are from the same category than the
  54      headline at point.  Hitting =<= again when a category filter is active
  55      will deactivate it.  This kind of filtering is /not/ cumulative, as
  56      headlines cannot have several categories.
  57
  58 - =C-u <= :: Hide agenda entries that are from the same category than the
  59      headline at point.
  60
  61 ** Filtering by top parent headline
  62 #+index: filtering, by top parent headline
  63
  64
  65 - =^= :: Only show siblings of the agenda entry at point.  This is useful
  66      when there are many agenda entries and you want to process siblings in
  67      priority.  Hitting =^= again when a top headline filter is active will
  68      deactivate it.  This kind of filtering is /not/ cumulative, as
  69      headlines cannot have several topmost parents.
  70
  71 ** Filtering by regular expressions
  72 #+index: filtering, by regular expressions
  73
  74 - ~=~ :: Prompt for a regular expression and only show agenda entries that
  75      match the regular expression.  You can successively filter by
  76      regexps.
  77
  78 - =C-u == :: Filter out entries that match a regexp.  You can successively
  79      filter out by regexps.
  80
  81 - =C-u C-u == :: Remove all regexps filters.
  82
  83 ** Combining and removing filters
  84 #+index: filters, combining
  85 #+index: filters, removing
  86
  87 You can filter by tags, then by regexps, than by category, then by topmost
  88 parent -- in *any* order.
  89
  90 To remove all filters from the current agenda view, hit =|=.
  91
  92 ** COMMENT TODO Pre-filtering
  93
  94 * Agenda limits
  95 #+index: limits, in agenda
  96 #+index: org-agenda-max-entries
  97 #+index: org-agenda-max-effort
  98 #+index: org-agenda-max-todos
  99 #+index: org-agenda-max-tags
 100
 101 Here is a list of options that you can set, either globally, or locally in
 102 your custom agenda:
 103
 104 - =org-agenda-max-entries= :: Limit the number of entries.
 105 - =org-agenda-max-effort= :: Limit the duration of accumulated efforts (as minutes).
 106 - =org-agenda-max-todos= :: Limit the number of entries with TODO keywords.
 107 - =org-agenda-max-tags= :: Limit the number of tagged entries.
 108
 109 When set to a positive integer, each option will exclude entries from other
 110 catogories: for example, =(setq org-agenda-max-effort 100)= will limit the
 111 agenda to 100 minutes of effort and exclude any entry that as no effort
 112 property.  If you want to include entries with no effort property, use a
 113 negative value for =org-agenda-max-effort=.
 114
 115 One useful setup is to use =org-agenda-max-entries= locally in a custom
 116 command.  For example, this custom command will display the next five
 117 entries with a =NEXT= TODO keyword.
 118
 119 #+BEGIN_SRC emacs-lisp
 120 (setq org-agenda-custom-commands
 121       '(("n" todo "NEXT"
 122          ((org-agenda-max-entries 5)))))
 123 #+END_SRC
 124
 125 Once you mark one of these five entry as =DONE=, rebuilding the agenda will
 126 again the next five entries again, including the first entry that was
 127 excluded so far.
 128
 129 You can also dynamically set temporary limits by pressing =~= (or =M-x
 130 org-agenda-limit-interactively RET=).  Those temporary limits are lost when
 131 rebuilding the agenda.
 132
 133 * Dimming blocked task
 134
 135 #+INDEX: dimming blocked tasks in agenda
 136 #+INDEX: blocked tasks, dimming in agenda
 137
 138 Blocked tasks are dimmed by default in the agenda.
 139
 140 You can turn this feature off with this in your =.emacs.el= file:
 141
 142 #+BEGIN_SRC emacs-lisp
 143 (setq org-agenda-dim-blocked-tasks nil)
 144 #+END_SRC
 145
 146 This will actually speed up the agenda generation (see [[file:../agenda-optimization.org][the Worg page on
 147 Agenda optimization]]).
 148
 149 Then, if you want to turn this feature on temporarily for the current
 150 agenda, just enter =M-x org-agenda-dim-blocked-tasks RET= interactively.
 151
 152
 153
 154
 155