#+TITLE: Org GTD - Get Things Done with Emacs

* First Contact

** The Problem

You know GTD. You want to practice it in Emacs.

org-mode is incredibly powerful... and incredibly complex.

Do you really need to master org-agenda's custom views, org-capture templates, and org-mode's keyword workflows just to implement David Allen's methodology?

** The Solution

*org-gtd treats Emacs and org-mode as infrastructure.*

You focus on GTD. org-gtd handles the org-mode complexity.

- Turnkey GTD workflow matching the book
- Automatic project dependency management
- Built-in views for capture/clarify/organize/engage/review
- Hooks for your customizations (effort, tags, integrations)
- Extensible for email, code tools, external sources

** Who This Is For

- You practice GTD (or want to start)
- You use Emacs (beginner to expert - we'll explain what you need)
- You want to DO work, not configure systems

* Quick Start (5 Minutes)

Get org-gtd working end-to-end: capture an item, organize it, and see it in your daily view.

** Prerequisites

- Emacs 28.1 or higher
- org-mode (included with Emacs)

** Installation

Install from MELPA:

#+begin_src emacs-lisp
;; Manually
M-x package-install RET org-gtd RET
#+end_src

** Complete Configuration (use-package)

If you use ~use-package~, copy this entire block into your init file - it includes installation, configuration, and keybindings:

#+begin_src emacs-lisp
(use-package org-gtd
  :ensure t
  :after org
  :demand t
  :init
  ;; Suppress upgrade warnings (must be set before package loads)
  (setq org-gtd-update-ack "4.0.0")
  ;; Where org-gtd will keep its files (defaults to ~/gtd/)
  ;; (setq org-gtd-directory "~/my-gtd/")

  :custom
  ;; Configure TODO keyword states (options like "TODO(t)" or "DONE(d!)" are fine)
  (org-todo-keywords '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL")))

  ;; Map GTD semantic states to your keywords
  (org-gtd-keyword-mapping '((todo . "TODO")
                             (next . "NEXT")
                             (wait . "WAIT")
                             (canceled . "CNCL")))

  :config
  ;; REQUIRED: Enable org-edna for project dependencies
  (org-edna-mode 1)

  ;; Add org-gtd files to your agenda (must be in :config so org-gtd-directory is defined).
  ;; A directory entry is valid: org-mode scans every .org file inside it.
  ;; Already using org-agenda-files? Don't overwrite it - merge instead, e.g.:
  ;;   (add-to-list 'org-agenda-files org-gtd-directory)
  (setq org-agenda-files (list org-gtd-directory))

  :bind
  ;; Global keybindings (work anywhere in Emacs)
  (("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-reflect-stuck-projects)

   ;; Keybinding for organizing items (only works in clarify buffers)
   :map org-gtd-clarify-mode-map
   ("C-c c" . org-gtd-organize)

   ;; Quick actions on tasks in agenda views (optional but recommended)
   :map org-agenda-mode-map
   ("C-c ." . org-gtd-agenda-transient)))
#+end_src

*Existing org-mode users*: If you already have ~org-todo-keywords~ configured, add a separate sequence for GTD keywords rather than mixing them into existing sequences. See the full documentation for details.

*Existing org-agenda-files users*: The snippets above use ~(setq org-agenda-files (list org-gtd-directory))~, which *replaces* any agenda files you already have. If you have an existing ~org-agenda-files~, merge instead, e.g. ~(add-to-list 'org-agenda-files org-gtd-directory)~. Note that ~org-gtd-directory~ is a directory, and listing a directory is valid: org-mode scans every ~.org~ file inside it, so any new GTD file is picked up automatically (but so is any unrelated ~.org~ file you drop there).

** Alternative: Manual Configuration

If you don't use ~use-package~, copy this into your init file and restart Emacs:

#+begin_src emacs-lisp
;; Suppress upgrade warnings (set BEFORE org-gtd loads)
(setq org-gtd-update-ack "4.0.0")

;; Configure org-mode TODO keywords
;; All GTD keywords must be in the same sequence
;; Standard options like "TODO(t)" or "DONE(d!)" are fine - org-gtd ignores them
(setq org-todo-keywords
      '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL")))

;; Map GTD semantic states to your keywords
(setq org-gtd-keyword-mapping
      '((todo . "TODO")      ; tasks not ready to act on
        (next . "NEXT")      ; tasks ready to act on immediately
        (wait . "WAIT")      ; tasks blocked or delegated
        (canceled . "CNCL"))) ; tasks that won't be completed

;; Optional: Set GTD directory (defaults to ~/gtd/)
;; (setq org-gtd-directory "~/gtd/")

;; Add org-gtd files to your agenda.
;; A directory entry is valid: org-mode scans every .org file inside it.
;; Already using org-agenda-files? Merge instead of overwriting, e.g.:
;;   (add-to-list 'org-agenda-files org-gtd-directory)
(setq org-agenda-files (list org-gtd-directory))

;; REQUIRED: Enable org-edna for project dependencies
(org-edna-mode 1)

;; Global keybindings (work anywhere in Emacs)
(global-set-key (kbd "C-c d c") 'org-gtd-capture)
(global-set-key (kbd "C-c d e") 'org-gtd-engage)
(global-set-key (kbd "C-c d p") 'org-gtd-process-inbox)
(global-set-key (kbd "C-c d n") 'org-gtd-show-all-next)
(global-set-key (kbd "C-c d s") 'org-gtd-reflect-stuck-projects)

;; Keybinding for organizing items (only works in clarify buffers)
(with-eval-after-load 'org-gtd
  (define-key org-gtd-clarify-mode-map (kbd "C-c c") 'org-gtd-organize))

;; Quick actions on tasks in agenda views (optional but recommended)
(with-eval-after-load 'org-agenda
  (define-key org-agenda-mode-map (kbd "C-c .") 'org-gtd-agenda-transient))
#+end_src

** Performance

*** Native Compilation

org-gtd supports native compilation for improved performance. If you have
Emacs built with native compilation support (--with-native-compilation):

1. Enable automatic native compilation:
   #+begin_src emacs-lisp
   (setq package-native-compile t)
   #+end_src

2. Reinstall or recompile org-gtd:
   #+begin_src emacs-lisp
   M-x package-reinstall RET org-gtd RET
   #+end_src

3. Packages will be natively compiled on installation

4. Expected performance improvement: 10-20% in large GTD datasets (500+ tasks)

*** Performance Characteristics

org-gtd is optimized for Emacs 28.1+ primitives:
- Fast literal string matching (string-search)
- Lexical binding throughout
- Efficient property access

Tested with GTD datasets up to 500+ tasks without performance issues.

** Your First GTD Cycle

*** 1. Capture Something

Press ~C-c d c~ (or ~M-x org-gtd-capture~).

Type: "Buy birthday gift for Alex"

Press ~C-c C-c~ to save and close.

*** 2. Process Your Inbox

Press ~C-c d p~ (or ~M-x org-gtd-process-inbox~).

You'll see a buffer with your captured item. This is the *clarify* step - edit the item to make it clear and actionable.

*** 3. Organize the Item

When you're ready to organize, press ~C-c c~ (or ~M-x org-gtd-organize~).

A menu appears asking what type of item this is. For our example:

Press ~s~ for "Single action" (a one-off task to do when possible).

org-gtd will prompt you to add tags if you want (press RET to skip).

The item is now filed into your GTD system!

*** 4. See It in Your Daily View

Press ~C-c d e~ (or ~M-x org-gtd-engage~).

You'll see an agenda view showing all your NEXT actions and scheduled items. Your item "Buy birthday gift for Alex" should be there with a NEXT state.

** What Just Happened?

You just completed the core GTD cycle:

1. *Capture* - Got something out of your head (~org-gtd-capture~)
2. *Clarify* - Made it clear and actionable (editing in the WIP buffer)
3. *Organize* - Categorized it (~org-gtd-organize~)
4. *Engage* - Saw it in your action list (~org-gtd-engage~)

The two remaining GTD steps:
- *Process* - Loop through your inbox (we did this with ~org-gtd-process-inbox~)
- *Review* - Regularly check your system (commands like ~org-gtd-reflect-stuck-projects~)

* What's Next

** Complete Tutorial

See ~doc/org-gtd.org~ (or ~C-h i m org gtd RET~ / ~M-x info-display-manual RET org-gtd~) for:
- Full 15-minute tutorial with projects and dependencies
- Custom agenda views with the declarative DSL
- Configuration examples for Doom Emacs and Spacemacs
- Complete command reference
- Hooks and customization guide
- Integration with email and other tools

** Learn More About GTD

If you're new to GTD, read [[https://gettingthingsdone.com/][David Allen's book]]. org-gtd implements the methodology faithfully, so understanding GTD itself will help you use the tool effectively.

** Get Help

- *Documentation*: ~C-h i m org gtd RET~ or ~M-x info-display-manual RET org-gtd~ (info manual)
- *Issues*: [[https://github.com/Trevoke/org-gtd.el/issues][GitHub Issues]]
- *Community*: [[https://discord.gg/2kAK6TfqJq][Discord Server]]
- *Sponsor*: [[https://github.com/sponsors/Trevoke/][GitHub Sponsors]]

** Next Steps in Your Learning

1. *Create a project* - Learn how projects with multiple tasks work
2. *Use dependencies* - Make tasks parallel or create custom blocking
3. *Create custom views* - Define your own weekly review using the view DSL
4. *Add hooks* - Customize what happens when you organize items
5. *Integrate* - Connect org-gtd to email, code tools, etc.

All of this is covered in the full documentation.


* Version Notice

** Upgrading to 4.0?

This is org-gtd 4.0.0 - a major release with flexible project dependencies and simplified configuration.

If you're upgrading from version 3.x, see the [[file:doc/org-gtd.org#upgrading][Upgrading section]] in the documentation for:
- Required configuration changes (keyword mapping)
- Required data migration command (~M-x org-gtd-upgrade-v3-to-v4~)
- What's new in 4.0

*Important*: Version 4.0 changes how projects work internally. You must run the migration for existing projects to continue working.

** What's New in 4.0

*** Flexible project dependencies!
Projects can now have parallel tasks and custom dependency relationships, not just sequential execution.

*** Simplified keyword configuration
Use ~org-gtd-keyword-mapping~ instead of multiple individual variables.

*** Declarative view language
Create custom agenda views with simple filter specifications instead of complex skip functions.

*** Better project modification
Add tasks to projects anywhere, create custom dependencies, manage complex structures.

See the full documentation for complete details.

* Directory Structure

- ~dev/~ :: Development jail environment
- ~doc/~ :: Complete documentation and info manual
- ~test/~ :: Test suite