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

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t 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 [[https://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 [[https://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 [[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
  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 [[https://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-span 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-span 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 [[https://orgmode.org/manual/Setting-options.html#Setting-options][this section of the manual]]). Or, as Carsten explained in [[https://orgmode.org/list/537DBEBB-18DC-4FB9-8CC7-26D6338946FA@uva.nl][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 * Speeding up custom agenda commands
 291
 292 The most recent versions of org-mode (the git repo or versions greater
 293 than 6.35) have a new variable that helps to speed up certain types of
 294 agenda commands. The variable is =org-agenda-entry-types= and it can
 295 be set *locally* within custom agenda commands via the customize
 296 interface.
 297
 298 As always, you can learn more about the variable by typing =M-x
 299 describe-variable [RET] org-agenda-entry-types=. According to the
 300 [[file:../org-glossary.org::#docstring][docstring]], the value =org-agenda-entry-types= is a list that consists
 301 of any or all of the following items:
 302
 303   - :timestamp :: List items containing a date stamp or date range
 304                   matching the selected date. This includes sexp
 305                   entries in angular brackets.
 306
 307   - :sexp :: List entries resulting from plain diary-like sexps.
 308
 309   - :deadline :: List deadline due on that date. When the date is
 310                  today, also list any deadlines past due, or due
 311                  within `org-deadline-warning-days'. `:deadline' must
 312                  appear before `:scheduled' if the setting of
 313                  `org-agenda-skip-scheduled-if-deadline-is-shown' is
 314                  to have any effect.
 315
 316   - :scheduled :: List all items which are scheduled for the given
 317                   date. The diary for *today* also contains items
 318                   which were scheduled earlier and are not yet marked
 319                   DONE.
 320
 321 By default, the daily/weekly agenda includes all of these items in its
 322 results. Sometimes, however, you might want to construct agenda views
 323 that consist only of certain types of entries, such as a list of
 324 upcoming deadlines or a weekly or monthly calendar that includes only
 325 timestamps and diary sexps. The variable =org-agenda-entry-types=
 326 allows you to search for such a subset of items quite efficiently
 327 (without bothering with the other items).
 328
 329 Here is an example of a weekly calendar using
 330 =org-agenda-entry-types=.
 331
 332 #+begin_src emacs-lisp
 333   (setq org-agenda-custom-commands
 334         '(("c" "Calendar" agenda ""
 335            ((org-agenda-span 7)                          ;; [1]
 336             (org-agenda-start-on-weekday 0)               ;; [2]
 337             (org-agenda-time-grid nil)
 338             (org-agenda-repeating-timestamp-show-all t)   ;; [3]
 339             (org-agenda-entry-types '(:timestamp :sexp))))  ;; [4]
 340         ;; other commands go here
 341           ))
 342 #+end_src
 343
 344 The options above create (1) a weekly calendar that (2) starts on
 345 Sunday and (3) includes all instances of repeating timestamps.
 346 Moreover, the calendar is generated quite quickly because the agenda
 347 command (4) only searches for timestamps and diary sexps and does not
 348 bother with deadlines and scheduling timestamps.
 349
 350 Another example might arise if one wants an overview of all deadlines
 351 due within the next 365 days:
 352
 353 #+begin_src emacs-lisp
 354   (setq org-agenda-custom-commands
 355         '(("d" "Upcoming deadlines" agenda ""
 356                   ((org-agenda-time-grid nil)
 357                    (org-deadline-warning-days 365)        ;; [1]
 358                    (org-agenda-entry-types '(:deadline))  ;; [2]
 359                    ))
 360         ;; other commands go here
 361          ))
 362 #+end_src
 363
 364 This custom command shows all deadlines that (1) fall due within the
 365 upcoming year. It does so quite efficiently by (2) looking for
 366 deadlines and nothing else.
 367
 368 Tip: if you want to exclude all agenda entry types, just set
 369 =org-agenda-entry-types= to nil.
 370
 371 * Other configuration ideas
 372
 373 This section is for additional ideas for configuring
 374 org-agenda-custom-commands. Feel free to add your own configurations
 375 here.
 376
 377 ** GTD contexts
 378
 379 Keyboard shortcuts to search by GTD contexts.
 380
 381 #+BEGIN_SRC emacs-lisp
 382 (setq org-agenda-custom-commands
 383       '(("g" . "GTD contexts")
 384         ("go" "Office" tags-todo "office")
 385         ("gc" "Computer" tags-todo "computer")
 386         ("gp" "Phone" tags-todo "phone")
 387         ("gh" "Home" tags-todo "home")
 388         ("ge" "Errands" tags-todo "errands")
 389         ("G" "GTD Block Agenda"
 390          ((tags-todo "office")
 391           (tags-todo "computer")
 392           (tags-todo "phone")
 393           (tags-todo "home")
 394           (tags-todo "errands"))
 395          nil                      ;; i.e., no local settings
 396          ("~/next-actions.html")) ;; exports block to this file with C-c a e
 397        ;; ..other commands here
 398         ))
 399 #+END_SRC
 400
 401 ** Priorities
 402
 403 Shortcuts to display tasks by priority level:
 404
 405 #+BEGIN_SRC emacs-lisp
 406 (setq org-agenda-custom-commands
 407       '(("p" . "Priorities")
 408         ("pa" "A items" tags-todo "+PRIORITY=\"A\"")
 409         ("pb" "B items" tags-todo "+PRIORITY=\"B\"")
 410         ("pc" "C items" tags-todo "+PRIORITY=\"C\"")
 411         ;; ...other commands here
 412         ))
 413 #+END_SRC
 414 ** Calendar style views
 415
 416 The following code is useful if you want to see a weekly planner
 417 containing only appointments---that is, with deadlines and scheduled
 418 items omitted:
 419
 420 #+BEGIN_SRC emacs-lisp
 421 (setq org-agenda-custom-commands
 422 '(("c" "Weekly schedule" agenda ""
 423          ((org-agenda-span 7)           ;; agenda will start in week view
 424           (org-agenda-repeating-timestamp-show-all t)   ;; ensures that repeating events appear on all relevant dates
 425           (org-agenda-skip-function '(org-agenda-skip-entry-if 'deadline 'scheduled))))
 426         ;; limits agenda view to timestamped items
 427         ;; ...other commands here
 428         ))
 429 #+END_SRC
 430
 431 Another example: you could use the following custom command to see
 432 deadlines due within the next 60 days:
 433
 434 #+BEGIN_SRC emacs-lisp
 435   (setq org-agenda-custom-commands
 436         '(("d" "Upcoming deadlines" agenda ""
 437            ((org-agenda-entry-types '(:deadline))
 438             ;; a slower way to do the same thing
 439             ;; (org-agenda-skip-function '(org-agenda-skip-entry-if 'notdeadline))
 440             (org-agenda-span 1)
 441             (org-deadline-warning-days 60)
 442             (org-agenda-time-grid nil)))
 443           ;; ...other commands here
 444           ))
 445 #+END_SRC
 446
 447 ** Printed agenda
 448
 449 Here's a fairly complex example of an agenda. The command below will
 450 create a black-and-white block agenda that lists:
 451
 452 1. An overview of appointments for the next seven days.
 453    - I.e., timestamped items but not deadlines or scheduled tasks
 454 2. A compact daily agenda.
 455 3. A list of todos sorted by context.
 456
 457 The sorted todos look like this:
 458
 459 : [ ] errands:  Wash car
 460 : [ ] errands:  Grocery shopping
 461 : [ ] home:  Do laundry
 462 : [ ] home:  Take out trash
 463
 464 And the entire agenda will be saved in a two-column, landscape
 465 postscript file when you type =C-c a e=.
 466
 467 Here's the code:
 468
 469 #+BEGIN_SRC emacs-lisp
 470   (setq org-agenda-custom-commands
 471         '(("P" "Printed agenda"
 472            ((agenda "" ((org-agenda-span 7)                      ;; overview of appointments
 473                         (org-agenda-start-on-weekday nil)         ;; calendar begins today
 474                         (org-agenda-repeating-timestamp-show-all t)
 475                         (org-agenda-entry-types '(:timestamp :sexp))))
 476             (agenda "" ((org-agenda-span 1)                      ; daily agenda
 477                         (org-deadline-warning-days 7)            ; 7 day advanced warning for deadlines
 478                         (org-agenda-todo-keyword-format "[ ]")
 479                         (org-agenda-scheduled-leaders '("" ""))
 480                         (org-agenda-prefix-format "%t%s")))
 481             (todo "TODO"                                          ;; todos sorted by context
 482                   ((org-agenda-prefix-format "[ ] %T: ")
 483                    (org-agenda-sorting-strategy '(tag-up priority-down))
 484                    (org-agenda-todo-keyword-format "")
 485                    (org-agenda-overriding-header "\nTasks by Context\n------------------\n"))))
 486            ((org-agenda-with-colors nil)
 487             (org-agenda-compact-blocks t)
 488             (org-agenda-remove-tags t)
 489             (ps-number-of-columns 2)
 490              (ps-landscape-mode t))
 491            ("~/agenda.ps"))
 492           ;; other commands go here
 493           ))
 494 #+END_SRC