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

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