Org GTD is an attempt to implement the GTD flow described in the GTD book as faithfully as possible.
This manual is for Org GtD version 2.0.
Copyright (C) 2018-{{{year}}} Aldric Giacomoni <[email protected]>You can redistribute this document and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
This package tries to replicate as closely as possible the GTD workflow (see diagram below).This package, and this documentation, assume familiarity with the flow of GTD as described in the book.
This package provides a system that allows you to capture incoming things into an inbox, then process the inbox and categorize each item based on the GTD categories. It leverages org-agenda to show today’s items as well as the NEXT items. It also has a simple project management system, which currently assumes all tasks in a project are sequential.
+-------+
|"STUFF"|
+---+---+
|
+---v---+
|IN BOX |
+---+----+
| Eliminate +----------+
| +------------> Trash |
+----v------+ | +----------+
|What is it?| |
+----+------+ | +----------+
| | Incubate | Someday/|
| +------------> Maybe |
+----------+ YES (Multi-Step) +------v------+ NO | +----------+
| Projects <---------------------+ Is it +-----+
+-+----^---+ | Actionable?| | File +----------+
| | +----------------+ +------+------+ +------------>Reference |
| | Review For | | +----------+
+-v----+---+ Actions | | YES
| Planning | +----------->
+----------+ |
+-----v------+ Less than
Delegate | What's the | 2 minutes +--------+
+------------+Next Action?+-------------------> DO IT |
| +-------+----+ +--------+
| |
| | FOR ME
| | Specific Date or Time
| +----------------------------+
| ASAP | |
+----v-----+ +--v-------+ +-----v----+
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
+----------+ +----------+ +----------+
Waiting For Next Actions Calendar
Org GTD now handles dependency loading more intelligently, so you no longer need the overly complicated setup of org-gtd, org-agenda and org-capure in your config for dependency loading. You now only need org-gtd. If you are using use-package then the following is the minimal config required.
(use-package org-gtd :after 'org)You no longer need to configure org-agenda-property-list yourself. Org GTD now manages the context with a macro, with-org-gtd-context. Any prior configuration of this subpackage can be handled as you did before.
You no longer need to configure org-agenda-files. Same reason as above. This allows you to use org-gtd without destroying your previous setup, and makes it easier to try org-gtd and then get rid of it if you don’t like it.
You no longer need to configure org-agenda-custom-commands. Now there’s org-gtd-agenda-custom-commands to take the relay - see the variable documentation for more information.
The org-capture templates are now simplified and managed by org-gtd-capture-templates. If you did not change the default configuration, then you can just remove what you had. Read the variable documentaton for further information.
My org-gtd config for 1.x was:
(use-package org-gtd
:after org
:demand t
:pin melpa
:custom
(org-gtd-directory stag-org-gtd-directory)
(org-agenda-property-list '("DELEGATED_TO"))
(org-edna-use-inheritance t)
:config
(org-edna-load)
:bind
(("C-c d c" . org-gtd-capture)
("C-c d a" . org-agenda-list)
("C-c d p" . org-gtd-process-inbox)
("C-c d n" . org-gtd-show-all-next)
("C-c d s" . org-gtd-show-stuck-projects)
:map org-gtd-process-map
("C-c c" . org-gtd-choose)))
(use-package org-agenda
:ensure nil
:no-require t
:after (org-gtd)
:custom
(org-agenda-skip-deadline-if-done t)
(org-agenda-skip-scheduled-if-done t)
(org-agenda-files `(,org-gtd-directory))
(org-agenda-custom-commands '(("g" "Scheduled today and all NEXT items" ((agenda "" ((org-agenda-span 1))) (todo "NEXT"))))))
(use-package org-capture
:ensure nil
:after org-gtd
:config
(setq org-capture-templates `(("i" "Inbox"
entry (file ,(org-gtd--path org-gtd-inbox-file-basename))
"* %?\n%U\n\n %i"
:kill-buffer t)
("t" "Todo with link"
entry (file ,(org-gtd--path org-gtd-inbox-file-basename))
"* %?\n%U\n\n %i\n %a"
:kill-buffer t))))And my config for 2.0 is:
(use-package org-gtd
:after org
:quelpa (org-gtd :fetcher github :repo "trevoke/org-gtd.el"
:branch "2.0.0" :upgrade t)
:demand t
:custom
(org-gtd-directory stag-org-gtd-directory)
(org-edna-use-inheritance t)
:config
(org-edna-mode)
:bind
(("C-c d c" . org-gtd-capture)
("C-c d e" . org-gtd-engage)
("C-c d p" . org-gtd-process-inbox)
("C-c d n" . org-gtd-show-all-next)
("C-c d s" . org-gtd-show-stuck-projects)
:map org-gtd-process-map
("C-c c" . org-gtd-choose)))org-agenda-list->org-gtd-engageorg-gtd-clarify-finalize->org-gtd-choose(see the section on Key bindings below)
You need to rename CANCELED to CNCL. a simple string replace in the org-gtd-directory will do the trick.
Org GTD no longer uses the name of the heading to figure out how to refile things, and which headings are useful. Instead it uses a custom Org property called ORG_GTD. This means you are free to rename the existing headings whatever you want, but you DO need to make some adjustments to your current files.
If you would like to add new refile targets, it’s simple, follow these instructions.
For projects, make sure the heading has the following two properties.
:PROPERTIES:
:TRIGGER: next-sibling todo!(NEXT)
:ORG_GTD: Projects
:END:
For other headings, make sure there is an ORG_GTD property, like for the project, above.
The other ORG_GTD properties are set as follows. Note that Single and Delegated actions are together now, so you can merge those headings if you want.
- Scheduled actions
ORG_GTD: Calendar- Single & Delegated actions
ORG_GTD: Actions- Incubated actions
ORG_GTD: Incubated
For incubated actions, version 1.x of Org GTD asked for second-level heading, such as *To Read. No more - these are now top-level headings, exactly as described above, with a heading property of ORG_GTD: Incubated.
There is a new variable, org-gtd-refile-to-any-target. By default this variable is set to t. This means that Org GTD will refile to whatever the first target it finds is. This is the default value because it most closely matches the behavior for version 1.x.
THIS BEHAVIOR ALSO APPLIES TO INCUBATE REFILE TARGETS. Therefore, if you have multiple incubated refile targets, you will need to set this variable to nil, or change to a single refile target. You can e.g. set a custom property to describe the kind of incubated item it is, if it is useful to you, something like:
* Incubated ** Buy a boat SCHEDULED: <2035-06-01 Fri> :PROPERTIES: :INCUBATE: big financial investment :END:
Version 1.x of Org GTD recommended a binding for org-gtd-clarify-finalize. This binding must now be set as follows (replace the keybinding with one of your choice):
(define-key org-gtd-process-map (kbd "C-c c") #'org-gtd-choose)This package is on MELPA and MELPA stable under the name org-gtd.
Just make sure this is loaded after org-mode like so.
(use-package org-gtd :after org)Check out the source code for dependencies and install them.
Then, clone this repo to a directory of your choice, e.g. ~/.emacs.d/packages.
Finally, add this to your config:
(add-to-list 'load-path "~/.emacs.d/packages")
(require 'org-gtd)Just turn on org-gtd-mode (M-x org-gtd-mode). This will set up emacs, Org mode, and Org GTD’s dependencies. It will wrap a number of org-agenda functions to work smoothly. If you are just testing out Org GTD, this is a good way to start.
Turn off org-gtd-mode to restore emacs to pre-org-gtd settings.
Note, you should still head over to the *Recommended key bindings section.
package: https://www.nongnu.org/org-edna-el/
This is one of the dependencies. This setting change is REQUIRED. It automatically changes the next TODO heading to NEXT in a project when you’ve finished the current task.
You do not need to make this change if you choose to toggle org-gtd-mode.
(setq org-edna-use-inheritance t)
(org-edna-mode 1)The most direct way to find out about the configuration options for org-gtd is to see the customize group: M-x customize-group RET org-gtd. They are all optional because they all come with default values.
The only one you may want to change before starting to use Org GTD is org-gtd-directory, which is the directory that Org GTD
will look to for everything it needs to do.
The configuration options will also be mentioned in the relevant subsections of *Using Org GTD.
There’s an important keymap you’ll want to make the flow of processing the inbox smoother. To limit impact on your emacs configuration, there is a specific keymap you can use. The function you’ll want to bind is org-gtd-choose. I suggest C-c c, as in the following example.
(define-key org-gtd-process-map (kbd "C-c c") #'org-gtd-choose)For other keybindings, do what you need. My bindings use C-c d as a prefix, i.e.:
C-c d corg-gtd-captureC-c d eorg-gtd-engage
etc.
Here are the categories of actions from GTD that we have to be able to handle:
- adding things to the inbox
- processing the inbox
- Engage with your GTD system
- cleaning up / archiving completed work
Other elements of GTD, such as reviews, are currently unimplemented: as the user, you can simply open the files to review things for now.
The inbox is a file called inbox.org in the directory stored in the variable org-gtd-directory. By default this variable is ~~/gtd~.
Org GTD provides one function to capture items: M-x org-gtd-capture. In my setup I have this booked globally as such:
(global-set-key "C-c d c" #'org-gtd-capture)This function overrides org-capture and uses the variable org-gtd-capture-templates to define org-gtd-specific capture templates. By default it comes with two templates, one to just capture a new item, and one to capture an item with a link to the file where you were when you started the capture.
Processing the inbox means taking everything in the inbox, one at a time, and refining/categorizing them so they are instantly useful when you are looking at available next / scheduled actions.
You can start processing the inbox with org-gtd-process-inbox. This will select the inbox buffer and hide everything but the first item in the inbox, then give you control to refine it.
When you are done refining it, call M-x org-gtd-choose (or hit your keybinding for it, see *Recommended key bindings). This will open a transient menu to let you choose how Org GTD should categorize this item.
You have a number of possible choices for each item you process. Subsections will explain how Org GTD handles each one.
- [Q]uick Action
- Quick action. Do it now, then choose this to mark the item as DONΕ and archive it.
- [T]rash
- This is not actionable and it’s not knowledge for later. Choose this to mark the item as CNCL and archive it.
- [P]roject
- This is a multi-step action. I’ll describe how to handle these below.
- [C]alendar
- This is a single item to be done at a given date or time. You’ll be presented with org-mode’s date picker, then it’ll refile the item. You’ll find this in the agenda later.
- [D]elegate
- Let someone else do this. Write the name of the person doing it, and choose a time to check up on that item.
- [S]ingle action
- This is a one-off to be done when possible.
- [A]rchive
- This is knowledge to be stored away.
- [I]ncubate
- no action now, review later
In addition you have [X] for “exit early”, which you can use to stop processing the inbox and restore emacs to its non-inbox-processing state.
After the item-type-specific behavior, you will have the option to add custom decorations to each item, based on how you prefer to think about (filter, find, etc.) the items when you do GTD.
The decorations are tracked in org-gtd-process-item-hooks, a list of functions. By default there is one element in the list, to add tags to the item.
This process will continue, item after item, until you hit x to exit early or until you run out of items to process.
When you choose quick action, you indicate that not much more tracking is necessary. This item is automatically marked as DONE and archived, then Org GTD moves on to the next item.
When you choose trash, the item is automatically marked as CNCL and archived, then Org GTD moves on to the next item.
When you you choose calendar, you will be asked to select a date (and time if you choose to add it), then Org GTD moves on to the next item.
When you choose delegate, you’ll be asked for a name to whom to delegate this to, and a date on which to check in with the person. Org GTD automatically marks this item as “WAIT”, then Org GTD moves on to the next item.
When you choose single action, Org GTD will mark it as a NEXT item, then Org GTD moves on to the next item.
When you choose archive, Org GTD will assume you have done what you needed to do to store this (e.g. put the information in org roam, bbdb, or wherever you will store it), then marks the item as DONE and archives it. Org GTD then moves on to the next item.
Incubating an item is similar to simply scheduling one, though the idea is that you want to be reminded of it much later, and be able to review your incubated items separately. So, all this will really do is make you choose a date at which you want to be reminded of this, then it’ll be refiled under an incubated target.
A “project” in GTD is a finite set of steps after which a given task is complete. In Org GTD, this is defined as a top-level org heading with a set of second-level org headings. When the item you are editing is intended to be a project, create such a headline structure, like so:
* Project heading ** First task ** Second task ** Third task
Then call M-x org-gtd-choose or hit your chosen keybinding, tell Org GTD you chose a project, and move on with your life.
A project is defined as “completed” when all its tasks are marked as DONE. A project is defined as “canceled” when its last task is marked as CNCL.
You can cancel a project by calling org-gtd-agenda-cancel-project from the agenda view, when the point is on the next task of the project.
DO NOTE: it is surprisingly difficult to add a custom note when canceling, so if you want to add a note explaining why you canceled the project, you will have to do so manually.
You can see a list of all NEXT actions, and scheduled actions, with M-x org-gtd-engage . This opens an org-agenda view.
The variable org-gtd-agenda-custom-commands has the settings to define what gets shown in that function.
You can define other functions by adding new custom commands to the above, and defining your own functions like so, where “x” is whatever your defined key is.
(defun my-agenda ()
(with-org-gtd-context
(org-agenda nil "x")))You can call org-gtd-show-all-next to only see NEXT actions, nothing scheduled.
Since Org provides the agenda, it is a convenient base of operations for interacting with things that come up through org-gtd-engage.
Here are the actions available to you:
M-x org-gtd-agenda-cancel-project- When the point is on a project action, this command will cancel the remaining actions in the project.
M-x org-gtd-agenda-delegate- When the point is on an action, this will properly delegate the action to someone else.
M-x org-gtd-agenda-projectify- This is intended to be used on an incubated item that has come up. Behavior in other situations has not been tested. This will properly let you transform an incubated item into a project.
Doing this without user intervention is tricky, as it makes undoing actions more complicated. As such, Org GTD provides a function that will go through the org-gtd-directory files, find the headings that belong to Org GTD (see *Multiple files / refile targets), and archive the finished items.
The variable org-gtd-archive-location hosts a function that returns a string matching the org-archive-location definition. It is a function in order to make the filename entirely dynamic.
The function to archive everything is M-x org-gtd-archive-completed-items.
If you would like to add new refile targets, it’s simple, follow these instructions.
Add a top-level heading in any .org file (including a new one) in org-gtd-directory and make sure it has the following properties drawer.
:PROPERTIES:
:TRIGGER: next-sibling todo!(NEXT)
:ORG_GTD: Projects
:END:
Create a new top-level heading in any .org file (including a new one) and make sure it has an ORG_GTD property as such.
:PROPERTIES:
:ORG_GTD: Action
:END:
The ORG_GTD properties are set as follows, except for Projects (see *New project heading):
- Scheduled actions
ORG_GTD: Calendar- Incubated actions
ORG_GTD: Incubated- Single & Delegated actions
ORG_GTD: Actions
org-edna needs to be configured, see *Required configuration of sub-packages.
Sometimes things break. Use M-x org-gtd-show-stuck-projects to find all projects that don’t have a NEXT item, which is to say, all projects that the package will not surface and help you finish.