Using categories to organize your Org agenda

D.C. Toedt wanted to share this tip for Org Mode agenda organization:

I’ve just discovered that it helps to add a :CATEGORY: property to the top-level, non-TODO heading that identifies the project.  Using your example:

* Project ABC

** TODO A task related to Project ABC
** TODO Another task related to ABC
*** TODO Subtask

In my bog-standard org-mode setup, this results in “ABC” being displayed in the far-left column of the agenda instead of just “todo” (which seems to be the default). This is great — it means that, in the text of the “Subtask” todo entry itself, I don’t need to include a reminder of what project the todo entry is associated with.

Here’s an agenda mockup to illustrate the point, augmented with a “default” entry from my own to-do list:

  todo:       Scheduled:  Follow up on expense reimbursement request
  ABC:        Scheduled:  Subtask

This also allows filtering the agenda by the category.

Thanks for sharing, D.C.!

The category actually defaults to the first part of your, so becomes todo, becomes organizer, etc. I keep an,,, etc. Keeping my routine tasks in allows me to filter them with a custom agenda command like:

            ("w" "Weekly review" agenda ""
             ((org-agenda-span 7)
              (org-agenda-log-mode 1)) "~/Dropbox/agenda/this-week.html")

            ("W" "Weekly review sans routines" agenda ""
             ((org-agenda-span 7)
              (org-agenda-log-mode 1)
              (org-agenda-tag-filter-preset '("-routine"))) "~/Dropbox/agenda/this-week-nonroutine.html")

so that I can see all the tasks (including routine tasks) in my regular weekly review, and just the special stuff in a separate view. You can see the whole definition of org-agenda-custom-commands in my Emacs configuration.

Update 2016-12-18: Oops! I just remembered that filtering by -routine is actually made possible by the #+FILETAGS: :routine: I have in, which has the additional benefit of allowing me to mark tasks in other files as routine by adding the :routine: tag to them. You can, however, still use categories to filter your agenda. < (org-agenda-filter-by-category) in an agenda view will filter by category, or use a match filter like CATEGORY="routines" to match on the category. Also, it turns out you can set up category icons by customizing org-agenda-category-icon-alist – hmm…

D.C.’s tip is handy if you want to keep those groups of tasks in one file, but still want that kind of visual indication in your agenda (and the ability to filter by it).

Have fun!

One Pingback/Trackback

  • Pingback: The Org Mode Category Property | Irreal()

  • Will

    Sacha, do you filter your agenda by effort estimates? If so, is that something you’ve added to your config? I’ve cribbed heavily from Bernt Hansen’s config with great results. But I can’t seem to come to grips with filtering by effort. I haven’t been able to understand the org mode manual entry on this topic.

    • Back when I set effort estimates on my tasks, I tended to sort by effort estimate instead of filtering by it. For an example, see the “All unscheduled by context” org-agenda-custom-commands in my config at . Would something like that work for you?

      • Will

        Thanks, Sacha. My agenda already sorts by effort and that can become visible if I use org-agenda-columns. I wanted to filter so that only tasks or projects of a certain effort estimate are visible. I could limit the original agenda to a certain effort but that would take more time. I like how quickly I’m able to filter and already compiled agenda.

        Having said all that, your config reminds me that there are many ways to approach these problems in Emacs. So thanks again!

        • Oh, try an org-agenda-custom-commands entry like this: (“5” “Quick tasks” tags-todo “EFFORT>=\”0:05\”&EFFORT<="0:15"")

          I put a minimum effort filter in there so that it skips tasks that don't have any effort estimates set. You could also use something like ("0" "Unestimated tasks" tags-todo "EFFORT=""") to look for tasks that don't have effort estimates.

          • Will

            That is very helpful. I need to take a closer look at the “tags-todo” variable. Thank you!

          • Ah! That’s actually more straightforward. You should be able to use / (org-agenda-filter-by-tag) . On my system, I need to press TAB in order to edit the query.

            If you want to do this programmatically so that you can create your own shortcut for it, it would probably look something like (setq org-agenda-query-string “EFFORT=”””) (org-agenda-redo). Is that enough for you to go on?

          • Will

            Sacha, I appreciate your help but I’m afraid that manual effort filtering has never worked for me.

            You describe agenda filtering by entering “/” (org-agenda-filter-by-tag) and then “TAB”. I’m not sure how this is supposed to work. I tried entering the regular expression string above but that didn’t work. I’m sure I’m misunderstanding something basic. I’m also unsure of how to use the elisp to create the shortcut although I haven’t explored that thoroughly yet.

            However, I want to mention something that would seem to be the obvious approach to filtering for effort: entering “_” (org-agenda-filter-by-effort) and then entering an operator “, =” followed by the one-digit index (eg, “3” for “0:30”). This is described pretty clearly in the manual. And I’ve tried just about every operator and value possible. However, the result of those attempts has always been the same: the filter removes all entries or displays all of them.

            Until you provided some of the examples above, I thought that something in my agenda setup might be preventing effort properties from being utilized or made available for filtering. However, I’m able to create a heading in my agenda for tasks that have specific effort estimates attached (see the elisp below).

            (tags-todo “EFFORT>=”0:05″&EFFORT<="0:30""
            ((org-agenda-overriding-header "30 minute tasks")
            (org-tags-match-list-sublevels nil)))

            So I'm puzzled. My goal is to filter an already created agenda by effort. I can create headings in an agenda that have specific effort estimates but I'd like to leave my headings alone and filter as needed. I really appreciate your help. And these comments have helped me to clarify what I'm trying to do and the approaches that seem to be available. However, I'm still unsure of how to achieve my goal. Makes me wish I knew more elisp!

          • Huh, you’re right, just changing org-agenda-query-string or using doesn’t seem to filter it properly on my end.

            Using _ to filter by effort works for me in 8.3.6, though. Hmm… (Thanks for teaching me about a new command!)

            Might be something to ask on the Org Mode mailing list, in case it’s a bug. Sorry about the confusion, and thanks for posting wonderfully detailed notes!

  • ibichka

    Hi Sacha, I was wondering if you could help me. I’m attempting at customising the org-agenda-custom-commands variable in my .emacs file (I’m new to emacs). I’d like to see in my ‘C-a a’ menu an extra shortcut to a customised view. Right now, by default, I have ‘n’ for “Agenda and all TODOs: set of 2 commands”. I just would like to add another one view, which would be the same view but instead of showing all TODOs, showing only all _unscheduled_ TODOs (because the scheduled ones appear anyway in the agenda view). Any help much appreciated!

    • ibichka

      A follow-up: I tried the following:

      (add-to-list ‘org-add-agenda-custom-commands
      ‘(“b” todo “UNSCHEDULED TODOs”
      ((org-agenda-skip-function ‘(org-agenda-skip-entry-if ‘scheduled))
      (org-agenda-overriding-header “Unscheduled TODOs: “))))

      However, I get the following error:

      “Symbol’s value as variable is void: org-add-agenda-custom-command”

      Any ideas?

      • Good try! org-add-agenda-custom-command is actually a function, so you probably want something more like (add-to-list ‘org-agenda-custom-commands ‘(“b” todo …)).

        I haven’t used org-add-agenda-custom-command before, but it looks like you could use it like this: (org-add-agenda-custom-command ‘(“b” todo …)). has an example.

        • ibichka

          Thanks Sacha. However, the code you provided is exactly the same I wrote above and it won’t work :(

          • It’s a subtle difference, I know! The first version doesn’t have the word “add” and uses the plural – org-agenda-custom-commands, that’s the variable. The second version uses org-add-agenda-custom-command doesn’t have add-to-list. Hope that helps!

          • ibichka

            Thanks, Sacha. However, I get the message (after eval-buffer my .emacs): symbol’s value as variable is void: org-agenda-custom-commands.