Projects in Emacs Org

Posted: - Modified: | emacs, org, wickedcoolemacs

Introduction

Organizing your tasks into projects can help you plan ahead, track
your progress, and stay motivated. Working from a project list allows
you to plan your day or week instead of just reacting to other
people’s requests. Keeping your projects and tasks in Org makes it
easier for you to review your completed tasks and plan the next step.
If you include some text describing why you want to do the project and
what your intended outcome is, this can help you stay motivated
throughout a long project.

Projects can take a single day or several years. They can be large
projects involving lots of other people and resources, or small
projects that you do on your own. Projects may involve a handful of
separate steps or a hundred things you need to do in order to achieve
your goal. The important thing is that there is more than one step.
If you organize your task list so that related tasks are together,
then you’ll find it easier to get a sense of where you are, where
you’re going, and what you need to do next.

In this section, you will learn how to:

  • Create projects,
  • Organize your tasks into projects,
  • Review your ongoing projects, and
  • Mark projects as finished.

I’ll assume that you’re using Emacs 22, and that you’ve set up Org
using an ~/organizer.org agenda file and the basic configuration
suggested in either “Org and GTD” or “Org as a Day Planner.” I’ll also
assume that you’re familiar with switching between the Org agenda view
and the Org organizer file, and that you’re comfortable navigating
around Emacs.

The examples I’ll use focus on yearly goals. You might also have
short-term projects or long-term plans. Feel free to adapt the
examples as needed.

Open your ~/organizer.org file. If you’ve collected your tasks as
suggested in the previous sections on Using Org as a Day Planner or
Using Org for GTD, your ~/organizer.org file might look something like
this:

 * Inbox
 ** TODO Read Emacs Lisp intro
 ** TODO Write yearly review
 ** TODO Exercise
 ** TODO Browse the Emacs Wiki

Create new top-level headings for this year’s goals or the projects
that you’re working on. You can create a top-level heading by
typing * and the heading, like this:

 * Learn more about Emacs
 * Go on vacation
 ...
 * Inbox
 ** TODO Read Emacs manual
 ...

It’s a good idea to add the projects to the beginning of the file
(before your Inbox) because M-x remember adds new tasks or notes to
the end of the file. If the last major heading as * Inbox, then the
tasks and notes are automatically added to it. If the last major
heading is a project, the tasks and notes may get misfiled.

What are your projects?
Yearly goals? I’ve got twenty-year plans!

If you’re a top-down planner, you’ll find it easy to list your
projects. In fact, you might have a ten- or even twenty-year plan
already written down. You’ll find this section straightforward,
because you’re already used to planning in terms of projects.
Go ahead and adapt the examples to your long-term plans.

Yearly goals? I live day by day!

If you’re a bottom-up planner, you might be giving me a weird look
right now. “Yearly goals? I’m lucky if I can figure out how to get
through the next day!” This section will also show you how to find the
recurring themes in your task list and organize them into projects.
Give project-based planning a try for a month. If this way of thinking
doesn’t work for you, Org will work just fine without projects.

You probably have projects, even if you can’t think of any right
now. Review your ~/organizer.org file. If you haven’t written down
everything you needed to do yet, go through the section on basic
configuration for your planning style (GTD or day planning). Once you
have a list of things to do, you can then review it for big tasks,
related tasks, and other project clues.

Read your tasks and ask yourself the following questions:

  • *Can I do this in one sitting?* Big tasks such as “Write a book” are often projects in disguise. Use projects so that you can break them down into smaller, doable tasks.
  • *Is this related to other tasks?* Related tasks such as “Book a flight” and “Plan my itinerary” are often clues to a project like “Go on vacation”. Use projects so that you can review related tasks together.
  • *Why am I doing this?* When you think about the reason why you’re doing something, you’ll often find a bigger project. For example, if one of your tasks is “Set up an automatic retirement savings plan”, then the question “Why am I doing this?” may lead you to the project “Plan for retirement”. Use projects to help you think of other ways to move towards that goal.

Big tasks need to be broken down into smaller tasks anyway, and
organizing them into projects will help you make them more
manageable. You may not want to organize all of your other tasks into
projects. If you can pick some major themes to focus on, though, then
you’ll be able to see how the different things you do are related to
each other, and you’ll be able to think of other ways to work on those
projects. If you’re starting out with project-based thinking, maybe
you can pick three to five projects and try to do a little work on
each of them every day.

If you still don’t identify any projects, that’s okay. You can use Org
as a straightforward task list. Jump ahead to the section on “Tags”,
as you’ll probably find that useful.

On the other hand, if this step turns up plenty of projects, resist
the temptation to over-correct and end up with hundreds of projects. I
find that more than 7 active projects gets hard to manage. Pick a few
main themes that you’d like to work on, and make everthing else
something you plan to do someday.

Project tasks

Creating tasks

Now that you have project headings, think of the next thing you need
to do in order to move those projects forward. If you’ve already
written down those tasks, move them under the appropriate project
heading. If not, type them in.

In order for a task to belong to a project, it needs to be under the
heading and at a lower level. For example, if your project heading has
one star, like this:

 * Learn Emacs

then your TODO headings should have two stars, like this:

 * Learn Emacs
 ** TODO Read the Emacs manual
 ** TODO Read the Emacs Lisp Intro manual (eintr)
 ** TODO Install the Emacs source code

If your tasks are not at the right level, you can add the star
manually by editing the heading. You can also use M-right and M-left
(org-metaright and org-metaleft) while on a heading in order to
promote or demote it, and you can use M-S-right and M-S-left
(org-shift-metaright and org-shift-metaleft) to promote or demote
entire subtrees.

To move tasks up and down within the project, you can copy and paste
the text. You can use M-Up and M-Down (org-metaup and org-metadown) to
move subtrees.

Think of tasks you can do within the next week in order to move each
of your projects forward. Add next actions to all of your active
projects. Creating next actions for each of your projects makes it
easier to remember to keep moving forward.

Organizing tasks

If you have many tasks in a project, you may want to organize them
into sub-projects. For example, you might divide a software project
into components. If you’re starting from scratch, you can create the
project structure by typing in more stars for sub-project
headings. For example:

 * Learn Emacs
 ** Read mail
 *** TODO Choose a mail client
 *** TODO Install and configure the mail client
 *** TODO Send a message
 ...
 ** Browse the Web
 *** Read through the w3m documentation
 ...

You can also demote an existing project into a subproject.
Use M-S-right (org-shift-metaright) on the
current project headline in order to demote it to a sub-project. This
will also demote the tasks within the project. For example, demoting
this:

 * Learn Emacs
 ** TODO Choose a mail client
 ** TODO Install and configure the mail client
 ** TODO Send a message

will result in this:

 ** Learn Emacs
 *** TODO Choose a mail client
 *** TODO Install and configure the mail client
 *** TODO Send a message

Then you can change the heading and add another heading above it, like this:

 * Learn Emacs
 ** Read mail
 *** TODO Choose a mail client
 *** TODO Install and configure the mail client
 *** TODO Send a message

This kind of organization is optional, but it can help you get an idea
of the overall structure of your project. Using different levels
allows you to hide and show groups of headings by pressing TAB on the
heading.

Now that you’ve created your project tasks and organized them the way
you want, it’s time to actually do the work.

Working on tasks

If you use Org as a day planner, you may also want to schedule the
tasks onto specific days with C-c C-s (org-schedule). You can review
your daily or weekly agenda with C-c a a (org-agenda,
org-agenda-list), switching between daily and weekly views with d and
w (org-agenda-day-view and org-agenda-week-view).

You can work with the next actions in the same way you work with other
tasks, rescheduling them or marking them as STARTED, WAITING or DONE
with the keyboar shortcuts introduced in the previous section on Org
and GTD or Org as a Day Planner.

When you finish a project task, think of the next action you can do in
order to move that project forward. If you use Org as a day planner,
schedule the next action onto your calendar as well.

Reviewing projects

You can review your projects by opening your ~/organizer.org and
browsing through the headings. S-tab (org-shifttab) changes the
visibility of headings, so you can see just the top-level headings or
all the details. You can use TAB (org-cycle) on a headline to show or
hide subtrees.

Reviewing a list of projects

If you have many projects, you’ll want a shorter view of just your
active projects. To make it easier to review projects, add a PROJECT
tag to all your active project headlines. You can add a tag by
editing your ~/organizer.org and moving your cursor to the headline
and typing C-c C-c (org-ctrl-c-ctrl-c), followed by the name of the
tag (PROJECT). You can also manually type :TAGNAME: at the end of the
headings, like this:

 * Learn more about Emacs        :PROJECT:
 ** TODO Read the Emacs manual
 ** TODO Read the Emacs Lisp Intro manual (eintr)
 ...
 * Go on vacation                :PROJECT:
 ...
 * Inbox
 ...

You might classify some of your projects as someday/maybe – things
that are nice to think about, but which you aren’t acting on right
now. Tag your inactive or someday/maybe projects with PROJECT and
MAYBE. If you’re editing the ~/organizer.org file, just
add :PROJECT:MAYBE: to the heading. If you’re tagging it with C-c C-c
(org-ctrl-c-ctrl-c), specify PROJECT:MAYBE as the tag.

 * Learn more about Emacs        :PROJECT:
 * Go on vacation                :PROJECT:MAYBE:
 ...
 * Inbox
 ** TODO Read Emacs manual
 ...

Now that you’ve tagged your projects, you can view just your project
headlines with a custom agenda command. Custom agenda views are a
terrific feature in Org, and you can do a lot with them if you know a
little Emacs Lisp. Here’s what you need to add to your ~/.emacs in
order to get a list of your active projects and your someday/maybe
projects:

(setq org-agenda-custom-commands
      '(("p" tags "PROJECT-MAYBE-DONE" nil)  ;; (1)
        ("m" tags "PROJECT&MAYBE" nil)       ;; (2)
        ;; ... put your other custom commands here
       ))
  • (1) This makes C-c a p (org-agenda, p) show your active projects.
  • (2) This makes C-c a m (org-agenda, m) show your “maybe” projects.

With these two commands, you can quickly review your active and
inactive projects. To jump to a project from the agenda view, move
your cursor to the heading and press RET (org-agenda-switch-to). If
you want to scan through the projects quickly, use f
(org-agenda-follow-mode) in the agenda view to turn on follow mode,
then move to different headlines. Another window will show the
headline at point.

If you review your projects at least once a week, you’ll find it
easier to make regular progress. If you want to combine your
weekly/daily review with your project list, you can do that with
org-agenda-custom-commands as well. Here’s what you’d put in your
~/.emacs:

(setq org-agenda-custom-commands
      '(("p" tags "PROJECT-MAYBE-DONE" nil)
        ("m" tags "PROJECT&MAYBE" nil)
        ("a" "My agenda"                            ;; (1)
         ((org-agenda-list)                         ;; (2)
          (tags "PROJECT-MAYBE-DONE")))             ;; (3)
        ;; ... put your other custom commands here
       ))
  • (1) The first argument is the shortcut key, the second is a name for the agenda view
  • (2) Your daily or weekly agenda. The d and w (org-agenda-day-view and org-agenda-week-view) shortcuts work if the point is within this section
  • (3) A list of your active projects

This configures C-c a a (org-agenda, “My agenda”) to display your
agenda and a list of your project headings. Again, you can press RET
(org-agenda-switch-to) to jump to a project from its heading in the
agenda view.

Reviewing your stuck projects

You might have forgotten to create next actions for some of your
active projects. Org can help you find projects which don’t have next actions.
You can then decide if the project is complete or if it needs further action.

To list stuck projects, you first need to tell Org what a stuck
project is. The following code defines a stuck project as an active
project (not tagged “maybe” or “done”) that doesn’t have a TODO or
STARTED action, if the body of the project doesn’t contain “*lt;IGNORE>”. Add this to your ~/.emacs and evaluate it:

(setq org-stuck-projects
      '("+PROJECT/-MAYBE-DONE" ("TODO" "STARTED") nil "\\<IGNORE\\>"))

Then you can use M-x org-agenda-list-stuck-projects or C-a a #
(org-agenda, org-agenda-list-stuck-projects) to show only the stuck
projects. Review this list and jump to the headlines.

Want to add that to your custom agenda view? Modify the org-agenda-custom-commands value in your ~/.emacs to be like this:

(setq org-agenda-custom-commands
      '(("p" tags "PROJECT-MAYBE-DONE" nil)
        ("m" tags "PROJECT&MAYBE" nil)
        ("a" "My agenda"
         ((org-agenda-list)
          (org-agenda-list-stuck-projects)          ;; (1)
          (tags "PROJECT-MAYBE-DONE")))
        ;; ... put your other custom commands here
       ))
  • (1) It’s a good idea to put it before your regular project list so that you can see what needs your attention.

What about finished projects? You might want to keep them in your Org
file, but they shouldn’t show up in your active and inactive project
lists. Org can keep track of those projects too.

Marking projects as done

If you look at the custom commands above, you’ll notice the “-DONE”
specifier. “DONE” is the tag we’ll use to indicate done projects. To
tag a project as done, move the point to the project heading and type
C-c C-c (org-ctrl-c-ctrl-c). The tag prompt will default to the
current tags. Just add “DONE” and press Enter. With the custom
commands we’ve set up, projects tagged DONE will not show in your
active, inactive, or stuck project lists.

You can also add the tag manually. For example, if the project heading is

 * Learn Emacs    :PROJECT:

and you’re happy with your level of Emacs proficiency, then you can
mark it as done by changing it to

 * Learn Emacs    :PROJECT:DONE:

If you have plenty of completed projects, your Org file might be quite
large. You can mark a subtree for archiving by typing C-c C-x C-a
(org-toggle-archive-tag). This hides it from most Org commands. You
can also archive a tree into a different file with C-c C-x C-s
(org-advertized-archive-subtree).

Wrapping up

Now you can create projects, manage your project tasks, and review
your active, inactive, and stuck projects in Org. You know how to mark
projects as completed and how to archive them. You’ve also started
using tags to dynamically generate reports from your Org file.

Tags can do a lot more. To find out what else you can do with tags,
read the next section on “Tagging in Org”.

You can comment with Disqus or you can e-mail me at sacha@sachachua.com.