Multiple fixes to the duplicate item workflow during clarification:
- Queued duplicates now have the user-entered title in their content (previously kept the original heading)
- Queue processing reuses the existing WIP buffer instead of killing and recreating it, preserving window layout (side windows, queue display)
- Each queued duplicate gets a fresh human-readable org ID instead of reusing the original item’s ID
- Canceling (
org-gtd-clarify-stop) during queue processing now discards only the current item and moves to the next, instead of discarding all remaining items - WIP buffer prefix changed from “Org-GTD” to “Org GTD” for consistency with other buffer names
Fixed a test that used a hardcoded 09:00 timestamp, causing intermittent failures when tests ran before 9 AM.
When org-gtd-mode is enabled and you change a project heading’s TODO state to
CNCL (e.g. via C-c C-t), org-gtd now detects this and offers to cancel all
incomplete child tasks automatically. A confirmation prompt lets you choose
whether to cascade the cancellation.
This complements the existing org-gtd-project-cancel command by catching manual
state changes that bypass the command.
Tasks belonging exclusively to cancelled or done projects no longer appear in active-task views (stuck single actions, stuck calendar/delegated/tickler/habit, engage views, etc.). This is automatic—no configuration needed.
- Tasks with no project (
ORG_GTD_PROJECT_IDSabsent) are unaffected - Multi-project tasks: only hidden when all projects are inactive
- Unresolvable project IDs: task stays visible (fail-open)
Done and cancelled project headings are also excluded from stuck-project and active-project views. The completed-project view is unaffected.
Test ordering could cause intermittent failures when default-directory was left
pointing to /mock:/gtd/ after a test’s mock filesystem was torn down. Fixed by
resetting default-directory to the project root at the start of each test.
Previously, org-gtd-someday only handled single items. It now uses smart dispatch
like org-gtd-tickler:
- On a project heading (
ORG_GTD: Projects): puts the entire project on someday/maybe - On a project task (has
ORG_GTD_PROJECT_IDS): prompts for which project to put on someday - On a single item: uses existing someday/maybe logic
State is preserved just like tickler projects—~PREVIOUS_ORG_GTD~, PREVIOUS_TODO, and
type-specific properties are all saved for later reactivation via org-gtd-reactivate.
For both org-gtd-tickler and org-gtd-someday: when incubating a project, tasks that
belong to multiple projects are now only incubated if the current project is the last
active one for that task. Previously, multi-project tasks were always skipped entirely.
An active project is one with ORG_GTD: Projects that is not done or cancelled. This
means if Task A belongs to Project X (being ticklered) and Project Y (still active),
Task A stays active. But if Project Y is also ticklered/someday/done, Task A gets
incubated along with Project X.
The project graph view now has an S key to move the current project to someday/maybe,
matching the existing I key for tickler/incubate.
Control when the GTD lighter appears in the mode-line with org-gtd-mode-lighter-display:
always(default): Always show (e.g.,GTD[0],GTD[5])never: Never show the lighterwhen-non-zero: Only show when inbox has items (hidesGTD[0])
;; Hide lighter when inbox is empty
(setq org-gtd-mode-lighter-display 'when-non-zero)When capturing multiple inbox items in one session (by adding multiple
level-1 headings in the capture buffer), each heading now gets its own
ORG_GTD_CAPTURED_AT timestamp. All items in the same capture session
share the same timestamp.
org-gtd-set-timestamp now works from both org-mode headings and
org-agenda items. Use it to reschedule Calendar, Delegated, or Tickler
items. The agenda transient (s key) uses this same command.
org-gtd-agenda-truncate-ellipsis controls the string used when truncating
long text in agenda prefixes. Users with fonts where “…” doesn’t display
as one character width can now customize this (e.g., "..." or "⣀").
When clarifying an inbox item, you can now create duplicates to handle items that represent multiple outcomes.
- Press
C-c dto duplicate with rename prompt (enter a new title) - Press
C-c Dto duplicate exactly as-is - Duplicates are queued and processed immediately after the current item
- Queue displays in a side window showing pending duplicates
- When canceling with pending duplicates, choose to discard or save to inbox
- Before exiting Emacs, prompts if any clarify buffers have pending duplicates
- Customize queue window position with
org-gtd-clarify-duplicate-queue-position
Clarify buffers now have proper protection against accidental data loss:
- Closing a clarify buffer with pending duplicates prompts to confirm
- The duplicate queue side window auto-closes when the last clarify buffer is killed
- WIP temp files are cleaned up properly when buffers are killed directly
- Multiple clarify buffers can exist simultaneously without interference
Previously, graph nodes were colored by priority (A/B/C), not by TODO state (NEXT/TODO). This made the graph confusing since colors didn’t indicate which tasks were actionable. Nodes now correctly show NEXT tasks in blue and TODO tasks in orange.
Graph node colors now use the Okabe-Ito palette, which is designed to be distinguishable by people with color vision deficiency. The blue/orange contrast for NEXT/TODO is safe for all common forms of color blindness.
- Node colors: Blue = NEXT (actionable), Orange = TODO (blocked)
- Project heading appears at bottom of graph (represents end state after all tasks complete)
- Tasks flow from top (first) to bottom (last)
Auto-refile now only uses targets in org-gtd-tasks.org, ignoring user’s
org-refile-targets and other org-agenda-files. This fixes issues where items
would be refiled to unexpected locations. (GitHub issues #259, #266)
A heading with property value Actions Projects (e.g., :ORG_GTD_REFILE: Actions Projects)
will be a valid target for both single actions and projects.
When find-file-visit-truename is t and the temp directory is accessed
through a symlink (e.g., macOS where /tmp -> /private/tmp), clarify buffers
were not being killed after organizing items. The fix uses find-buffer-visiting
instead of get-file-buffer to properly handle symlink path resolution.
The inbox file is now always excluded from refile targets, even if it
accidentally contains headings with ORG_GTD_REFILE properties. This prevents
items from being refiled back to inbox during processing and resolves issues
where users saw inbox.org headings in their refile target list.
When entering a calendar item with a time range like 11:00-12:00, the duration
is now correctly preserved in the ORG_GTD_TIMESTAMP property. Previously the
end time was being lost. Now uses org-mode’s org-end-time-was-given variable
to properly capture time ranges, matching how org-timestamp (C-c .) works.
org-gtd-show-project-graph now works in more contexts:
- On task headings: shows the graph for the project the task belongs to
- On tasks in multiple projects: prompts to select which project
- From org-agenda: shows the graph for the task at point
- Shows helpful messages when task is not in a project or heading is not a GTD item
The graph visualization modules (org-gtd-graph-mode, org-gtd-dag-draw, etc.)
are no longer loaded when org-gtd initializes. They load on first use of
org-gtd-show-project-graph or related commands, reducing startup time by ~17ms.
You can now click on nodes in the project graph view (both ASCII and SVG modes)
to select them. This updates the details panel to show the clicked node’s
information. Handles Emacs image-scaling-factor automatically.
When using (prefix . (area-of-focus)) in the view DSL, project tasks without
an explicit CATEGORY property now correctly display the project heading’s
CATEGORY instead of the file-name based default. The resolver now traverses
to the project via ORG_GTD_PROJECT_IDS when no explicit CATEGORY is set.
When users had (nil :maxlevel . N) in their org-refile-targets configuration
(meaning “current buffer”), the WIP clarify buffer would be offered as a refile
target. This caused “Cannot refile to position inside the tree or region” errors
because org-refile cannot refile a heading to itself. The refile verify function
now excludes files in the WIP temp directory.
The default capture templates included %U which added an inactive timestamp
to the body of captured items. This was redundant since the capture timestamp
is already stored in the ORG_GTD_CAPTURED_AT property. The templates now
only include the property.
Properties containing org links (e.g., EBDB links like [[ebdb:uuid][John Doe]])
now display just the link description (“John Doe”) instead of the raw link syntax.
This improves readability when using linked contacts for DELEGATED_TO or similar
properties.
When removing a task from a project graph (`t r`), the selected node now updates to a nearby task (predecessor, successor, or project) instead of leaving a stale reference to the removed task.
The graph transients (add/modify blockers/successors) now use a custom EIEIO prefix class to store edge selection state on the transient object itself, rather than using a global variable. This fixes edge selection state being lost when switching between transient buffers.
The upgrade path was missing the ORG_GTD_PROJECT property (project name cache)
on project tasks. This property is used for display purposes in agenda views.
New projects created in v4 had this property, but migrated v3 projects did not.
org-gtd no longer manages org-agenda-files for you. Add your GTD directory to your config:
(setq org-agenda-files (list org-gtd-directory))Without this, your GTD items will not appear in agenda views.
org-gtd now requires Emacs 28.1 or higher due to transient.el dependency updating its minimum requirement.
Users on Emacs 27.2 must remain on org-gtd 3.x.
To check your Emacs version: M-x emacs-version
org-gtd-clarify-mode is now a major mode derived from org-mode (was a minor mode).
The internal org-gtd-wip-mode has been removed. This is an internal refactoring -
user-facing behavior is unchanged.
The keymap has been renamed from org-gtd-clarify-map to org-gtd-clarify-mode-map
(following Emacs naming conventions). The old name still works but is obsolete:
;; Old (still works, but deprecated):
(define-key org-gtd-clarify-map (kbd "C-c c") 'org-gtd-organize)
;; New (recommended):
(define-key org-gtd-clarify-mode-map (kbd "C-c c") 'org-gtd-organize)- Emacs 27.2 compatibility code and declarations
- Workarounds for pre-28.1 behavior
- Ancient Emacs 25.0 version checks
- Performance: Using 28.1’s faster string-search for literal matching
- Code quality: Lexical binding throughout for native compilation support
- Documentation: Enhanced command docstrings for better discoverability
- Testing: CI now validates on Emacs 28.2, 29.1, and 30.1
- Native compilation support (10-20% performance improvement on large datasets)
- Performance documentation in README
- Replaced string-match + regexp-quote with string-search where applicable
- Removed all (declare (modes …)) compatibility declarations
- CI matrix updated to test on 28.2, 29.1, 30.1
- use
with-temp-messageto hide things we don’t care about.
- Now uses org-refile like it was meant to be used
- Now works for projects outside
org-gtd-directory.
Make GTD truly a part of your emacs experience.
I can’t find 27.1 anywhere.
org mode’s habits now have a place here
- Habits have their place
- What used to be called “archive” is now called “knowledge”
- Modify project is now “Add to project”
- The package domain now is a better match for the domain language of GTD.
- SCHEDULED and DEADLINE are intended to be used for things that have to start and things that have to end, respectively. V2 abused them, v3 is more respectful of how org-mode wants to work.
- They can be displayed while clarifying.
- There’s an optional organize-hook for areas of focus
- There’s an agenda view for areas of focus
We now respect that emacs is a GUI and that the user must have complete control at all times. The flow also provides control to the user PRIOR to the user choosing the way to categorize this item.
Fits the four-letter pattern better. You’ll need to do a search-and-replace in the files managed by org-gtd, replacing “CANCELED” by “CNCL”.
The code now looks for top-level headings with a property called ORG_GTD with possible values: Action, Incubated, Projects, Scheduled, Delegated.
[2021-10-06 Wed]
The system would effectively skip over headings. Had to disable org-edna-mode while Ι am changing the states to CANCELED.
[2021-10-03 Sun]
There’s a new public function, (org-gtd-inbox-path), you should use this in your configuration instead of (org-gtd--path org-gtd-inbox-file-basename).
- projects can be canceled by calling
(org-gtd-cancel-project)on the top headline of the project - projects can be canceled by calling
(org-gtd-agenda-cancel-project)when the point is on the next task of the project on the agenda view.
(org-gtd-archive-complete-projects) now archives both completed and canceled projects.
[2021-09-19 Sun]
the readme was a cluttered mess, I’ve broken it down into a lot of subsections. I hope it will be easier to manage now.
Based on an idea in https://github.com/Trevoke/org-gtd.el/discussions/54
There’s now an available variable that you can use to extend and customize the behavior of item processing. If you come up with cool ideas, share them!
I dunno why this tag existed but we’re skipping this I guess.
[2020-08-20 Thu]
While processing the inbox, it was impossible to refile to the incubate file properly. This release fixes that bug.
To note:
If you haven’t yet, make sure you go to the incubate file and set up some categories for yourself, e.g. `* To Read`, `* To Eat`, etc. org-gtd currently handles up to two headline levels, so you could do `* To Read` and `** Horror` if you wanted