-
-
Notifications
You must be signed in to change notification settings - Fork 45
/
org-gtd.info
1587 lines (1236 loc) · 59.9 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 <trevoke@gmail.com>
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: Summary, 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 3.0
* Menu:
* Summary:: quick intro to GTD
* What’s new in 3.0: What's new in 30.
* Setting up Org GTD::
* Using Org GTD:: How Org GTD maps to the GTD flow
* Troubleshooting::
— The Detailed Node Listing —
What’s new in 3.0
* Minimum emacs version now 27.2: Minimum emacs version now 272.
* Organize menu has changed::
* Easier to clarify more items::
* Functions exist to create your own hooks::
* Support habits::
* Todo keywords can be customized::
* Massive API changes::
* Massive Data structure changes::
* Include horizons::
* You can create your own project templates and insert them while clarifying::
Setting up Org 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
* 3.0.0 <- 2.2.0: 300 <- 220.
* 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::
* Sample Doom Emacs Config::
Using Org GTD
* Org-mode building blocks for Org GTD::
* The GTD flow::
* Automating through emacs::
The GTD flow
* Adding things to the inbox::
* Processing the inbox::
* Clarifying each item::
* Organizing an item into the system::
* Engaging with your GTD items::
* Working with the GTD Horizons::
* Cleaning up / archiving completed work::
* Commands you can call on org-agenda::
* Defining your own agenda views::
* Adding your own hooks when organizing::
Troubleshooting
* Finding lost tasks::
* Projects without a NEXT item::
* I can't create a project when clarifying an inbox item!::
File: org-gtd.info, Node: Summary, Next: What's new in 30, Prev: Top, Up: Top
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---+
| INBOX |
+---+---+
| Eliminate +-----------+
| +----------->| Trash |
+------v------+ | +-----------+
| What is it? | |
+------+------+ | +-----------+
| | Incubate | Someday/ |
| +----------->| Maybe |
+----------+ YES (multi-step) +------v------+ NO | +-----------+
| Projects |<--------------------| Is it |-----+
+-+----^---+ | Actionable? | | File +-----------+
| | +----------------+ +------+------+ +----------->| Reference |
| | Review for | | +-----------+
+-v----+---+ Actions | |
| Planning | +---------->| YES
+----------+ |
+------v------+ Less than
Delegate | What's the | 2 minutes +-----------+
+-----------+ NEXT +----------------->| DO IT |
| | Action? | +-----------+
| +------+------+
| |
| | FOR ME:
| | Specific Date or Time
| +-------------------------------+
| ASAP| |
+-----v-----+ +-----v-----+ +-----v-----+
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
+-----------+ +-----------+ +-----------+
Waiting For Next Actions Calendar
File: org-gtd.info, Node: What's new in 30, Next: Setting up Org GTD, Prev: Summary, Up: Top
2 What’s new in 3.0
*******************
* Menu:
* Minimum emacs version now 27.2: Minimum emacs version now 272.
* Organize menu has changed::
* Easier to clarify more items::
* Functions exist to create your own hooks::
* Support habits::
* Todo keywords can be customized::
* Massive API changes::
* Massive Data structure changes::
* Include horizons::
* You can create your own project templates and insert them while clarifying::
File: org-gtd.info, Node: Minimum emacs version now 272, Next: Organize menu has changed, Up: What's new in 30
2.1 Minimum emacs version now 27.2
==================================
It became too difficult for me to support 27.1.
File: org-gtd.info, Node: Organize menu has changed, Next: Easier to clarify more items, Prev: Minimum emacs version now 272, Up: What's new in 30
2.2 Organize menu has changed
=============================
• Habits have their place now (h)
• What used to be called "archive" is now called "knowledge" (k)
• Modify project is now "Add to project" (a)
File: org-gtd.info, Node: Easier to clarify more items, Next: Functions exist to create your own hooks, Prev: Organize menu has changed, Up: What's new in 30
2.3 Easier to clarify more items
================================
There’s now two more powerful commands you can use to clarify almost
anything:
• ‘org-gtd-clarify-item’
• ‘org-gtd-clarify-agenda-item’
These both allow you to enter a one-off clarify/organize flow.
File: org-gtd.info, Node: Functions exist to create your own hooks, Next: Support habits, Prev: Easier to clarify more items, Up: What's new in 30
2.4 Functions exist to create your own hooks
============================================
Make GTD truly a part of your emacs experience! These functions take
various arguments (check the documentation in emacs) and automatically
add something to your org-gtd. This would be useful after sending an
email, for instance. Please share your own hooks as issues in Github or
in the discord so we can create a community library!
• ‘org-gtd-habit-create’
• ‘org-gtd-calendar-create’
• ‘org-gtd-delegate-create’
• ‘org-gtd-incubate-create’
• ‘org-gtd-single-action-create’
File: org-gtd.info, Node: Support habits, Next: Todo keywords can be customized, Prev: Functions exist to create your own hooks, Up: What's new in 30
2.5 Support habits
==================
Org mode’s habits now have a specific place here.
File: org-gtd.info, Node: Todo keywords can be customized, Next: Massive API changes, Prev: Support habits, Up: What's new in 30
2.6 Todo keywords can be customized
===================================
*note See all the configuration options: Tell me all the levers I can
pull.
File: org-gtd.info, Node: Massive API changes, Next: Massive Data structure changes, Prev: Todo keywords can be customized, Up: What's new in 30
2.7 Massive API changes
=======================
The package domain now is a better match for the domain language of GTD.
Functions use the words ‘capture’, ‘process’, ‘clarify’, ‘organize’,
‘review’.
File: org-gtd.info, Node: Massive Data structure changes, Next: Include horizons, Prev: Massive API changes, Up: What's new in 30
2.8 Massive Data structure changes
==================================
• 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.
• We use our own timestamp property. For compatibility with orgzly,
we currently duplicate the timestamp into the body.
File: org-gtd.info, Node: Include horizons, Next: You can create your own project templates and insert them while clarifying, Prev: Massive Data structure changes, Up: What's new in 30
2.9 Include horizons
====================
• 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
*note Working with the GTD Horizons::.
File: org-gtd.info, Node: You can create your own project templates and insert them while clarifying, Prev: Include horizons, Up: What's new in 30
2.10 You can create your own project templates and insert them while clarifying
===============================================================================
*note Options and commands related to clarification::
File: org-gtd.info, Node: Setting up Org GTD, Next: Using Org GTD, Prev: What's new in 30, Up: Top
3 Setting up Org GTD
********************
* Menu:
* 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: Upgrading, Next: Installing, Up: Setting up Org GTD
3.1 Upgrading
=============
If you are installing and not upgrading, you can skip this section
entirely and just go to the next section, *note Installing::.
* Menu:
* 3.0.0 <- 2.2.0: 300 <- 220.
* 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: 300 <- 220, Next: 220 <- 210, Up: Upgrading
3.1.1 3.0.0 <- 2.2.0
--------------------
There’s a lot here, so you may want to make yourself some tea. We have
to cover support for org habits, upgrading data, key changes in the
configuration, a change in the menu, and the rest of the API changes.
And once that’s done, you should head back to the *note What’s new in
3.0: What's new in 30. section to see what else is available for you!
• A note for doom emacs users
Beta testers using doom emacs found they needed to do a fully clean
install. The regular upgrades did not work. We could not find a
clean fix. We suspect this is related to org-mode being a very
complex beast, but we’re not sure.
• Support for org habits
For the sake of keeping the ‘org-agenda-custom-commands’ as simple
as possible, habits are now stored under headings with the property
‘ORG_GTD: Habits’. The same rules for refiling apply to these
headings.
• Upgrading data
Some not-inconsequential data structure changes happened under the
hood. To keep using ‘org-gtd’ you will need to upgrade your data,
using ‘M-x org-gtd-upgrade-v2-to-v3’. _Backups are always
recommended, even though there are tests._ Note that if there are
any habits managed by ‘org-gtd v2’ then they will be moved to a
heading ‘* Habits’, in a file called ‘org-gtd-tasks.org’, in
‘org-gtd-directory’.
• Key changes in configuration
Here’s a table of the changes, with sample config change and
explanations afterwards.
2.0 3.0
--------------------------------------------------------------------------
‘org-gtd-process-mode’ ‘org-gtd-clarify-mode’
‘org-gtd-process-map’ ‘org-gtd-clarify-map’
‘org-gtd-choose’ ‘org-gtd-organize’
‘org-gtd-process-item-hooks’ ‘org-gtd-organize-hooks’
‘org-gtd-capture-templates’ Now looks like ‘org-capture-templates’
Projects :TRIGGER: changed again (see below)
‘org-gtd-agenda-custom-config’ gone (see below)
org file headers Drop ’em (see below)
• Sample new config
(use-package org-gtd
:after org
:quelpa (org-gtd :fetcher github :repo "trevoke/org-gtd.el"
:commit "3.0.0" :upgrade t)
:demand t
:custom
(org-gtd-directory "~/org-gtd")
(org-edna-use-inheritance t)
(org-gtd-organize-hooks '(org-gtd-set-area-of-focus org-set-tags-command))
: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)
:map org-gtd-clarify-map
("C-c c" . org-gtd-organize)))
• Projects trigger
The new trigger line looks like this:
‘:TRIGGER: org-gtd-next-project-action
org-gtd-update-project-task!’
This allows us to define these functions as flexibly as we
want, in the future, and that will mean we can expand what it
means to be a project in the future.
• ‘org-gtd-capture-templates’
Most of you users have not had to touch this, so you probably
won’t have a use for this section of the upgrade
documentation. The new data structure is now a complete
parallel for the ‘org-capture-templates’ structure, so you can
see how to structure it by looking at the help file for that.
The key elements are still the same, however:
• the template has to start with a single asterisk
• the entry has to be ‘entry (file ,#'org-gtd-inbox-path)’
• ‘org-gtd-agenda-custom-config’
This customization is no longer in use. It wasn’t an easy
decision to make, but I have to make way for bigger, future
changes in org-gtd over the next major releases.
If you have an existing ‘org-gtd-agenda-custom-commands’
setup, then you can do something like this to keep using it.
In short, for now, create your own function, and wrap the
definition with the ‘with-org-gtd-context’ macro. You can see
the source code of ‘org-gtd-engage’ for an example.
; only so I refer to it with a name in this snippet
(setq my-commands org-gtd-agenda-custom commands)
(defun my-org-gtd-engage ()
(interactive)
(with-org-gtd-context
(let ((org-agenda-custom-commands my-commands))
; "g" is what the previous command used, replace with what you need
(org-agenda nil "g"))))
• Dropping the org file headers
The TODO keywords are now customizable (see ‘M-x
customize-group org-gtd RET’), while they were hard-coded in
v2. Those hard-coded values are now the defaults, but you
should remove the hard-coded values anyway, so remove the
following line:
‘#+TODO: NEXT(n) TODO(t) WAIT(w@) | DONE(d) CNCL(c@)’
• A change in the menu
• Habits have their place (‘h’)
• What used to be called "archive" is now called "knowledge"
(‘k’)
• Modify project is now "Add to project" (‘a’)
Do note that that "a" got completely reassigned! If you used to
use it for items that went into your personal knowledge management
system, you’ll need to retrain yourself.
I’m very sorry about this. In the future, you’ll be able to
customize this UI.
• Rest of API changes
• ‘org-gtd-delegate’ is now ‘org-gtd-delegate-item-at-point’
This is the function to call if you want to delegate without
refiling.
• ‘org-gtd-agenda-projectify’ is now ‘just
org-gtd-clarify-agenda-item’
V3 means you can freely clarify and organize anything in the
agenda with the above function.
• ‘org-gtd-agenda-delegate’ is now
‘org-gtd-delegate-agenda-item’
The nomenclature changes here because of an effort to, over
time, define a better language for GTD, slicing vertically
through org-mode features.
• ‘org-gtd-cancel-project’ is now ‘org-gtd-project-cancel’
Same reason as above.
• ‘org-gtd-agenda-cancel-project’ is now
‘org-gtd-project-cancel-from-agenda’
Same reason as above.
• ‘org-gtd-show-stuck-projects’ is now
‘org-gtd-review-stuck-projects’
Same reason as above.
• That’s it!
Go check out *note What’s new in 3.0: What's new in 30. as well as
*note Configuring::.
File: org-gtd.info, Node: 220 <- 210, Next: 210 <- 200, Prev: 300 <- 220, Up: Upgrading
3.1.2 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. Correspondingly, 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, or
(setq org-reverse-note-order nil) ;; refile to the bottom of the list
Note that if you’re upgrading directly 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
3.1.3 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
3.1.4 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
3.2 Installing
==============
This package requires emacs 27.2 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
3.2.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
3.2.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
3.3 Configuring
===============
* Menu:
* The easy way::
* Required configuration of sub-packages::
* configuration options for org-gtd::
* Recommended key bindings::
* Sample Doom Emacs Config::
File: org-gtd.info, Node: The easy way, Next: Required configuration of sub-packages, Up: Configuring
3.3.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
3.3.2 Required configuration of sub-packages
--------------------------------------------
• Configuring 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
3.3.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-next’
Keyword to use for actions ready to be taken
‘org-gtd-next-suffix’
org-mode keyword suffix (e.g. !, @)
‘org-gtd-todo’
Keyword to use for actions not yet ready
‘org-gtd-todo-suffix’
org-mode keyword suffix (e.g. !, @)
‘org-gtd-wait’
Keyword to use for blocked actions (e.g. delegated)
‘org-gtd-wait-suffix’
org-mode keyword suffix (e.g. !, @)
‘org-gtd-done’
Keyword to use for completed actions
‘org-gtd-done-suffix’
org-mode keyword suffix (e.g. !, @)
‘org-gtd-canceled’
Keyword to use for actions that won’t be done
‘org-gtd-canceled-suffix’
org-mode keyword suffix (e.g. !, @)
‘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. The only requirements are that the template string
must define an org-mode top-level heading, and that the entry
point to the inbox. That is to say, the first two characters
must be a single asterisk followed by a space: ‘"* "’, and the
entry type must be like this: ‘entry (file
,#'org-gtd-inbox-path)’. *note Adding things to the inbox::.
‘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 when organizing an item as such.
‘org-gtd-organize-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, but of course you can change this entirely. *note
Organizing an item: Organizing an item into the system.
‘org-gtd-archive-location’
Points to a function to generate the archive file dynamically.
Default value generates a file suffixed with the current 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 Refiling to
the appropriate area::.
‘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’.
‘org-gtd-areas-of-focus’
list of strings representing your areas of focus (horizon 2 in
GTD).
‘org-gtd-clarify-show-horizons’
When clarifying, do you want the horizons buffer to be shown
by default, or do you prefer it hidden?
‘org-gtd-clarify-project-templates’
Alist of strings: ‘project template name . project template’
where there template is a series of tasks you may want to
insert automatically, if you have a generic type of project
that comes up a lot.
‘org-gtd-horizons-file’
Name of the file, in ‘org-gtd-directory’, that will be
displayed when the horizons buffer is displayed when
clarifying.
‘org-gtd-engage-prefix-width’
how many characters to dedicate to the prefix, on the left
side of the TODO items, so the project name, if any, can show
clearly.
File: org-gtd.info, Node: Recommended key bindings, Next: Sample Doom Emacs Config, Prev: configuration options for org-gtd, Up: Configuring
3.3.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-organize’. I suggest ‘C-c c’, as in the following example.
(define-key org-gtd-clarify-map (kbd "C-c c") #'org-gtd-organize)
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: Sample Doom Emacs Config, Prev: Recommended key bindings, Up: Configuring
3.3.5 Sample Doom Emacs Config
------------------------------
If you are a Doom Emacs user, then your configuration may look something
like this:
(use-package! org-gtd
:after org
:config
(setq org-edna-use-inheritance t)
(org-edna-mode)
(map! :leader
(:prefix ("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-review-stuck-projects))
(map! :map org-gtd-clarify-map
:desc "Organize this item" "C-c c" #'org-gtd-organize))
File: org-gtd.info, Node: Using Org GTD, Next: Troubleshooting, Prev: Setting up Org GTD, Up: Top
4 Using Org GTD
***************
* Menu:
* Org-mode building blocks for Org GTD::
* The GTD flow::
* Automating through emacs::
File: org-gtd.info, Node: Org-mode building blocks for Org GTD, Next: The GTD flow, Up: Using Org GTD
4.1 Org-mode building blocks for Org GTD
========================================
This section introduces how Org GTD leverages org-mode.
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).
Org GTD uses org keywords to figure out the relevant state of each
task. By default, ‘NEXT’, ‘TODO’, ‘WAIT’, ‘CNCL’, and ‘DONE’, though
you can configure them.
Org GTD uses the following properties:
‘ORG_GTD’
top-level property, used for simple filtering when it comes to
agenda views
‘ORG_GTD_TIMESTAMP’
where the timestamp for appointments and other date-relevant
actions is stored. It’s separate from everything else org-mode
related in order to allow you, the user, to use ‘SCHEDULED’,