trevoke / org-gtd.el

A package for using GTD with org-mode

NOTICE

This is org-gtd 3.0.0.

Check documentation in doc/ (and the info manual within emacs itself) if you’re upgrading. Please report all defects as Github issues.

Use existing tags if you’d rather stick to a pre-3.0 version.

Sponsorship

I’ve put many hours of reading, research, and coding, to put this together. If it delivers value to you, helps you manage your life, please consider sponsoring (Github sponsors or Patreon) and allowing me to continue putting work into this package and other projects.

Org GTD

This package tries to replicate as closely as possible the GTD workflow. This package assumes familiarity with GTD.

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.

For a comprehensive instruction manual, see the documentation:

• Either the info file (within emacs, C-h i m org gtd RET)
• or in the doc/ directory of the repository, there is a .org file you can peruse.

The documentation also details how to upgrade from one version to another.

Whirlwind tour of the package

What follows is an incomplete description of the package. It is useful if you just want to take it for a test run. Read the full documentation for the full set of features and customizability.

GTD Meta

Modes:

org-gtd-mode

If you want to be able to refresh the org-agenda views and have all the org-gtd files included in your org-agenda-files, you’ll need this to be enabled.

Customizable variables:

org-gtd-directory

Directory where org-gtd will look for its files

org-gtd-areas-of-focus

List of strings representing Horizon 3. See Steps 4 and 6 for further details.

GTD Step 1/6 : Capture

Functions:

org-gtd-capture

A wrapper around org-capture. Use it to capture items into the GTD inbox. Will create the inbox file if it does not exist.

Customizable variables:

org-gtd-capture-templates

Defines behavior for org-gtd-capture.

GTD Step 2/6 : Process

Functions:

org-gtd-process-inbox

Start a loop around step 3 (Clarify) for every item in the inbox.

GTD Step 3/6 : Clarify

Functions:

org-gtd-clarify-item

Call this from any org heading to clarify this item as a one-off and organize it into org-gtd.

org-gtd-clarify-agenda-item

Call this from any item in the agenda to clarify this item and organize it into org-gtd.

org-gtd-clarify-switch-to-buffer

Call this to switch back to any existing clarify buffer. Use this instead of switching back through the normal flow, as this manages some state.

Keymaps:

org-gtd-clarify-map

Sparse keymap for minor mode used in the clarify buffer.

GTD Step 4/6 : Organize

Functions:

org-gtd-organize

Pop up a menu asking how to organize (e.g. single action, appointment, etc.) the item at point. Great function to bind on org-gtd-clarify-map.

Hooks:

org-gtd-organize-hooks

Series of functions that get called to decorate each item (e.g. org tags, org effort, etc.). Add org-gtd-set-area-of-focus to this one to set areas of focus on each item.

GTD Step 5/6 : Engage daily

Functions:

org-gtd-engage

Your daily view.

org-gtd-engage-grouped-by-context

All NEXT actions, grouped by tags beginning with @. This may not work if you remove org-set-tags-command from org-gtd-organize-hooks.

GTD Step 6/6 : Review

Functions:

org-gtd-oops

Show all the missed appointments. Oops!

org-gtd-review-area-of-focus

Show an agenda view designed for one of your areas of focus.

org-gtd-review-stuck-*

The * here is any of the action types; you can find any of the ones that have fallen through the cracks.

Directory tree

dev

used as a jail environment. Copy somewhere else and spin up with $ HOME="dev/" emacs.

doc

where the documentation lives

test

where the tests are

Community

If you want help, you can open an issue right on Github.

You’re also welcome to join my discord server for all conversations related to org-gtd in particular and GTD in general. Many of the ideas for org-gtd came out of my reading the GTD book, and then reading some sections multiple times, but I am in no way an expert. Defining the GTD domain, which is to say, getting to clear nomenclature with clear actions, is still a work in progress.

Animated demos of org-gtd

Projects

org-gtd.el's Issues

Org-gtd should warn the user the right format for a project

Suppose you have a single heading

* My single item project

If the user is in the clarify part (org-gtd-choose) and select Project, org-gtd triggers this error

Debugger entered--Lisp error: (wrong-number-of-arguments (first-entry . rest-entries) 0)
  signal(wrong-number-of-arguments ((first-entry . rest-entries) 0))
  org-gtd-projects--nextify()
  org-gtd--project()
  funcall-interactively(org-gtd--project)
  call-interactively(org-gtd--project nil nil)
  command-execute(org-gtd--project)

The problem is that expect format is

* My correct formated project
* * First task

org-gtd should warn the user when the format is incorrect.

Best.

Skipping entries when processing inbox

How do I skip an element when processing the inbox?

Find good org-agenda buffers w/ org-agenda-custom-commands and the GTD book

https://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.html

"archive completed projects" should also archive canceled projects

Update screenshot in readme of processing menu

Hello,

First of all, this package looks great, i'm definitely going to give it a spin.

The screenshot of the processing menu in the README (e.g. when processing an inbox item what to do with it) seems outdated. I'm using org-gtd from the latest master branch and it looks like this:

Which isn't the same as shown in the readme:

Perhaps an update to the README is needed? Or am I missing something?

Thank you in advance.

Add the option in org-gtd-choose of "Refile to X project"

When we are in the process of capturing and clarifying items, sometimes a new item belongs to an already processed project.

Suppose you have in your project tree

* Projects
** [0/1] Learn how to bike
*** NEXT Practice 1 hour 

Later you recall you don't have a bike, then you capture in the inbox

* Buy a bike

In the clarify part, you get stuck because you need to cancel the whole process and refile manually the item to the correct project.

Please let me know if I was clear enough with the problem.

Best.

should be possible to cancel a project (mark all unfinished tasks canceled)

Projects: Conflict between user settings to process an item and package settings

I'm running into an issue with Projects.

In my config, I've added this line:
(setq org-gtd-process-item-hooks '(org-priority org-set-effort org-set-tags-command))

Instead of the A priority symbol [#A] next to the task in the project:
[#A] Some project's headline > Task for that project

My output is:

In the agenda view:

In the file under the Projects headline:

I believe the package is adding [/] to tell me how many tasks are left however that is interfering with my priority settings. Can you assist me with this?

Thanks a ton for this package. It really keeps me organized and less stressed.

How do I could return to the popup options if I changed my mind about how to process an item?

For example,

I have this item in my inbox.org

* One great item

I process the inbox and choose "quick action" and a dedicated buffer appears to clarify the item. While I'm clarifying this, I decided that maybe the item is a project or belongs to an existing project.

How do I could return to the previous state and select for example "project" instead of "quick action"?

Thanks again.

Activate incubated project (or transform incubated item into active project)

Any plan for 2021

Hi,

I find this package very useful but is there a plan for a development in 2021 ?
Just curiosity.
;-)

`org-gtd-archive-complete-projects` does not archive a project ending in a `CANCELED` todo

Running (org-gtd-archive-complete-projects) does not archive a projecty ending with a CANCELED todo.

Can't get process to work

HI, while trying to use process I don't get any feedback and nothing happens to the item (does not get a TODO added, etc).
I'm not sure where to start, after selecting an option it simply puts me into the inbox on the first item. I love the idea and work here, thank for any input or suggestions!!

Fwiw I have tried this with Spacemacs and Doom emacs.

can't categorize an item as project

keep hitting

org-gtd--nextify: Wrong number of arguments: (first-entry . rest-entries), 0

This doesn't happen for delegate

org-gtd--refile-targets - function or variable?

Should org-gtd--refile-targets be a variable rather than a function?

Popup interface inscreenshot removed?

When I decide to process my inbox I don't see the multiple choice popup as per ogpi-1.png. I only see tho options in the minibuffer. Is this just a case of the README being out of date.

Trying to process a item gives (wrong-number-of-arguments (first-entry . rest-entries) 0)

If I try to process an item to a new project and after setting the tags it throws me this error (I used emacs --debug-init) and can't continue and the screen stays blocked.

Debugger entered--Lisp error: (wrong-number-of-arguments (first-entry . rest-entries) 0)
  signal(wrong-number-of-arguments ((first-entry . rest-entries) 0))
  org-gtd--nextify()
  org-gtd--project()
  org-gtd--process-inbox-element()
  #f(compiled-function () #<bytecode 0x3a8bc45>)()
  org-scan-tags(#f(compiled-function () #<bytecode 0x3a8bc45>) t nil nil)
  org-map-entries(#f(compiled-function () #<bytecode 0x3a8bc45>))
  org-gtd-process-inbox()
  funcall-interactively(org-gtd-process-inbox)
  call-interactively(org-gtd-process-inbox nil nil)
  command-execute(org-gtd-process-inbox)

Thanks for the help.

org-gtd--project: Wrong number of arguments: (first-entry . rest-entries), 0

It could be because I use emacs 28.

[Question] Add item to existing project and nested projects

Is there a way to add an inbox item to an existing project as the next step after all added entries? Also can there be projects inside a project?

Discussion about implementation

Hi! Great repo, this looks very interesting to me!

I couldn't work out from the README how everything fits together in this package, what the philosophy is. I also tried browsing the source code but that got me even more confused.

• what files are you creating, with what headlines and goals?
• what todo states are being used?
• what tags/properties are being used?
• what does the capture process look like?
• any thoughts on where triggerlists come into the picture?

I'm hoping to understand these issues better before I want to load the package and possibly migrate my current set-up (see my emacs config).

These comments are intended to be helpful, even if they may come off a bit whiney! I'm potentially interested in using the package and likely contributing many bug reports/feature requests if I do.

Clean up code so that auto-loading works

This might require breaking up with-org-gtd-context into multiple macros.

Invalid function with-org-gtd-context

Today I upgraded to this commit (abf43ae) and every time I execute org-gtd-engage I get this message

Debugger entered--Lisp error: (invalid-function with-org-gtd-context)
  with-org-gtd-context(nil)
  org-gtd-engage()
  funcall-interactively(org-gtd-engage)
  call-interactively(org-gtd-engage nil nil)
  command-execute(org-gtd-engage)

Also, processing the inbox seems broken because it does not present the narrowed tree in the inbox file nor the menus to classify the tasks.
Skip this part, sorry. I made a silly mistake with my inbox.org. However, the org-gtd-engage error persist.

Review emacsconf2020 talk, maybe add to readme

https://emacsconf.org/2020/talks/11/

Since I'm doing v2.0, I need to check and see how much of this is really outdated. Most of 2.0 should be important backend changes for flexibility, but .. one never knows. Maybe I need to make a new talk.

Add TODO keyword to scheduled items?

Hello!

Is it possible to have org-gtd automatically add a NEXT status to calendar items when the appropriate date arrives? Or is that something that should be done manually? Or is the calendar action not necessarily for tasks?

Thanks!

How did you include org-roam in the "archive" option?

Watching your talk in EmacsConf 2020 https://emacsconf.org/2020/talks/11/ (great talk by the way), you used org-roam to archive the items that you want to transform later in a note (inside the org-roam-directory I guess).

I was trying to replicate this with the current version of org-gtd (4716603) and I only get that the item get archived into inbox.org_archive.

Could you please share the config you used or point me about something that I haven't done to replicate this behavior with the "archive" option?

Thanks.

Error (use-package): org-agenda/:config: Symbol’s function definition is void: org-agenda-custom-commands

Should I adjust this line?
The line (org-agenda-custom-commands '(("g" "Scheduled today and all NEXT items" ((agenda "" ((org-agenda-span 1))) (todo "NEXT"))))) gives me the error
Error (use-package): org-agenda/:config: Symbol’s function definition is void: org-agenda-custom-commands.
I erased any customization from the easy customization options and there are no other org-agenda-custom-command lines in my init file. I am using the standard customization from the README on Windows.

org-gtd-show-stuck-projects surfaces completed projects

The function org-gtd-show-stuck-projects is supposed to surface projects without NEXT items. However, it also surfaces projects that have no TODO items. This means that completed projects will always show up in that list. The only workarounds I see involve manual processes, which seems contrary to the point of org-gtd.

Incubate leaves item in inbox

When processing the inbox, Incubate does not move the item to an incubate.org, so it has to be reprocessed every time the inbox is handled.

[Question] did you see the "David Allen best software for GTD" templates?

David Allen talked about his ideal GTD app some time ago on the GTD conf 2019: https://www.youtube.com/watch?v=2c_RuXVujho

His old designs are available on https://gettingthingsdone.com/2019/07/david-allen-on-the-best-software-for-gtd/

There are quite some nice tidbits in there that would be great to implement in some way or other. For instance:

• get an idea of how many items are in your inbox at any time (statusbar indicator that grows when more items are added?)

and of course many more. Do you have any thoughts on this? Or a roadmap of how you'd like everything to work?

hitting error using org-gtd

Hi, I'm a newbie when it comes to elisp. Here is my complete init.el. Do you know why I'm seeing this error?

I'm getting

Error (use-package): Failed to parse package org-agenda: use-package: :after wants a symbol, or nested list of symbols
Error (use-package): Failed to parse package org-agenda: use-package: :after wants a symbol, or nested list of symbols
Error (use-package): Failed to parse package org-agenda: use-package: :after wants a symbol, or nested list of symbols

(require 'package)

(setq package-archives '(("melpa" . "https://melpa.org/packages/")
			 ("melpa-stable" . "https://stable.melpa.org/")
                         ("org" . "https://orgmode.org/elpa/")
                         ("elpa" . "https://elpa.gnu.org/packages/")))

(package-initialize)
(unless package-archive-contents
 (package-refresh-contents))

;; Initialize use-package on non-Linux platforms
(unless (package-installed-p 'use-package)
   (package-install 'use-package))

(require 'use-package)
(setq use-package-always-ensure t)

(use-package org-gtd
  :after org
  :pin melpa-stable ;; or :pin melpa as you prefer
  :demand t ;; without this, the package won't be loaded, so org-agenda won't be configured
  :custom
  ;; where org-gtd will put its files. This value is also the default one.
  (org-gtd-directory "~/gtd/")
  ;; package: https://github.com/Malabarba/org-agenda-property
  ;; this is so you can see who an item was delegated to in the agenda
  (org-agenda-property-list '("DELEGATED_TO"))
  ;; I think this makes the agenda easier to read
  (org-agenda-property-position 'next-line)
  ;; package: https://www.nongnu.org/org-edna-el/
  ;; org-edna is used to make sure that when a project task gets DONE,
  ;; the next TODO is automatically changed to NEXT.
  (org-edna-use-inheritance t)
  :config
  (org-edna-load)
  :bind
  (("C-c d c" . org-gtd-capture) ;; add item to inbox
  ("C-c d a" . org-agenda-list) ;; see what's on your plate today
  ("C-c d p" . org-gtd-process-inbox) ;; process entire inbox
  ("C-c d n" . org-gtd-show-all-next) ;; see all NEXT items
  ("C-c d s" . org-gtd-show-stuck-projects)) ;; see projects that don't have a NEXT item
  :init
  (bind-key "C-c c" 'org-gtd-clarify-finalize)) ;; the keybinding to hit when you're done editing an item in the processing phase
(require 'org-gtd)
(use-package org-agenda
  :ensure nil ;; this is how you tell use-package to manage a sub-package
  :after org-gtd ;; because we need to add the org-gtd directory to the agenda files
  ;; use as-is if you don't have an existing org-agenda setup
  ;; otherwise push the directory to the existing list
  (org-agenda-files `(,org-gtd-directory))
  ;; a useful view to see what can be accomplished today
  (org-agenda-custom-commands '(("g" "Scheduled today and all NEXT items" ((agenda "" ((org-agenda-span 1))) (todo "NEXT"))))))

(use-package org-capture
  :ensure nil
  ;; note that org-gtd has to be loaded before this
  :after org-gtd
  :config
  ;; use as-is if you don't have an existing set of org-capture templates
  ;; otherwise add to existing setup
  ;; you can of course change the letters, too
  (setq org-capture-templates `(("i" "Inbox"
                                 entry (file ,(org-gtd--path org-gtd-inbox-file-basename))
                                 "* %?\n%U\n\n  %i"
                                 :kill-buffer t)
                                ("l" "Todo with link"
                                 entry (file ,(org-gtd--path org-gtd-inbox-file-basename))
                                 "* %?\n%U\n\n  %i\n  %a"
                                 :kill-buffer t))))

`org-gtd-process-inbox` skipping every other item

Hello again!

I noticed that, without changing my configuration (and even testing older configurations of mine, just to double check), running org-gtd-process-inbox is starting to skip every other inbox item and thus not processing everything in inbox.org.

I noticed in the CHANGELOG that you maybe have noticed a similar issue and said something about disabling org-edna-mode? Do you have a recommended configuration for the bug?

Thanks!

Graceful exit of inbox processing

How does one gracefully exit inbox processing?

Nothing added to agenda

Hi,

Thanks for the package. When I tried the packages, it seems everything works fine, but after processed my inbox, but nothing shows up on my agenda view, also when I try Ctrl-c d n, nothing shows up also. I am using doom emacs on macOS and I am using the configuration from the end of document of this package. Do you have any idea? Thank you.

More complex/flexible task dependencies

The request came up once or twice to do more complex task dependency than the linear setup currently in place.

Since I'm using org-edna for this linear setup, one option to extend upon this would be https://github.com/toshism/org-linker-edna

It references this : https://karl-voit.at/2020/08/14/project-mgt-draft/ as an example workflow with advanced dependency usage.

[Question] Possible to use Projects per file?

Hello,
as far as i understand the documentation, i find nothing about using multiple files for different projects.
E.g.: Usually and currently with org i use one file per Projects or private things.
One file for my things, one for my wife, one per project.

Is this possible?

Regards
Poul

Determine which in-buffer settings can be brought into with-org-gtd-context

https://orgmode.org/manual/In_002dbuffer-Settings.html

org-gtd--nextify: Wrong number of arguments: nil, 0

Hi,

Your project catched my attention a while ago and now that it's in melpa i decided to give it a try. I've been implementing GTD in emacs in a more manual way.

I'm trying to set an inbox entry as a project with p, so I press p, then C-c x and it asks for tags. I write a couple for the project and after hitting RET I'm getting the following error:

org-gtd--nextify: Wrong number of arguments: nil, 0

Not sure if I'm doing something wrong, or maybe something in my config. ¿Any idea of why?

Thanks for the interesting project.

Consider dropping org-agenda-property dependency

In an effort to reduce the number of dependencies consider dropping org-agenda-property. Instead, suggest users use a tag instead. This is what I do and find it works well. I also write tags in lowercase to differentiate them from org-todo-keywords which I find makes interpreting org-agenda-custom-commands.

Feature: modeline widget with "number of items in inbox"

Unsure whether just the number is fine, or whether it could be a visual representation, e.g.

->[12], ->[86]

or

->[] ->[[]], ->[[[]]]

Idea from #21

Documentation missing

The documentation of the ways of working with org-gtd is missing, so I can only get help from these issues.

Add sample configs for doom.el

e.g.

;;; Org-gtd
(use-package! org-gtd
  :after org
  :config
  (org-edna-mode)
  (setq org-gtd-directory "~/documents/org/gtd")
  (setq org-gtd-default-file-name "actionable")
  (setq org-edna-use-inheritance t)
  (map!
   :leader
   (:prefix-map ("d" . "org-gtd")
    :desc "Capture"        "c"  #'org-gtd-capture
    :desc "Engage"         "e"  #'org-gtd-engage
    :desc "Process inbox"  "p"  #'org-gtd-process-inbox
    :desc "Show all next"  "n"  #'org-gtd-show-all-next
    :desc "Stuck projects" "s"  #'org-gtd-show-stuck-projects))

  (map!
   :map org-gtd-process-map
   :desc "Choose"         "C-c C-c" #'org-gtd-choose))

add optional buffer showing horizons during item processing

Should some defconst be changed to defcustom?

To avoid being too opinionated. I'm thinking of the various files etc.

When i try to move items to "project" nothing happens

While processing the items in the inbox.org file, if select "p" for shelving it under project, nothing happens. The item still exists in the inbox.org. The items have not moved to "Projects" heading in actionable.org file.
How to properly create projects and add items to it ?

Question: How does incubate work?

Hi again,

I'm trying to process a task by incubating it. I go to process (C-c d p), I press i to incubate it. It goes to the capture buffer. I press C-c cand it asks for tags. I introduce a couple and it prompts for a date in the calendar, then it shows me a refile with the headers of the inbox, I think.

I see there is a incubate.org file. I tried adding some headers there but it stills shows the headers of inbox.org. Maybe, I'm doing something wrong. The README only indicates that incubations allow for later reviewing.

Thanks again.

Github actions builds are failing. Not sure why. Help!

See 13f04f4 for example (check out the red X next to the SHA)

[Bug]: invalid-function with-org-gtd-refile

Using the recommended settings under the 2.0.0 branch, I attempted processing an item using any of the GTD actions. For example, when it refiled the item as a single action, it threw me this error after applying tags.

Debugger entered--Lisp error: (invalid-function with-org-gtd-refile)
  with-org-gtd-refile("actions" nil "Refile to \"inbox.org\" in file /home/dylan/documents/gtd/inbox.org: done")
  org-gtd-refile--do("actions")
  org-gtd--single-action()
  funcall-interactively(org-gtd--single-action)
  command-execute(org-gtd--single-action)

It then refiled itself to inbox with the decorations applied and went to the next item. I have tested this on emacs 27.2.1 and 28.0.90.

Do you have any ideas for solving this? Thanks!

org-cature templates return nil error

hello,
i'm interested in your favorite program, but unfortunately there seems to be an error with the templates.
i copy and paste the lines from the documentation, but after pressing C-c d c i or l there is an file expansion error inside the org-templates.
my org-gtd-directory is set,
there is an inbox.org file inside.
i think the synthax is anyhow not fully correct.
i use emacs 26.3 on linux kubuntu with org 9.3.
any clues?

Regards
Poul

Unable to process inbox

Hi!
I've just stumbled on GTD and trying to use this package while gathering my knowledge through the book.

One thing I stumbled upon when trying out this package is that when I do org-gtd-clarify-finalize, I got the error State ‘NEXT’ not valid in this file.
I think it is because I don't have NEXT in my org-todo-keywords.

I can add NEXT to my org-todo-keywords, but I think we can prevent this from happening by adding #+TODO: on the inbox.org file.

when I tried "incubate", it complains `user-error: No refile targets`

I thought this should go to incubate.org?