-
-
Notifications
You must be signed in to change notification settings - Fork 45
/
org-gtd.info
1077 lines (824 loc) · 38.1 KB
/
org-gtd.info
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This is org-gtd.info, produced by makeinfo version 6.8 from
org-gtd.texi.
Copyright (C) 2018-2023 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.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Org GTD: (org-gtd). An opinionated GTD flow implemented in org-mode.
END-INFO-DIR-ENTRY
File: org-gtd.info, Node: Top, Next: Setting up Org GTD, Up: (dir)
Org GTD User Manual
*******************
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.2
* Menu:
* Setting up Org GTD::
* Using Org GTD:: How Org GTD maps to the GTD flow
* Troubleshooting::
— The Detailed Node Listing —
Setting up Org GTD
* Summary:: quick intro to GTD
* Upgrading:: How to upgrade your local setup across major versions
* Installing:: Get Org GTD in your emacs
* Configuring:: Required and optional system configuration
Upgrading
* 2.2.0 <- 2.1.0: 220 <- 210.
* 2.1.0 <- 2.0.0: 210 <- 200.
* 2.0.0 <- 1.1.x: 200 <- 11x.
Installing
* use-package::
* Manually::
Configuring
* The easy way::
* Required configuration of sub-packages::
* configuration options for org-gtd::
* Recommended key bindings::
Using Org GTD
* Adding things to the inbox::
* Processing the inbox::
* Engaging with your GTD items::
* Cleaning up / archiving completed work::
* Multiple files / refile targets::
Processing the inbox
* Projects::
* Modify an existing project::
* Quick action::
* Trash::
* Calendar::
* Delegate::
* Single action::
* Archive::
* Incubate::
Engaging with your GTD items
* Interacting with org-agenda::
Multiple files / refile targets
* New project heading::
* Other headings::
Troubleshooting
* Projects without a NEXT item::
* I can't create a project when clarifying an inbox item!::
File: org-gtd.info, Node: Setting up Org GTD, Next: Using Org GTD, Prev: Top, Up: Top
1 Setting up Org GTD
********************
* Menu:
* Summary:: quick intro to GTD
* Upgrading:: How to upgrade your local setup across major versions
* Installing:: Get Org GTD in your emacs
* Configuring:: Required and optional system configuration
File: org-gtd.info, Node: Summary, Next: Upgrading, Up: Setting up Org GTD
1.1 Summary
===========
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
File: org-gtd.info, Node: Upgrading, Next: Installing, Prev: Summary, Up: Setting up Org GTD
1.2 Upgrading
=============
If you are installing and not upgrading, you can skip this section
entirely and just go to the next section, *note Installing::.
* Menu:
* 2.2.0 <- 2.1.0: 220 <- 210.
* 2.1.0 <- 2.0.0: 210 <- 200.
* 2.0.0 <- 1.1.x: 200 <- 11x.
File: org-gtd.info, Node: 220 <- 210, Next: 210 <- 200, Up: Upgrading
1.2.1 2.2.0 <- 2.1.0
--------------------
• respect org-mode’s org-reverse-note-order variable
The upgrade to ‘2.0.1’ allowed addition of a task as the first task
of an existing project while organizing a clarified item. ‘2.0.2’
allows the user to choose what they prefer. Correspondibly, it
lets the ‘org-mode’ variable ‘org-reverse-note-order’ operate as it
should. In your configuration, use:
(setq org-reverse-note-order t) ;; refile to the top of the list
(setq org-reverse-note-order nil) ;; refile to the bottom of the list
Note that if you’re upgrading straight from 2.0.0 you still need to
make the adjustment to the TRIGGER for your project headings.
File: org-gtd.info, Node: 210 <- 200, Next: 200 <- 11x, Prev: 220 <- 210, Up: Upgrading
1.2.2 2.1.0 <- 2.0.0
--------------------
• Update org-edna trigger
In order for project modification to work, you will need to go to
every Project heading that you have. You will find the following:
:PROPERTIES:
:TRIGGER: next-sibling todo!(NEXT)
:ORG_GTD: Projects
:END:
And you will need to update the trigger so it looks like this:
:PROPERTIES:
:TRIGGER: relatives(forward-no-wrap todo-only 1 no-sort) todo!(NEXT)
:ORG_GTD: Projects
:END:
Now be sure to set the following variable in your config file,
before org-gtd loads, to disable the loud warning:
(setq org-gtd-update-ack "2.1.0")
That is it! You’re ready to add tasks to existing projects while
processing the inbox.
File: org-gtd.info, Node: 200 <- 11x, Prev: 210 <- 200, Up: Upgrading
1.2.3 2.0.0 <- 1.1.x
--------------------
• Configuration
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.
• Example upgrade
My org-gtd config for 1.x was as follows:
(use-package org-gtd
:after org
:quelpa (org-gtd :fetcher github :repo "trevoke/org-gtd.el"
:commit "1.1.1" :upgrade t)
:demand t
:custom
(org-gtd-directory "~/org-gtd")
(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"
:commit "2.0.0" :upgrade t)
:demand t
:custom
(org-gtd-directory "~/org-gtd")
(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)))
• Relevant commands with new names
• ‘org-agenda-list’ -> ‘org-gtd-engage’
• ‘org-gtd-clarify-finalize’ -> ‘org-gtd-choose’ (see the
section on Key bindings below)
• heading states (TODO, etc.)
You need to rename CANCELED to CNCL. a simple string replace in
the ‘org-gtd-directory’ will do the trick.
• Differentiating GTD types of items
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’.
• Multiple refile targets
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:
• Key bindings
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)
File: org-gtd.info, Node: Installing, Next: Configuring, Prev: Upgrading, Up: Setting up Org GTD
1.3 Installing
==============
This package requires emacs 27.1 or higher.
This package is on MELPA and MELPA stable under the name ‘org-gtd’.
* Menu:
* use-package::
* Manually::
File: org-gtd.info, Node: use-package, Next: Manually, Up: Installing
1.3.1 use-package
-----------------
Just make sure this is loaded after ‘org-mode’ like so.
(use-package org-gtd :after org)
File: org-gtd.info, Node: Manually, Prev: use-package, Up: Installing
1.3.2 Manually
--------------
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)
File: org-gtd.info, Node: Configuring, Prev: Installing, Up: Setting up Org GTD
1.4 Configuring
===============
* Menu:
* The easy way::
* Required configuration of sub-packages::
* configuration options for org-gtd::
* Recommended key bindings::
File: org-gtd.info, Node: The easy way, Next: Required configuration of sub-packages, Up: Configuring
1.4.1 The easy way
------------------
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 *note Recommended key
bindings:: section.
File: org-gtd.info, Node: Required configuration of sub-packages, Next: configuration options for org-gtd, Prev: The easy way, Up: Configuring
1.4.2 Required configuration of sub-packages
--------------------------------------------
• org-edna
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)
File: org-gtd.info, Node: configuration options for org-gtd, Next: Recommended key bindings, Prev: Required configuration of sub-packages, Up: Configuring
1.4.3 configuration options for org-gtd
---------------------------------------
• I don’t care, just let me start using it
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 *note Using Org GTD::.
• Tell me all the levers I can pull
Make sure you also read about sub-package configuration: *note
Required configuration of sub-packages::.
‘org-gtd-directory’
set this to a directory. ‘org-gtd’ will look for all its
files in this directory.
‘org-gtd-capture-templates’
(!note: take care when changing this) This defines the
pre-filled text that will show up when capturing an item to
the inbox. This is a simplified version of
‘org-capture-templates’. If you want to modify it, you should
be able to get away with only reading the documentation for
this one variable. The only recommendation is that the
template string must define an org-mode top-level heading.
That is to say, the first two characters must be a single
asterisk followed by a space: "* ". *note Adding things to
the inbox::.
‘org-gtd-agenda-custom-commands’
(!note: take care when changing this) this is the exact same
thing as ‘org-agenda-custom-commands’. ‘Org-gtd’ requires
that the key ‘g’ be bound to a display view, so if you want to
change what ‘org-gtd’ displays, make sure you leave the ‘g’
alone (or modify that one). *note Engaging with your GTD
items::.
‘org-reverse-note-order’
(‘org-mode’ variable) set this to ‘t’ to add new items to the
top of project tasks and to ‘nil’ to add new items to the
bottom of project tasks. Most relevant, see *note Projects::
and *note Modify an existing project::.
‘org-gtd-process-item-hooks’
this is a list of functions that you can use to decorate each
item when you clarify it. For instance, you could add a
function to set the effort, or the priority, or some category,
etc. By default it has only one function, which lets you add
tags. You could remove this function if you wanted. *note
Processing the inbox::.
‘org-gtd-archive-location’
variable that holds a function to generate the archive file.
I made this choice primarily because I want to refile to an
archive file suffixed with the year, and I’m *just too lazy*
to manually rename them once a year. The function has an
arity of zero and generates an org-mode file+outline path.
*note Cleaning up / archiving completed work::.
‘org-gtd-refile-to-any-target’
when ‘t’, ‘org-gtd’ will refile to the first target it finds,
and create a target if it doesn’t find one. When false, it
will ask for confirmation before refiling. *note Multiple
files / refile targets::.
‘org-gtd-delegate-read-func’
function that is used to prompt for a person a task is
delegated to. Must return a string. By default this is set
to ‘read-string’.
File: org-gtd.info, Node: Recommended key bindings, Prev: configuration options for org-gtd, Up: Configuring
1.4.4 Recommended key bindings
------------------------------
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 c’
‘org-gtd-capture’
‘C-c d e’
‘org-gtd-engage’
etc.
File: org-gtd.info, Node: Using Org GTD, Next: Troubleshooting, Prev: Setting up Org GTD, Up: Top
2 Using Org GTD
***************
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.
* Menu:
* Adding things to the inbox::
* Processing the inbox::
* Engaging with your GTD items::
* Cleaning up / archiving completed work::
* Multiple files / refile targets::
File: org-gtd.info, Node: Adding things to the inbox, Next: Processing the inbox, Up: Using Org GTD
2.1 Adding things to the inbox
==============================
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.
File: org-gtd.info, Node: Processing the inbox, Next: Engaging with your GTD items, Prev: Adding things to the inbox, Up: Using Org GTD
2.2 Processing the inbox
========================
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 *note 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.
*[P]rojects
This is a multi-step action. *note Projects::.
*[M]odify a project
Add current task to pre-existing project. *note Modify an existing
project::.
*[Q]uick action
Less than 2 minutes. Do it now, then choose this to mark the item
as DONΕ and archive it. *note Quick action::.
*[T]rash*
Not actionable; not knowledge. *note Trash::.
*[C]alendar*
Single action to be done at a given date or time. *note
Calendar::.
*[D]elegate
Let someone else do this. *note Delegate::.
*[S]ingle action*
This is a one-off to be done when possible. *note Single action::.
*[A]rchive*
This is knowledge to be stored away. *note Archive::.
*[I]ncubate*
no action now; review later. *note Incubate::.
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.
This process will continue, item after item, until you hit *x* to
exit early or until you run out of items to process.
The decorations (priority, tags, categories, etc.) are customizable
as you desire and managed by ‘org-gtd-process-item-hooks’, a list of
functions. By default there is one element in the list, to add tags to
the item. You can add your own functions to this list, as long as the
functions do not modify the text in any "custom" way, separate from what
org-mode understands.
* Menu:
* Projects::
* Modify an existing project::
* Quick action::
* Trash::
* Calendar::
* Delegate::
* Single action::
* Archive::
* Incubate::
File: org-gtd.info, Node: Projects, Next: Modify an existing project, Up: Processing the inbox
2.2.1 Projects
--------------
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. Those second-level headings represent
the sequentially-ordered set of tasks to be executed before the project
can be called complete. 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 to the next item in the inbox.
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.
Projects will show up in the agenda, but only the current NEXT task.
File: org-gtd.info, Node: Modify an existing project, Next: Quick action, Prev: Projects, Up: Processing the inbox
2.2.2 Modify an existing project
--------------------------------
When you choose this, the package will do the following:
• refile this as a task inside the project of the project (first or
last, depending on value of ‘org-reverse-note-order’)
• adjust the TODO keywords of the project such that:
• all DONE or CNCL keywords are untouched
• there is exactly one WAIT or NEXT keyword
• all other keywords are TODO
You can go to that project yourself and readjust the order of the
headings as necessary, and then you can go to that project’s top heading
("Project heading" in example below) and execute ‘M-x
org-gtd-projects-fix-todo-keywords-for-project-at-point’
* Project heading
** NEXT First task
** TODO Second task
** TODO Third task
File: org-gtd.info, Node: Quick action, Next: Trash, Prev: Modify an existing project, Up: Processing the inbox
2.2.3 Quick action
------------------
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.
This won’t show up in the agenda, because you’ve already done it.
File: org-gtd.info, Node: Trash, Next: Calendar, Prev: Quick action, Up: Processing the inbox
2.2.4 Trash
-----------
When you choose trash, the item is automatically marked as CNCL and
archived, then Org GTD moves on to the next item.
This won’t show up in the agenda, because you don’t care about it.
File: org-gtd.info, Node: Calendar, Next: Delegate, Prev: Trash, Up: Processing the inbox
2.2.5 Calendar
--------------
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.
This will come up in the agenda when the time is right. Literally.
File: org-gtd.info, Node: Delegate, Next: Single action, Prev: Calendar, Up: Processing the inbox
2.2.6 Delegate
--------------
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.
This will show up in the "Blocked" section of the agenda.
File: org-gtd.info, Node: Single action, Next: Archive, Prev: Delegate, Up: Processing the inbox
2.2.7 Single action
-------------------
When you choose single action, Org GTD will mark it as a NEXT item, then
Org GTD moves on to the next item.
This will show up in the agenda as a NEXT item.
File: org-gtd.info, Node: Archive, Next: Incubate, Prev: Single action, Up: Processing the inbox
2.2.8 Archive
-------------
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.
This won’t show up in the agenda because it’s not actionable.
File: org-gtd.info, Node: Incubate, Prev: Archive, Up: Processing the inbox
2.2.9 Incubate
--------------
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.
This will show up in the agenda at the date of your choosing.
File: org-gtd.info, Node: Engaging with your GTD items, Next: Cleaning up / archiving completed work, Prev: Processing the inbox, Up: Using Org GTD
2.3 Engaging with your GTD items
================================
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.
Org Gtd uses ‘org-edna’ to automatically trigger state changes in
projects, such that when you mark a NEXT item from a project as DONE,
the next TODO in that project automatically becomes NEXT, such that the
agenda is always up-to-date (you may need to refresh the agenda).
* Menu:
* Interacting with org-agenda::
File: org-gtd.info, Node: Interacting with org-agenda, Up: Engaging with your GTD items
2.3.1 Interacting with org-agenda
---------------------------------
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.
File: org-gtd.info, Node: Cleaning up / archiving completed work, Next: Multiple files / refile targets, Prev: Engaging with your GTD items, Up: Using Org GTD
2.4 Cleaning up / archiving completed work
==========================================
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 *note 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’.
File: org-gtd.info, Node: Multiple files / refile targets, Prev: Cleaning up / archiving completed work, Up: Using Org GTD
2.5 Multiple files / refile targets
===================================
If you would like to add new refile targets, it’s simple, follow these
instructions.
* Menu:
* New project heading::
* Other headings::
File: org-gtd.info, Node: New project heading, Next: Other headings, Up: Multiple files / refile targets
2.5.1 New project heading
-------------------------
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: relatives(forward-no-wrap todo-only 1 no-sort) todo!(NEXT)
:ORG_GTD: Projects
:END:
File: org-gtd.info, Node: Other headings, Prev: New project heading, Up: Multiple files / refile targets
2.5.2 Other headings
--------------------
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
*note New project heading::):
Scheduled actions
‘ORG_GTD: Calendar’
Incubated actions
‘ORG_GTD: Incubated’
Single & Delegated actions
‘ORG_GTD: Actions’
File: org-gtd.info, Node: Troubleshooting, Prev: Using Org GTD, Up: Top
3 Troubleshooting
*****************
* Menu:
* Projects without a NEXT item::
* I can't create a project when clarifying an inbox item!::
File: org-gtd.info, Node: Projects without a NEXT item, Next: I can't create a project when clarifying an inbox item!, Up: Troubleshooting
3.1 Projects without a NEXT item
================================
Sometimes things break. Use ‘M-x org-gtd-show-stuck-projects’ to find