org-tutorials/org-custom-agenda-commands.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   5 #+TITLE:      Custom Agenda Commands
   6 #+AUTHOR:     Matt Lundin
   7 #+EMAIL:      mdl at imapmail dot org
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 [[file:index.org][{Back to Worg's index}]]
  13
  14 * Introduction
  15   :PROPERTIES:
  16   :ID:       846f8b04-3012-48c9-bab1-3a618099d977
  17   :END:
  18
  19 Org-mode's built-in agenda commands are powerful tools for searching
  20 your notes and for gathering, sorting, filtering, and displaying your
  21 tasks. As you become familiar with the power of the agenda commands,
  22 you may want to:
  23
  24 - create shortcuts for frequent agenda searches (e.g., a search for
  25   all TODOs with the tag "@computer").
  26 - combine different different searches into a single [[http://orgmode.org/manual/Block-agenda.html#Block-agenda][block agenda]].
  27   (e.g., a daily agenda plus all TODO items with the tag "@work" and
  28   the tag "@computer").
  29 - change the query and display options for specific agenda searches
  30   (sorting, appearance, files used, etc.).
  31 - set up automatic export of custom agenda views to a variety of
  32   formats (html, ps, txt).
  33 - call user-defined functions from the [[http://orgmode.org/manual/Agenda-dispatcher.html#Agenda-dispatcher][agenda dispatcher]].
  34
  35 All of these things can be accomplished with the variable
  36 org-agenda-custom-commands.
  37
  38 * How to create custom agenda commands
  39
  40 The [[http://orgmode.org/manual/index.html][org-mode manual]] provides a [[http://orgmode.org/manual/Custom-agenda-views.html#Custom-agenda-views][comprehensive explanation]] of custom
  41 agenda commands. This tutorial is meant to supplement the manual by
  42 exploring some of the uses and benefits of such customization.
  43
  44 If you have not previously created a custom agenda command, the
  45 easiest way to get started is to type:
  46
  47 : M-x customize-variable RET org-agenda-custom-commands
  48
  49 The customization buffer for the variable provides a nice interface
  50 for setting custom commands as well as a full explanation of the
  51 different components of the setting.
  52
  53 As the documentation explains, the configuration for each custom
  54 command is a list consisting of the following:
  55
  56 - 1) Key :: The shortcut for invoking the command in the agenda
  57             dispatcher ("h", "J", etc.).
  58 - 2) Description (optional) :: The description of the command that
  59                     will be displayed in the agenda dispatcher
  60                     (optional).
  61 - 3) Type of search :: The desired agenda display/search. The options
  62      include agenda, todo, search, tags, alltodo, tags-todo,
  63      todo-tree, tags-tree, occur-tree, or a user-defined function.
  64 - 4) Search term :: Depending on the type of search, this will be a
  65                     TODO keyword, a tag (or property), a word, or a
  66                     regular expression.
  67 - 5) Settings (optional) :: How the agenda command should search and
  68      display information. These are local settings, active only for
  69      the command in which they are set.
  70 - 6) Export files (optional) :: If you want the agenda view to be
  71      automatically exported when you type C-c a e, then you can
  72      include the path to the exported file here. The file extension
  73      will determine the export format.
  74
  75 ** Sample customization
  76
  77 Here is a sample custom agenda command as one might set it in an
  78 .emacs file:
  79
  80 #+BEGIN_SRC emacs-lisp
  81 (setq org-agenda-custom-commands
  82       '(("c" "Desk Work" tags-todo "computer" ;; (1) (2) (3) (4)
  83          ((org-agenda-files '("~/org/widgets.org" "~/org/clients.org")) ;; (5)
  84           (org-agenda-sorting-strategy '(priority-up effort-down))) ;; (5) cont.
  85          ("~/computer.html")) ;; (6)
  86         ;; ...other commands here
  87         ))
  88 #+END_SRC
  89
  90 The first line in this custom command contains:
  91
  92 1. the key to trigger the search ("c")
  93 2. a description of the search for the agenda dispatcher ("Desk Work")
  94 3. the type of search (todo items matching a tag)
  95 4. the tag to search for ("computer")
  96
  97 The next two lines (5) set local options for this agenda command only.
  98 Any options you set here will not interfere with your global agenda
  99 settings. In this particular command, the files widgets.org and
 100 clients.org will be searched and the agenda display will sort the
 101 todos first by priority (highest priority last), then by estimated
 102 effort (highest effort first)---regardless or your global
 103 org-agenda-sorting-strategy.
 104
 105 The last line (6) specifies that this agenda view should be exported
 106 as HTML to "~/computer.html" when the agenda export function is called
 107 (C-c a e).
 108
 109 And here is what the setting above looks like in an emacs
 110 customization buffer:
 111
 112 [[file:../images/mdl/org-custom-agenda-commands-1.png]]
 113
 114 Of course, you need not include all of these components in every
 115 custom command. A more minimalistic set of instructions might look
 116 like this:
 117
 118 #+BEGIN_SRC emacs-lisp
 119 (setq org-agenda-custom-commands
 120       '(("w" todo "STARTED") ;; (1) (3) (4)
 121         ;; ...other commands here
 122         ))
 123 #+END_SRC
 124
 125 This will produce a list of all tasks with the todo keyword
 126 STARTED.[1]
 127
 128 [1] If you omit a description the agenda dispatcher will simply show
 129 the search type and search string in place of a description.
 130
 131 In addition to agenda views, custom agenda commands can also be used
 132 to store commonly used searches, such as sparse trees and occur trees.
 133 See the [[http://orgmode.org/manual/Sparse-trees.html#Sparse-trees][manual's section on sparse trees]] for further information.
 134
 135 As the examples above illustrate, agenda commands can range from
 136 simple stored searches to elaborate agenda views that diverge
 137 substantially from your normal agenda settings (different agenda
 138 files, different sorting strategies, different display options, etc.).
 139
 140 Now, let's look at a few usage scenarios.
 141
 142 * A use scenario: block agenda views
 143
 144 Perhaps the most common use of custom commands is to save the results
 145 of frequent agenda searches and (optionally) to combine multiple
 146 searches together in a single view.
 147
 148 Let's imagine you've just settled in at your office desk in the
 149 morning, ready for a good day's labor. You want to review your work
 150 before you get started. As part of your typical routine, you'd like to
 151 see:
 152
 153 1. your scheduled tasks and upcoming deadlines
 154 2. any urgent tasks with the priority "A"
 155 3. any tasks you can do at your computer or in your office or on the
 156    phone
 157 4. any headlines tagged "project" for which CATEGORY="elephants"
 158 5. any headlines tagged "review" in the file "circuspeanuts.org"
 159 6. any items that have the todo keyword "WAITING"
 160
 161 You could do a number of agenda searches by hand, first calling the
 162 agenda, then the tag-todo search (twice), then a tag search, then a
 163 tag search restricted to the file circuspeanuts.org, and finally the
 164 todo keyword search. In other words:
 165
 166 : C-c a a
 167 : C-c a M +PRIORITY="A"
 168 : C-c a M computer|office|phone
 169 : C-c a m project+CATEGORY="elephants"
 170 : C-x b circuspeanuts.org
 171 : C-c a < m review
 172 : C-c a T WAITING
 173
 174 That would be a lot of manual labor before you had even begun your
 175 work. You could make your life easier by combining these searches into
 176 a single agenda command that compiles the results of all the searches:
 177
 178 #+BEGIN_SRC emacs-lisp
 179 (setq org-agenda-custom-commands
 180       '(("O" "Office block agenda"
 181          ((agenda "" ((org-agenda-ndays 1)))
 182                       ;; limits the agenda display to a single day
 183           (tags-todo "+PRIORITY=\"A\"")
 184           (tags-todo "computer|office|phone")
 185           (tags "project+CATEGORY=\"elephants\"")
 186           (tags "review" ((org-agenda-files '("~/org/circuspeanuts.org"))))
 187                           ;; limits the tag search to the file circuspeanuts.org
 188           (todo "WAITING"))
 189          ((org-agenda-compact-blocks t))) ;; options set here apply to the entire block
 190         ;; ...other commands here
 191         ))
 192 #+END_SRC
 193
 194 You'll notice that you can configure local settings for each of the
 195 searches in a block agenda. This powerful option enables fine-grained
 196 control of the agenda display. You could, for instance, create a block
 197 agenda that displays all headlines tagged "office" in the file
 198 "widgets.org", followed by all headlines tagged "computer" in the file
 199 "clients.org", and so on.
 200
 201 ** An example: GTD weekly review
 202
 203 If you're into GTD, you can use org-agenda-custom-commands to create
 204 block views for the weekly review, such as:
 205
 206 #+BEGIN_SRC emacs-lisp
 207 (setq org-agenda-custom-commands
 208       '(("W" "Weekly Review"
 209          ((agenda "" ((org-agenda-ndays 7))) ;; review upcoming deadlines and appointments
 210                                            ;; type "l" in the agenda to review logged items
 211           (stuck "") ;; review stuck projects as designated by org-stuck-projects
 212           (todo "PROJECT") ;; review all projects (assuming you use todo keywords to designate projects)
 213           (todo "MAYBE") ;; review someday/maybe items
 214           (todo "WAITING"))) ;; review waiting items
 215          ;; ...other commands here
 216         ))
 217 #+END_SRC
 218
 219 * Making the most of local settings
 220
 221 Agenda commands can be used for much more than managing workload. They
 222 are also powerful ways to search and display notes in org files.
 223
 224 One use of custom agenda commands is to create different sets of
 225 search options. Let's say, for instance, that you have three separate
 226 directories of org-files:
 227
 228   - "~/org/" for your project files
 229   - "~/website/" for your published files
 230   - "~/archive/" for old projects and notes
 231
 232 Most of the time, you only want to search your project files, so you
 233 set the global option appropriately:
 234
 235 #+BEGIN_SRC emacs-lisp
 236 (setq org-agenda-files (file-expand-wildcards "~/org/*.org"))
 237 #+END_SRC
 238
 239 But there are no doubt times when you need to search your website or
 240 your archive files. To make this possible, you could create the
 241 following commands:
 242
 243 #+BEGIN_SRC emacs-lisp
 244 (setq org-agenda-custom-commands
 245       '(("Q" . "Custom queries") ;; gives label to "Q"
 246         ("Qa" "Archive search" search ""
 247          ((org-agenda-files (file-expand-wildcards "~/archive/*.org"))))
 248         ("Qw" "Website search" search ""
 249          ((org-agenda-files (file-expand-wildcards "~/website/*.org"))))
 250         ("Qb" "Projects and Archive" search ""
 251          ((org-agenda-text-search-extra-files (file-expand-wildcards "~/archive/*.org"))))
 252                 ;; searches both projects and archive directories
 253         ("QA" "Archive tags search" org-tags-view ""
 254          ((org-agenda-files (file-expand-wildcards "~/archive/*.org"))))
 255         ;; ...other commands here
 256          ))
 257 #+END_SRC
 258
 259 Now you are only a key command away from searching different sets of
 260 org files.
 261
 262 Note that the key triggers in the example above consist of two
 263 characters. If you have numerous custom agenda commands, this is a
 264 nice way to organize the agenda dispatcher into subpages. Only "Q"
 265 will appear on the main dispatcher view, the commands themselves will
 266 appear in a second view after you press "Q".
 267
 268 First view:
 269
 270 [[file:../images/mdl/org-custom-agenda-commands-2.png]]
 271
 272 Second view (after pressing "Q"):
 273
 274 [[file:../images/mdl/org-custom-agenda-commands-3.png]]
 275
 276 The possibilities for using local search settings are myriad. One
 277 could, for instance, tweak display options for sparse tree searches
 278 via the variables org-show-hierarchy-above and org-show-entry-below
 279 (see [[http://orgmode.org/manual/Setting-Options.html#Setting-Options][this section of the manual]]). Or, as Carsten explained in [[http://article.gmane.org/gmane.emacs.orgmode/10114][this
 280 mailing list post]], one can create custom agenda commands that default
 281 to a column view:
 282
 283 #+BEGIN_SRC emacs-lisp
 284 (setq org-agenda-custom-commands
 285       '(("x" "With deadline columns" alltodo ""
 286          ((org-agenda-overriding-columns-format "%20ITEM %DEADLINE")
 287           (org-agenda-view-columns-initially t)))))
 288 #+END_SRC
 289
 290 * Other configuration ideas
 291
 292 This section is for additional ideas for configuring
 293 org-agenda-custom-commands. Feel free to add your own configurations
 294 here.
 295
 296 ** GTD contexts
 297
 298 Keyboard shortcuts to search by GTD contexts.
 299
 300 #+BEGIN_SRC emacs-lisp
 301 (setq org-agenda-custom-commands
 302       '(("g" . "GTD contexts")
 303         ("go" "Office" tags-todo "office")
 304         ("gc" "Computer" tags-todo "computer")
 305         ("gp" "Phone" tags-todo "phone")
 306         ("gh" "Home" tags-todo "home")
 307         ("ge" "Errands" tags-todo "errands")
 308         ("G" "GTD Block Agenda"
 309          ((tags-todo "office")
 310           (tags-todo "computer")
 311           (tags-todo "phone")
 312           (tags-todo "home")
 313           (tags-todo "errands"))
 314          nil                      ;; i.e., no local settings
 315          ("~/next-actions.html")) ;; exports block to this file with C-c a e
 316        ;; ..other commands here
 317         ))
 318 #+END_SRC
 319
 320 ** Priorities
 321
 322 Shortcuts to display tasks by priority level:
 323
 324 #+BEGIN_SRC emacs-lisp
 325 (setq org-agenda-custom-commands
 326       '(("p" . "Priorities")
 327         ("pa" "A items" tags-todo "+PRIORITY=\"A\"")
 328         ("pb" "B items" tags-todo "+PRIORITY=\"B\"")
 329         ("pc" "C items" tags-todo "+PRIORITY=\"C\"")
 330         ;; ...other commands here
 331         ))
 332 #+END_SRC
 333 ** Calendar style views
 334
 335 The following code is useful if you want to see a weekly planner
 336 containing only appointments---that is, with deadlines and scheduled
 337 items omitted:
 338
 339 #+BEGIN_SRC emacs-lisp
 340 (setq org-agenda-custom-commands
 341 '(("c" "Weekly schedule" agenda ""
 342          ((org-agenda-ndays 7)          ;; agenda will start in week view
 343           (org-agenda-repeating-timestamp-show-all t)   ;; ensures that repeating events appear on all relevant dates
 344           (org-agenda-skip-function '(org-agenda-skip-entry-if 'deadline 'scheduled))))
 345         ;; limits agenda view to timestamped items
 346         ;; ...other commands here
 347         ))
 348 #+END_SRC
 349
 350 Another example: you could use the following custom command to see
 351 deadlines due within the next 60 days:
 352
 353 #+BEGIN_SRC emacs-lisp
 354 (setq org-agenda-custom-commands
 355       '(("d" "Upcoming deadlines" agenda ""
 356          ((org-agenda-skip-function '(org-agenda-skip-entry-if 'scheduled))
 357           (org-agenda-ndays 1)
 358           (org-deadline-warning-days 60)
 359           (org-agenda-time-grid nil)))
 360         ;; ...other commands here
 361         ))
 362 #+END_SRC
 363
 364 ** Printed agenda
 365
 366 Here's a fairly complex example of an agenda. The command below will
 367 create a black-and-white block agenda that lists:
 368
 369 1. An overview of appointments for the next seven days.
 370    - I.e., timestamped items but not deadlines or scheduled tasks
 371 2. A compact daily agenda.
 372 3. A list of todos sorted by context.
 373
 374 The sorted todos look like this:
 375
 376 : [ ] errands:  Wash car
 377 : [ ] errands:  Grocery shopping
 378 : [ ] home:  Do laundry
 379 : [ ] home:  Take out trash
 380
 381 And the entire agenda will be saved in a two-column, landscape
 382 postscript file when you type =C-c a e=.
 383
 384 Here's the code:
 385
 386 #+BEGIN_SRC emacs-lisp
 387 (setq org-agenda-custom-commands
 388       '(("P" "Printed agenda"
 389          ((agenda "" ((org-agenda-ndays 7)                      ;; overview of appointments
 390                       (org-agenda-start-on-weekday nil)         ;; calendar begins today
 391                       (org-agenda-repeating-timestamp-show-all t)
 392                       (org-agenda-skip-function '(org-agenda-skip-entry-if 'deadline 'scheduled))))
 393           (agenda "" ((org-agenda-ndays 1)                      ;; daily agenda
 394                       (org-deadline-warning-days 7)             ;; 7 day advanced warning for deadlines
 395                       (org-agenda-todo-keyword-format "[ ]")
 396                       (org-agenda-scheduled-leaders '("" ""))
 397                       (org-agenda-prefix-format "%t%s")))
 398           (todo "TODO"                                          ;; todos sorted by context
 399                 ((org-agenda-prefix-format "[ ] %T: ")
 400                  (org-agenda-sorting-strategy '(tag-up priority-down))
 401                  (org-agenda-todo-keyword-format "")
 402                  (org-agenda-overriding-header "\nTasks by Context\n------------------\n"))))
 403          ((org-agenda-with-colors nil)
 404           (org-agenda-compact-blocks t)
 405           (org-agenda-remove-tags t)
 406           (ps-number-of-columns 2)
 407            (ps-landscape-mode t))
 408          ("~/agenda.ps"))
 409         ;; other commands go here
 410         ))
 411 #+END_SRC