org-depend.el demonstrates a mechanism for creating TODO dependencies. Note that Org-mode does already have built-in local dependencies which are simpler and cover most of what one usually wants to do. However, the built-in implementation covers only the following two concepts:
org-depend.el was originally a proof-of-concept implementation of
TODO dependencies, using two special hooks,
=org-trigger-hook=. It remains in the distribution as an example on
how more complex dependencies between entries can be implemented. In
particular it shows how to implement the following:
OPTIONS should be a comma separated string without spaces, and can contain following options:
from-topthe candidate list is all of the siblings in the
from-bottomcandidate list are all siblings from bottom up
from-currentcandidate list are all siblings from current item
no-wrapcandidate list are siblings from current one down
todo-onlyOnly consider siblings that have a todo keyword
todo-and-done-onlySame as above but also include done items.
priority-upsort by highest priority
priority-downsort by lowest priority
effort-upsort by highest effort
effort-downsort by lowest effort
There is also customizable variable
that contains default options if none are specified. Its default
value is =from-current,todo-only,priority-up
4) If the TRIGGER property contains any other words like
XYZ(KEYWORD), these are treated as entry IDs with keywords.
That means, Org-mode will search for an entry with the ID property
XYZ and switch that entry to KEYWORD as well.
1) If an entry contains a BLOCKER property that contains the word
previous-sibling, the sibling above the current entry is
checked when you try to mark it DONE. If it is still in a TODO
state, the current state change is blocked.
2) If the BLOCKER property contains any other words, these are treated as entry IDs. That means, Org-mode will search for an entry with the ID property exactly equal to this word. If any of these entries is not yet marked DONE, the current state change will be blocked.
3) Whenever a state change is blocked, an org-mark is pushed, so that
you can find the offending entry with
When trying this example, make sure that the settings for TODO keywords have been activated, i.e. include the following line and press C-c C-c on the line before working with the example:
#+TYP_TODO: TODO NEXT | DONE
OK, here is the example.
,* TODO Win a million in Las Vegas :PROPERTIES: :ID: I-cannot-do-it-without-money :END:
The "third" TODO (see above) cannot become a TODO without this money.
,* Do this by doing a chain of TODOs ,** NEXT This is the first in this chain :PROPERTIES: :TRIGGER: chain-siblings(NEXT) :END:
,** This is the second in this chain
,** This is the third in this chain :PROPERTIES: :BLOCKER: I-cannot-do-it-without-money :END:
,** This is the forth in this chain :PROPERTIES: :TRIGGER: XYZ-is-my-id(TODO) :END:
When this is DONE, we will also trigger entry XYZ-is-my-id
,** This is the fifth in this chain
,* Start writing report :PROPERTIES: :ID: XYZ-is-my-id :END:
In advanced example we will add a hook to automatically insert =chain-find-next= TRIGGER when entry is changed to NEXT and automatically remove it otherwise.
First evaluate the following lisp code:
(defun mm/org-insert-trigger () "Automatically insert chain-find-next trigger when entry becomes NEXT" (cond ((equal org-state "NEXT") (unless org-depend-doing-chain-find-next (org-set-property "TRIGGER" "chain-find-next(NEXT,from-current,priority-up,effort-down)"))) ((not (member org-state org-done-keywords)) (org-delete-property "TRIGGER"))))
(add-hook 'org-after-todo-state-change-hook 'mm/org-insert-trigger)
Now in the following org file, try changing item TODO state to NEXT. You should see properties drawer appear with the TRIGGER property inside.
Try marking the NEXT item DONE. The next item should automatically become NEXT.
Change priority of one of the items to
[#A], then mark the NEXT item
DONE. The highest priority item will automatically become NEXT.
,* Auto-NEXT example ,** TODO Make me NEXT, then mark me DONE ,** TODO Second item ,** TODO Third item ,** Plain item ,** TODO Change my priority
An advanced workflow with dependencies is auto-generated from a
template snippet using the
Some of those things were demonstrated in an Emacs Chat by Sacha Chua with Karl Voit.
The blog article further discusses some ideas on how to improve the
=org-depend= functionality with an ID picker, a mnemonic ID
auto-generator, a workflow assistent, advanced
TRIGGER commands to
add scheduled dates, and inheritance of todo-cancelation.