1task-tutorial(5) User Manuals task-tutorial(5)
2
6 task-tutorial - A tutorial for the task(1) command line todo manager.
7
10 This tutorial contains a narrative and a series of commands that lead
11 you through different scenarios and illustrate the capabilities of
12 taskwarrior. We will begin with basic usage, and progress to the more
13 powerful features. It is recommended that you work through these exam‐
14 ples alongside this tutorial.
15 Make your terminal window as wide as you can, to properly see the for‐
17 matted output of this page.
18 Taskwarrior has many features and you will probably not use them all,
20 but there are likely to be several capabilities that work well with
21 your style of managing tasks. Everyone has different usage patterns.
22 This is therefore a complete list of capabilities, and you should
23 choose accordingly.
24
27 Let's get started. We're planning a party, and there is a lot of work
28 to do, so let's capture these tasks, by using the 'add' command.
29 $ task add Select a free weekend in November
31 Created task 1.
32 $ task add Select and book a venue
33 Created task 2.
34 $ task add Come up with a guest list
35 Created task 3.
36 $ task add Mail invitations
37 Created task 4.
38 $ task add Select a caterer
39 Created task 5.
40 The '$' prompt shows that these are commands that you type (don't
42 include the $ symbol yourself), and lines without the prompt are those
43 displayed by taskwarrior. Let's take a look at our tasks so far.
44 $ task list
46 ID Project Pri Due Active Age Description
48 -- ------- --- --- ------ -------
49 ---------------------------------
50 1 1 min Select a free weekend in No‐
51 vember
52 2 55 secs Select and book a venue
53 3 49 secs Come up with a guest list
54 4 40 secs Mail invitations
55 5 33 secs Select a caterer
56 5 tasks
58 Now I've already ordered a cake, so rather than 'add' this, I'm going
60 to 'log' it. This just means that I want to keep track of the task,
61 but I've already done it. It saves me a step.
62 $ task log Order a special cake
64 Logged task.
65 As for those invitations, I'm going to need to design them first. And
67 I'm also going to need print them. Here we are duplicating a task and
68 making a substitution. Notice how the commands can be abbreviated,
69 provided they are still unique.
70 $ task 4 duplicate /Mail/Design/
72 Duplicated 4 'Mail invitations'.
73 Duplicated 1 task.
74 Created task 7.
75 $ task 4 dup /Mail/Print/
76 Duplicated 4 'Mail invitations'.
77 Duplicated 1 task.
78 Created task 8.
79 $ task list
80 That looks good - but now I think of it, I already have my guest list,
82 so I can mark that one as done.
83 $ task 3 done
85 Completed 3 'Come up with a guest list'.
86 Marked 1 task as done.
87 $ task list
88 ID Project Pri Due Active Age Description
90 -- ------- --- --- ------ ------
91 ---------------------------------
92 1 8 mins Select a free weekend in Novem‐
93 ber
94 2 7 mins Select and book a venue
95 3 6 mins Mail invitations
96 4 6 mins Select a caterer
97 5 4 mins Design invitations
98 6 4 mins Print invitations
99 6 tasks
101 And that's basic usage, and you already know enough to be productive
103 using taskwarrior. If you stopped here, you would be perfectly able to
104 manage your task list.
105 But if you want to see what it can really do, keep reading...
107
110 Remember to pay the rent at the end of the month.
111 $ task add Pay teh rent on teh 31st
113 Created task 7.
114 Oh, that was sloppy, but it can be fixed with a global substitution,
116 represented by the 'g' at the end. You could omit the 'g', and it
117 would only make the first substitution.
118 $ task 7 /teh/the/g
120 Modified 1 task.
121 $ task list
122 ID Project Pri Due Active Age Description
124 -- ------- --- --- ------ -------
125 ---------------------------------
126 1 12 mins Select a free weekend in No‐
127 vember
128 2 12 mins Select and book a venue
129 3 11 mins Mail invitations
130 4 11 mins Select a caterer
131 5 9 mins Design invitations
132 6 9 mins Print invitations
133 7 37 secs Pay the rent on the 31st
134 7 tasks
136 We can now use projects to separate home chores from the party prepara‐
138 tion. Let's assign that last task to the 'home' project. Note that a
139 task may only belong to one project.
140 $ task 7 project:home
142 The scope of project 'home' has changed. Project 'home' is 0%
143 complete (1 of 1 tasks remaining).
144 Modified 1 task.
145 And we will put those first six tasks in the 'party' project. See how
147 we specify a range of tasks? Taskwarrior will want to confirm bulk
148 changes like this, but we'll accept all changes here.
149 $ task 1-6 project:party
151 Task 1 "Select a free weekend in November"
153 - project will be set to 'party'.
154 Proceed with change? (Yes/no/All/quit) A
155 The scope of project 'party' has changed. Project 'party' is 0%
157 complete (1 of 1 tasks remaining).
158 The scope of project 'party' has changed. Project 'party' is 0%
159 complete (2 of 2 tasks remaining).
160 The scope of project 'party' has changed. Project 'party' is 0%
161 complete (3 of 3 tasks remaining).
162 The scope of project 'party' has changed. Project 'party' is 0%
163 complete (4 of 4 tasks remaining).
164 The scope of project 'party' has changed. Project 'party' is 0%
165 complete (5 of 5 tasks remaining).
166 The scope of project 'party' has changed. Project 'party' is 0%
167 complete (6 of 6 tasks remaining).
168 Modified 6 tasks.
169 Now that we have multiple projects, as shown here, we can use project
171 as a filter for the list report. You can see again that we can abbre‐
172 viate 'list' and 'project', but when we abbreviate 'party', we are fil‐
173 tering all the projects that begin with 'par'.
174 $ task projects
176 Project Tasks Pri:None Pri:L Pri:M Pri:H
178 ------- ----- -------- ----- ----- -----
179 home 1 1 0 0 0
180 party 6 6 0 0 0
181 2 projects (7 tasks)
183 $ task list project:home
184 ID Project Pri Due Active Age Description
186 -- ------- --- --- ------ ------ ------------------------
187 7 home 5 mins Pay the rent on the 31st
188 1 task
190 $ task li pro:par
191 ID Project Pri Due Active Age Description
193 -- ------- --- --- ------ -------
194 ---------------------------------
195 1 party 18 mins Select a free weekend in No‐
196 vember
197 2 party 17 mins Select and book a venue
198 3 party 17 mins Mail invitations
199 4 party 17 mins Select a caterer
200 5 party 15 mins Design invitations
201 6 party 15 mins Print invitations
202 6 tasks
204
207 Priorities are another way to organize tasks. You can use priority
208 values of high, medium and low, and taskwarrior knows these as H, M or
209 L.
210 $ task 1-3,5 priority:H
212 Task 1 "Select a free weekend in November"
214 - priority will be set to 'H'.
215 Proceed with change? (Yes/no/All/quit) A
216 Modified 4 tasks.
218 $ task list
220 ID Project Pri Due Active Age Description
222 -- ------- --- --- ------ -------
223 ---------------------------------
224 1 party H 24 mins Select a free weekend in No‐
225 vember
226 2 party H 23 mins Select and book a venue
227 3 party H 23 mins Mail invitations
228 5 party H 21 mins Design invitations
229 7 home 12 mins Pay the rent on the 31st
230 4 party 23 mins Select a caterer
231 6 party 21 mins Print invitations
232 7 tasks
234 You can remove priorities by specifying a blank value.
236 $ task 3 pri:
238 Modified 1 task.
239
242 A task may only have one project, but it may have any number of tags,
243 which are just single words associated with the task. I can go to the
244 print shop at the mall, and do all the invitation tasks, so let's tag
245 them all.
246 $ task 3,5,6 +mall
248 Task 3 "Mail invitations"
250 - tags will be set to 'mall'.
251 Proceed with change? (Yes/no/All/quit) A
252 Modified 3 tasks.
254 The long report shows tags, too,
256 $ task long
258 ID Project Pri Added Started Due Recur Countdown Age
260 Deps Tags Description
261 -- ------- --- ---------- ------- --- ----- --------- -------
262 ---- ---- ---------------------------------
263 1 party H 10/16/2010 27 mins
264 Select a free weekend in November
265 2 party H 10/16/2010 26 mins
266 Select and book a venue
267 5 party H 10/16/2010 23 mins
268 mall Design invitations
269 7 home 10/16/2010 14 mins
270 Pay the rent on the 31st
271 3 party 10/16/2010 25 mins
272 mall Mail invitations
273 4 party 10/16/2010 25 mins
274 Select a caterer
275 6 party 10/16/2010 23 mins
276 mall Print invitations
277 7 tasks
279 and I can use tags as a filter to any report too.
281 $ task list +mall
283 ID Project Pri Due Active Age Description
285 -- ------- --- --- ------ ------- ------------------
286 5 party H 24 mins Design invitations
287 3 party 26 mins Mail invitations
288 6 party 24 mins Print invitations
289 3 tasks
291 I made a mistake - I can't mail out the invitations at the mall, so
293 let's remove that tag.
294 $ task 3 -mall
296 Modified 1 task.
297
300 Task 7 is not worded correctly, so I can modify that by specifying a
301 task ID and a new description. This is also considered a bulk change,
302 and so requires confirmation.
303 $ task 7 Pay rent at the end of the month
305 Task 7 "Pay the rent on the 31st"
307 - description will be changed from 'Pay the rent on the 31st'
308 to 'Pay rent at the end of the month'.
309 Proceed with change? (Yes/no/All/quit) Y
310 Modified 1 task.
312 We'll need music. I can prepend, and I can append to a task.
314 $ task add music
316 $ task 8 prepend Select some
317 $ task 8 append for after dinner
318 $ task list dinner
319 ID Project Pri Due Active Age Description
321 -- ------- --- --- ------ -------
322 ----------------------------------
323 8 34 secs Select some Music for after
324 dinner
325 1 task
327 I can also go straight into an editor and modify anything. The task is
329 formatted and you can edit anything you like, and the changes will be
330 detected and made to the task.
331 $ task 5 edit
333 [Your $EDITOR is invoked]
334 Sometimes the command line will confuse the shell. In this case, what
336 would happen if there was a file named 'bands' in the current direc‐
337 tory?
338 $ task add Hire a band?
340 The shell might expand that wild-card, so to avoid that, you can escape
342 the wild-card, or quote the whole description.
343 $ task add Hire a band\?
345 $ task add "Hire a band?"
346 You can also use the minus minus operator which tells taskwarrior to
348 stop being clever and interpret the rest of the arguments as a task
349 description. Otherwise, that +dj would be interpreted as a tag.
350 $ task add -- Hire a band\? +dj
352 Created task 9.
353 We don't really need a band, so the easiest way to get rid of that task
355 is to undo the last change. Taskwarrior has a complete undo stack, so
356 you can undo all the way back to the beginning.
357 $ task undo
359 The last modification was made 10/16/2010
361 Prior Values Current Values
363 ------------ ------------------------------------
364 description Hire a band? +dj
365 entry 10/16/2010
366 status pending
367 uuid 599c7598-069d-4598-8d94-0c919c4213ec
368 The undo command is not reversible. Are you sure you want to
370 revert to the previous state? (y/n) y
371 Task removed.
372 The undo operation gets rid of the task completely, but I could also
374 have just deleted the task, then the deletion itself would be tracked,
375 and also undo-able.
376 $ task 1 delete
378 Permanently delete task 1 'Select a free weekend in November'?
379 (y/n) y
380 Deleting task 1 'Select a free weekend in November'.
381 The scope of project 'party' has changed. Project 'party' is 0%
382 complete (5 of 5 tasks remaining).
383 $ task undo
384 The last modification was made 10/16/2010
386 Prior Values Current Val‐
388 ues
389 ------------------------------------
390 ------------------------------------
391 description Select a free weekend in November Select a free
392 weekend in November
393 entry 10/16/2010 10/16/2010
394 priority H H
395 project party party
396 status pending deleted
397 uuid 3a6881bb-628b-4f90-93d7-4da563b83d54
398 3a6881bb-628b-4f90-93d7-4da563b83d54
399 end 10/16/2010
400 The undo command is not reversible. Are you sure you want to
402 revert to the previous state? (y/n) y
403 Modified task reverted.
404
407 During that undo operation, taskwarrior displayed metadata that is
408 associated with the task. You can display this with the info command,
409 and its shortcut.
410 $ task 1 info
412 Name Value
414 ----------- ------------------------------------
415 ID 1
416 Description Select a free weekend in November
417 Status Pending
418 Project party
419 Priority H
420 UUID 3a6881bb-628b-4f90-93d7-4da563b83d54
421 Entered 10/16/2010 (44 mins)
422 $ task 1
424 Name Value
426 ----------- ------------------------------------
427 ID 1
428 Description Select a free weekend in November
429 Status Pending
430 Project party
431 Priority H
432 UUID 3a6881bb-628b-4f90-93d7-4da563b83d54
433 Entered 10/16/2010 (44 mins)
434 There are also statistics that taskwarrior gathers, which I can dis‐
436 play.
437 $ task stats
439 Category Data
441 -------------------- -------------
442 Pending 8
443 Waiting 0
444 Recurring 0
445 Completed 2
446 Deleted 0
447 Total 10
448 Annotations 0
449 Unique tags 1
450 Projects 2
451 Data size 9.3 KiB
452 Undo transactions 32
453 Tasks tagged 20%
454 Oldest task 10/16/2010
455 Newest task 10/16/2010
456 Task used for 29 mins
457 Task added every 2 mins
458 Task completed every 14 mins
459 Average time pending 31 mins
460 Average desc length 23 characters
461
464 Annotations are little notes that can be added to a task. There can be
465 any number, and each has a time stamp.
466 $ task 1 annotate the 13th looks good
468 Annotated 1 with 'the 13th looks good'.
469 $ task 1 annotate or the 14th Annotated 1 with 'or the 14th'
470 $ task list
471 ID Project Pri Due Active Age Description
473 -- ------- --- --- ------ -------
474 ----------------------------------
475 1 party H 48 mins Select a free weekend in No‐
476 vember
477 10/16/2010 the 13th looks good
478 10/16/2010 or the 14th
479 2 party H 47 mins Select and book a venue
480 5 party H 44 mins Design invitations
481 8 19 mins Select some Music for after
482 dinner
483 7 home 35 mins Pay rent at the end of the
484 month
485 3 party 47 mins Mail invitations
486 4 party 47 mins Select a caterer
487 6 party 44 mins Print invitations
488 8 tasks
490 You can choose to display annotations in different ways.
492 $ task list rc.annotations:full
494 ID Project Pri Due Active Age Description
496 -- ------- --- --- ------ -------
497 ---------------------------------
498 1 party H 49 mins Select a free weekend in No‐
499 vember
500 10/16/2010 the 13th looks good
501 10/16/2010 or the 14th
502 1 task
504 Configuration override annotations:full
505 $ task list rc.annotations:sparse
506 ID Project Pri Due Active Age Description
508 -- ------- --- --- ------ -------
509 ----------------------------------
510 1 party H 49 mins +Select a free weekend in No‐
511 vember
512 10/16/2010 or the 14th
513 1 task
515 Configuration override annotations:sparse
516 $ task list rc.annotations:none
517 ID Project Pri Due Active Age Description
519 -- ------- --- --- ------ -------
520 ----------------------------------
521 1 party H 49 mins +Select a free weekend in No‐
522 vember
523 1 task
525 Configuration override annotations:none
526 Annotations can be removed by providing a matching pattern.
528 $ task 1 denotate 14th
530 Found annotation 'or the 14th' and deleted it.
531
534 There is a 'show' command, that is used to display the active configu‐
535 ration. There are hundreds of settings that can be changed, and every
536 one has a sensible default.
537 $ task show
539 Config variable Value
541 ------------------------------- ----------------
542 _forcecolor no
543 active.indicator *
544 alias.export export.yaml
545 alias.export.vcalendar export.ical
546 alias.ghistory ghistory.monthly
547 alias.history history.monthly
548 alias.rm delete
549 annotations full
550 ...
551 weekstart Sunday
552 If you want a complete list of all the settings and their meanings,
554 read the man page.
555 $ man taskrc
557 The 'config' command is used to modify the settings, and in this case
559 the configuration variable 'answer' is given the value of forty-two.
560 $ task config answer forty-two
562 Are you sure you want to add 'answer' with a value of 'forty-
563 two'? (y/n) y
564 Config file .taskrc modified.
565 The 'show' command indicates that the value was changed, and also that
567 the variable is unrecognized. The show command performs a detailed
568 check on your configuration, and alerts you to several kinds of prob‐
569 lem. The config command can also remove a value.
570 $ task show answer
572 Config variable Value
574 --------------- ---------
575 answer forty-two
576 Your .taskrc file contains these unrecognized variables:
578 answer
579 $ task config answer
581 Are you sure you want to remove 'answer'? (y/n) y
582 Config file .taskrc modified.
583 A very powerful feature is the ability to override the configuration
585 variables temporarily. Here I am requesting an ascending sort on the
586 description field only.
587 $ task rc.report.list.sort=description+ list
589 ID Project Pri Due Active Age Description
591 -- ------- --- --- ------ -------
592 ----------------------------------
593 5 party H 51 mins Design invitations
594 3 party 53 mins Mail invitations
595 7 home 42 mins Pay rent at the end of the
596 month
597 6 party 51 mins Print invitations
598 4 party 53 mins Select a caterer
599 1 party H 54 mins Select a free weekend in No‐
600 vember
601 10/16/2010 the 13th looks good
602 2 party H 53 mins Select and book a venue
603 8 25 mins Select some Music for after
604 dinner
605 8 tasks
607 Configuration override report.list.sort=description+
608 The value in the configuration file is prefixed with 'rc.' to identify
610 its namespace.
611
614 There is a default command, which can be set to anything, in this case
615 it is set to the 'list' report. Then running taskwarrior with no com‐
616 mand name runs the default command.
617 $ task config default.command list
619 Are you sure you want to add 'default.command' with a value of
620 'list'? (y/n) y
621 Config file .taskrc modified.
622 $ task
623 ID Project Pri Due Active Age Description
625 -- ------- --- --- ------ -------
626 ----------------------------------
627 1 party H 55 mins Select a free weekend in No‐
628 vember
629 10/16/2010 the 13th looks good
630 2 party H 54 mins Select and book a venue
631 5 party H 52 mins Design invitations
632 8 26 mins Select some Music for after
633 dinner
634 7 home 43 mins Pay rent at the end of the
635 month
636 3 party 54 mins Mail invitations
637 4 party 54 mins Select a caterer
638 6 party 52 mins Print invitations
639 8 tasks
641 I can also specify a default priority and project, which means that any
643 tasks added will use them, unless an alternative is provided.
644 $ task config default.priority H
646 Are you sure you want to add 'default.priority' with a value of
647 'H'? (y/n) y
648 Config file .taskrc modified.
649 $ task config default.project work
650 Are you sure you want to add 'default.project' with a value of
651 'work'? (y/n) y
652 Config file .taskrc modified.
653 $ task add New task
654 Created task 9.
655 $ task list New task
656 ID Project Pri Due Active Age Description
658 -- ------- --- --- ------ ------- -----------
659 9 work H 12 secs New task
660 1 task
662 Let's just revert those changes, to clean up.
664 $ task undo
666 The last modification was made 10/16/2010
668 Prior Values Current Values
670 ------------ ------------------------------------
671 description New task
672 entry 10/16/2010
673 priority H
674 project work
675 status pending
676 uuid 0f44f9dd-79db-4098-b95b-4c3aa97d575a
677 The undo command is not reversible. Are you sure you want to
679 revert to the previous state? (y/n) y
680 Task removed.
681 $ task config default.priority
682 Are you sure you want to remove 'default.priority'? (y/n) y
683 Config file .taskrc modified.
684 $ task config default.project
685 Are you sure you want to remove 'default.project'? (y/n) y
686 Config file .taskrc modified.
687
690 You can create aliases to effectively rename commands.
691 $ task config alias.zzz list
693 Are you sure you want to add 'alias.zzz' with a value of 'list'?
694 (y/n) y
695 Config file .taskrc modified.
696 $ task zzz
697 ID Project Pri Due Active Age Description
699 -- ------- --- --- ------ -------
700 ----------------------------------
701 1 party H 1 hr Select a free weekend in No‐
702 vember
703 10/16/2010 the 13th looks good
704 2 party H 59 mins Select and book a venue
705 5 party H 56 mins Design invitations
706 8 30 mins Select some Music for after
707 dinner
708 7 home 47 mins Pay rent at the end of the
709 month
710 3 party 59 mins Mail invitations
711 4 party 58 mins Select a caterer
712 6 party 56 mins Print invitations
713 8 tasks
715 You can abbreviate those, too.
717 $ task z
719 ID Project Pri Due Active Age Description
721 -- ------- --- --- ------ -------
722 ----------------------------------
723 1 party H 1 hr Select a free weekend in No‐
724 vember
725 10/16/2010 the 13th looks good
726 2 party H 59 mins Select and book a venue
727 5 party H 56 mins Design invitations
728 8 30 mins Select some Music for after
729 dinner
730 7 home 47 mins Pay rent at the end of the
731 month
732 3 party 59 mins Mail invitations
733 4 party 58 mins Select a caterer
734 6 party 56 mins Print invitations
735 8 tasks
737
740 [Note that you will see color in your terminal as you work through this
741 tutorial, but you will not see the color in the man page. This is a
742 limitation of man pages in general. The text shown (without color) is
743 included here.]
744 All the examples so far have been shown with color turned off. How
746 about some color?
747 $ task config color on
749 Are you sure you want to change the value of 'color' from 'off'
750 to 'on'? (y/n) y
751 Config file .taskrc modified.
752 $ task list
753 ID Project Pri Due Active Age Description
755 -- ------- --- --- ------ -------
756 ----------------------------------
757 1 party H 1 hr Select a free weekend in No‐
758 vember
759 10/16/2010 the 13th looks good
760 2 party H 1 hr Select and book a venue
761 5 party H 59 mins Design invitations
762 8 33 mins Select some Music for after
763 dinner
764 7 home 50 mins Pay rent at the end of the
765 month
766 3 party 1 hr Mail invitations
767 4 party 1 hr Select a caterer
768 6 party 59 mins Print invitations
769 8 tasks
771 What you see is the result of a set of color rules being applied to the
773 tasks. There is a hierarchy of color rules that colorize a task based
774 on the metadata.
775 Here is an example of an explicit override to the color rules where a
777 specific task is given a red background.
778 $ task 1 bg:on_red
780 modified 1 task.
781 $ task list
782 ID Project Pri Due Active Age Description
784 -- ------- --- --- ------ -------
785 ----------------------------------
786 1 party H 1 hr Select a free weekend in No‐
787 vember
788 10/16/2010 the 13th looks good
789 2 party H 1 hr Select and book a venue
790 5 party H 59 mins Design invitations
791 8 33 mins Select some Music for after
792 dinner
793 7 home 50 mins Pay rent at the end of the
794 month
795 3 party 1 hr Mail invitations
796 4 party 1 hr Select a caterer
797 6 party 59 mins Print invitations
798 8 tasks
800 $ task 1 bg:
801 Modified 1 task.
802 Taskwarrior supports 256 colors on certain terminal emulators, and this
804 shows the range of colors available. Note that your terminal may show
805 fewer colors.
806 $ task color
808 Basic colors
810 black red blue green magenta cyan yellow white
811 black red blue green magenta cyan yellow white
812 Effects
814 red bold red underline on blue on green on bright
815 green
816 color0 - color15
818 0 1 2 . . .
819 . . . 15
822 Color cube rgb000 - rgb555 (also color16 - color231)
824 0 1 2 3 4
825 5
826 0 1 2 3 4 5 0 1 2 3 4 5 0 1 2 3 4 5 0 1 2 3 4 5 0 1 2 3 4
827 5 0 1 2 3 4 5
828 0
829 1
830 2
831 3
832 4
833 5
834 Gray ramp gray0 - gray23 (also color232 - color255)
836 0 1 2 . . . . . . 23
837 Try running 'task color white on red'.
840 This is how to show a color sample.
842 $ task color white on red
844 Use this command to see how colors are displayed by your termi‐
846 nal.
847 16-color usage (supports underline, bold text, bright back‐
850 ground):
851 task color black on bright yellow
852 task color underline cyan on bright blue
853 256-color usage (supports underline):
855 task color color214 on color202
856 task color rgb150 on rgb020
857 task color underline grey10 on grey3
858 task color red on color173
859 Your sample:
861 task color white on red
862 Or samples of all the active color settings.
864 $ task color legend
866 Here are the colors currently in use:
868 Color Definition
870 ------------------------- -------------------------
871 color.active black on bright green
872 color.alternate
873 color.blocked black on white
874 color.calendar.due white on red
875 color.calendar.due.today bold white on red
876 color.calendar.holiday black on bright yellow
877 color.calendar.overdue black on bright red
878 color.calendar.today bold white on bright blue
879 color.calendar.weekend white on bright black
880 color.calendar.weeknumber bold blue
881 color.debug yellow
882 color.due red
883 color.due.today red
884 color.footnote yellow
885 color.header yellow
886 color.history.add black on red
887 color.history.delete black on yellow
888 color.history.done black on green
889 color.overdue bold red
890 color.pri.H bold white
891 color.pri.L
892 color.pri.M white
893 color.pri.none
894 color.recurring magenta
895 color.summary.background on gray3
896 color.summary.bar on green
897 color.sync.added green
898 color.sync.changed yellow
899 color.sync.rejected red
900 color.tagged green
901 color.undo.after green
902 color.undo.before red
903 Themes are a simple way to use coordinated color schemes so by includ‐
905 ing a color theme into the configuration file, you can see some strik‐
906 ing effects. For a blue theme, add this line to your .taskrc file:
907 include /usr/local/share/doc/task/rc/dark-blue-256.theme
909 For a red theme:
911 include /usr/local/share/doc/task/rc/dark-red-256.theme
913 For a general dark theme:
915 include /usr/local/share/doc/task/rc/dark-256.theme
917 Here are two color rules that specify a dark blue background for all
919 tasks that are part of the 'party' project, and uses bold to identify
920 any tasks with the keyword 'invitations' in the description.
921 $ task "rc.color.project.party=on rgb001" rc.color.key‐
923 word.invit=bold list
924 ...
925 There is a man page with a writeup of all the color capabilities.
927 $ man task-color
929
932 I'm selecting a venue, so let's indicate that task 2 is active by
933 starting it. See how active tasks are affected by the color rules.
934 $ task 2 start
936 Started 2 'Select and book a venue'.
937 There is an active report that shows only active tasks, and you can
939 mark any active task as inactive, by stopping it.
940 $ task active
942 ID Project Pri Due Active Age Description
944 -- ------- --- --- ------ ---- -----------------------
945 2 party H * 1 hr Select and book a venue
946 1 task
948 $ task 2 stop
949 Stopped 2 'Select and book a venue'.
950 There is a journalling feature that records the start and stop times as
952 annotations.
953 $ task config journal.time on
955 Are you sure you want to add 'journal.time' with a value of
956 'on'? (y/n) y
957 Config file .taskrc modified.
958 $ task config dateformat.annotation 'Y/m/d H:N'
959 Are you sure you want to add 'dateformat.annotation' with a
960 value of 'Y/m/d H:N'? (y/n) y
961 Config file .taskrc modified.
962 $ task 2 start
963 Started 2 'Select and book a venue'.
964 $ task list venue
965 ID Project Pri Due Active Age Description
967 -- ------- --- --- ------ ---- -----------------------------
968 2 party H * 1 hr Select and book a venue
969 2010/10/16 11:20 Started task
970 1 task
972 $ task 2 stop
973 Stopped 2 'Select and book a venue'.
974 $ task list venue
975 ID Project Pri Due Active Age Description
977 -- ------- --- --- ------ ---- -----------------------------
978 2 party H * 1 hr Select and book a venue
979 2010/10/16 11:20 Started task
980 2010/10/16 11:21 Stopped task
981 1 task
983
986 Due dates can be specified as dates, durations into the future or past,
987 mnemonic, ordinal or day of week.
988 $ task 1 due:7/31/2010
990 Modified 1 task.
991 $ task 1 due:2wks
992 Modified 1 task.
993 $ task 1 due:-2wks
994 Modified 1 task.
995 $ task 1 due:eom
996 Modified 1 task.
997 $ task 2 due:8th
998 Modified 1 task.
999 $ task 2 due:sunday
1000 Modified 1 task.
1001 $ task 5 due:eow
1002 Modified 1 task.
1003 Some of these dates are in the past, so now you see there are overdue
1005 tasks. Due dates have different colors for due, imminent, today and
1006 overdue values. You can also choose the format - for input and output.
1007 $ task rc.dateformat.report:Y-M-DTH:N:SZ list
1009 ID Project Pri Due Active Age Description
1011 -- ------- --- -------------------- ------ ----
1012 ------------------------------------
1013 2 party H 2010-10-17T00:00:00Z 1 hr Select and book
1014 a venue
1015 2010/10/16 11:20
1016 Started task
1017 2010/10/16 11:21
1018 Stopped task
1019 5 party H 2010-10-22T00:00:00Z 1 hr Design invita‐
1020 tions
1021 1 party H 2010-10-31T00:00:00Z 1 hr Select a free
1022 weekend in November
1023 2010/10/16 00:00
1024 the 13th looks good
1025 8 1 hr Select some
1026 Music for after dinner
1027 7 home 1 hr Pay rent at the
1028 end of the month
1029 3 party 1 hr Mail invitations
1030 4 party 1 hr Select a caterer
1031 6 party 1 hr Print invita‐
1032 tions
1033 8 tasks
1035 Configuration override dateformat.report:Y-M-DTH:N:SZ
1036
1039 When tasks have due dates, you can see them on the calendar.
1040 $ task calendar
1042 Taskwarrior provides sample holiday files for countries where taskwar‐
1044 rior is used most. You can create your own, or use one of the samples
1045 to show holidays on the calendar. Try adding this line to your
1046 ~/.taskrc file:
1047 include /usr/local/share/doc/task/rc/holidays-US.rc
1049 Then:
1051 $ task calendar
1053 October 2010 November 2010
1055 December 2010
1056 Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo
1058 Tu We Th Fr Sa
1059 40 1 2 45 1 2 3 4 5 6 49
1060 1 2 3 4
1061 41 3 4 5 6 7 8 9 46 7 8 9 10 11 12 13 50 5 6
1062 7 8 9 10 11
1063 42 10 11 12 13 14 15 16 47 14 15 16 17 18 19 20 51 12 13
1064 14 15 16 17 18
1065 43 17 18 19 20 21 22 23 48 21 22 23 24 25 26 27 52 19 20
1066 21 22 23 24 25
1067 44 24 25 26 27 28 29 30 49 28 29 30 53 26 27
1068 28 29 30 31
1069 45 31
1070 Legend: today, due, due-today, overdue, weekend, holiday,
1072 weeknumber.
1073 There are holiday files for CA, DE, ES, FR, NL, SE, UK and US.
1075 You can see the whole year, see due tasks as well, and see the holi‐
1077 days:
1078 $ task cal 2010
1080 January 2010 February 2010
1082 March 2010 April 2010
1083 Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo
1085 Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1086 1 1 2 6 1 2 3 4 5 6 10 1
1087 2 3 4 5 6 14 1 2 3
1088 2 3 4 5 6 7 8 9 7 7 8 9 10 11 12 13 11 7 8
1089 9 10 11 12 13 15 4 5 6 7 8 9 10
1090 3 10 11 12 13 14 15 16 8 14 15 16 17 18 19 20 12 14 15
1091 16 17 18 19 20 16 11 12 13 14 15 16 17
1092 4 17 18 19 20 21 22 23 9 21 22 23 24 25 26 27 13 21 22
1093 23 24 25 26 27 17 18 19 20 21 22 23 24
1094 5 24 25 26 27 28 29 30 10 28 14 28 29
1095 30 31 18 25 26 27 28 29 30
1096 6 31
1097 May 2010 June 2010
1099 July 2010 August 2010
1100 Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo
1102 Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1103 18 1 23 1 2 3 4 5 27
1104 1 2 3 32 1 2 3 4 5 6 7
1105 19 2 3 4 5 6 7 8 24 6 7 8 9 10 11 12 28 4 5
1106 6 7 8 9 10 33 8 9 10 11 12 13 14
1107 20 9 10 11 12 13 14 15 25 13 14 15 16 17 18 19 29 11 12
1108 13 14 15 16 17 34 15 16 17 18 19 20 21
1109 21 16 17 18 19 20 21 22 26 20 21 22 23 24 25 26 30 18 19
1110 20 21 22 23 24 35 22 23 24 25 26 27 28
1111 22 23 24 25 26 27 28 29 27 27 28 29 30 31 25 26
1112 27 28 29 30 31 36 29 30 31
1113 23 30 31
1114 September 2010 October 2010 No‐
1116 vember 2010 December 2010
1117 Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo
1119 Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1120 36 1 2 3 4 40 1 2 45 1
1121 2 3 4 5 6 49 1 2 3 4
1122 37 5 6 7 8 9 10 11 41 3 4 5 6 7 8 9 46 7 8
1123 9 10 11 12 13 50 5 6 7 8 9 10 11
1124 38 12 13 14 15 16 17 18 42 10 11 12 13 14 15 16 47 14 15
1125 16 17 18 19 20 51 12 13 14 15 16 17 18
1126 39 19 20 21 22 23 24 25 43 17 18 19 20 21 22 23 48 21 22
1127 23 24 25 26 27 52 19 20 21 22 23 24 25
1128 40 26 27 28 29 30 44 24 25 26 27 28 29 30 49 28 29
1129 30 53 26 27 28 29 30 31
1130 45 31
1131 Legend: today, due, due-today, overdue, weekend, holiday,
1133 weeknumber.
1134 $ task rc.calendar.details:full cal
1136 October 2010 November 2010
1138 December 2010 January 2011
1139 Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo
1141 Tu We Th Fr Sa Su Mo Tu We Th Fr Sa
1142 40 1 2 45 1 2 3 4 5 6 49
1143 1 2 3 4 1 1
1144 41 3 4 5 6 7 8 9 46 7 8 9 10 11 12 13 50 5 6
1145 7 8 9 10 11 2 2 3 4 5 6 7 8
1146 42 10 11 12 13 14 15 16 47 14 15 16 17 18 19 20 51 12 13
1147 14 15 16 17 18 3 9 10 11 12 13 14 15
1148 43 17 18 19 20 21 22 23 48 21 22 23 24 25 26 27 52 19 20
1149 21 22 23 24 25 4 16 17 18 19 20 21 22
1150 44 24 25 26 27 28 29 30 49 28 29 30 53 26 27
1151 28 29 30 31 5 23 24 25 26 27 28 29
1152 45 31
1153 6 30 31
1154 Legend: today, due, due-today, overdue, weekend, holiday,
1156 weeknumber.
1157 ID Project Pri Due Active Age Description
1160 -- ------- --- ---------- ------ ----
1161 ------------------------------------
1162 2 party H 10/17/2010 1 hr Select and book a venue
1163 2010/10/16 11:20 Started
1164 task
1165 2010/10/16 11:21 Stopped
1166 task
1167 5 party H 10/22/2010 1 hr Design invitations
1168 1 party H 10/31/2010 1 hr Select a free weekend in
1169 November
1170 2010/10/16 00:00 the 13th
1171 looks good
1172 3 tasks
1174 Configuration override calendar.details:full
1175 $ task rc.calendar.holidays:full cal
1176 October 2010 November 2010
1178 December 2010
1179 Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo
1181 Tu We Th Fr Sa
1182 40 1 2 45 1 2 3 4 5 6 49
1183 1 2 3 4
1184 41 3 4 5 6 7 8 9 46 7 8 9 10 11 12 13 50 5 6
1185 7 8 9 10 11
1186 42 10 11 12 13 14 15 16 47 14 15 16 17 18 19 20 51 12 13
1187 14 15 16 17 18
1188 43 17 18 19 20 21 22 23 48 21 22 23 24 25 26 27 52 19 20
1189 21 22 23 24 25
1190 44 24 25 26 27 28 29 30 49 28 29 30 53 26 27
1191 28 29 30 31
1192 45 31
1193 Legend: today, due, due-today, overdue, weekend, holiday,
1195 weeknumber.
1196 Date Holiday
1199 ---------- -----------------------------------
1200 10/11/2010 Columbus Day
1201 11/11/2010 Veterans Day
1202 11/25/2010 Thanksgiving Day
1203 12/25/2010 Christmas Day
1204 12/31/2010 New Year's Eve
1205 1/1/2011 New Year's Day
1206 1/17/2011 Birthday of Martin Luther King, Jr.
1207 2/21/2011 Washington's Birthday
1208 Configuration override calendar.holidays:full
1210
1213 Remember the task we added to pay the rent? We're going to need to do
1214 that every month. Recurring tasks allow us to set up a single task
1215 that keeps coming back, just as you'd expect.
1216 $ task 7 due:eom recur:monthly
1218 Task 7 is now a recurring task.
1219 Modified 1 task.
1220 $ task 7
1221 Name Value
1223 ----------- ------------------------------------
1224 ID 7
1225 Description Pay rent at the end of the month
1226 Status Recurring
1227 Project home
1228 Recurrence monthly
1229 Mask
1230 Due 10/31/2010
1231 UUID f79123aa-3377-43fd-8f50-d14ab3c1577b
1232 Entered 10/16/2010 (1 hr)
1233 You can also limit the extent of the recurrence. Let's make sure the
1235 task doesn't recur after the lease ends.
1236 $ task 7 until:eoy
1238 Modified 1 task.
1239 And there is a recurring report that shows you only the recurring
1241 tasks.
1242 $ task recurring
1244 ID Project Pri Due Recur Active Age Description
1246 -- ------- --- ---------- ------- ------ ----
1247 --------------------------------
1248 9 home 10/31/2010 monthly 1 hr Pay rent at the
1249 end of the month
1250 1 task
1252 To illustrate a point, let's set up a recurring annual task as a
1254 reminder to pay taxes, and put the due date in the past. This will
1255 cause task to fill in the gaps, and create a series of severely overdue
1256 tasks.
1257 $ task add Pay taxes due:4/15/2007 recur:yearly
1259 Created task 10.
1260 $ task long
1261 ID Project Pri Added Started Due Recur Countdown
1263 Age Deps Tags Description
1264 -- ------- --- ---------- ------- ---------- ------- ---------
1265 ------ ---- ---- ------------------------------------
1266 11 10/16/2010 4/15/2007 yearly 3.5 yrs 2
1267 secs Pay taxes
1268 12 10/16/2010 4/15/2008 yearly 2.5 yrs 2
1269 secs Pay taxes
1270 13 10/16/2010 4/15/2009 yearly 1.5 yrs 2
1271 secs Pay taxes
1272 14 10/16/2010 4/15/2010 yearly 6 mths 2
1273 secs Pay taxes
1274 2 party H 10/16/2010 10/17/2010 -11 hrs
1275 2 hrs Select and book a venue
1276 2010/10/16
1277 11:20 Started task
1278 2010/10/16
1279 11:21 Stopped task
1280 5 party H 10/16/2010 10/22/2010 -5 days
1281 2 hrs mall Design invitations
1282 1 party H 10/16/2010 10/31/2010 -2 wks
1283 2 hrs Select a free weekend in November
1284 2010/10/16
1285 00:00 the 13th looks good
1286 9 home 10/16/2010 10/31/2010 monthly -2 wks
1287 1 hr Pay rent at the end of the month
1288 15 10/16/2010 4/15/2011 yearly -5 mths 2
1289 secs Pay taxes
1290 8 10/16/2010
1291 1 hr Select some Music for after dinner
1292 3 party 10/16/2010
1293 2 hrs Mail invitations
1294 4 party 10/16/2010
1295 2 hrs Select a caterer
1296 6 party 10/16/2010
1297 2 hrs mall Print invitations
1298 13 tasks
1300 Deletions to recurring tasks can be escalated to include all the recur‐
1302 rences of a task.
1303 $ task 11 delete
1305 Permanently delete task 11 'Pay taxes'? (y/n) y
1306 This is a recurring task. Do you want to delete all pending
1307 recurrences of this same task? (y/n) y
1308 Deleting recurring task 10 'Pay taxes'.
1309 Deleting recurring task 11 'Pay taxes'.
1310 Deleting recurring task 12 'Pay taxes'.
1311 Deleting recurring task 13 'Pay taxes'.
1312 Deleting recurring task 14 'Pay taxes'.
1313 Deleting recurring task 15 'Pay taxes'.
1314
1317 You can use the shell command to create a more immersive environment.
1318 Any task command you run outside the shell can also be run inside the
1319 shell, without the need to prefix every command with "task".
1320 $ task shell
1322 task 1.9.4 shell
1323 Enter any task command (such as 'list'), or hit 'Enter'.
1325 There is no need to include the 'task' command itself.
1326 Enter 'quit' to end the session.
1327 task>
1329 task> projects
1330 Project Tasks Pri:None Pri:L Pri:M Pri:H
1332 ------- ----- -------- ----- ----- -----
1333 7 7 0 0 0
1334 home 2 2 0 0 0
1335 party 6 3 0 0 3
1336 3 projects (15 tasks)
1338 task> tags
1339 Tag Count
1341 mall 2
1342 1 tag (15 tasks)
1344 task> list
1345 ID Project Pri Due Active Age Description
1347 -- ------- --- ---------- ------ -----
1348 ------------------------------------
1349 2 party H 10/17/2010 2 hrs Select and book a venue
1350 2010/10/16 11:20 Started
1351 task
1352 2010/10/16 11:21 Stopped
1353 task
1354 5 party H 10/22/2010 2 hrs Design invitations
1355 1 party H 10/31/2010 2 hrs Select a free weekend in
1356 November
1357 2010/10/16 00:00 the 13th
1358 looks good
1359 9 home 10/31/2010 1 hr Pay rent at the end of
1360 the month
1361 8 1 hr Select some Music for
1362 after dinner
1363 3 party 2 hrs Mail invitations
1364 4 party 2 hrs Select a caterer
1365 6 party 2 hrs Print invitations
1366 8 tasks
1368 task> quit
1369
1372 You've seen tags, but there are also 'special tags' that have effects
1373 on individual tasks. The 'nocolor' special tag causes the color rules
1374 to be bypassed.
1375 $ task 6 +nocolor
1377 Modified 1 task.
1378 Special tags are highlighted by the 'tags' command.
1380 $ task tags
1382 Tag Count
1384 ------- -----
1385 mall 2
1386 nocolor 1
1387 2 tags (9 tasks)
1389 There are others - the 'nonag' special tag prevents the generation of
1391 nag messages when you work on low priority tasks when there are more
1392 important ones.
1393 $ task 6 -nocolor
1395 Modified 1 task.
1396 The 'nocal' special tag will prevent a task from appearing on the cal‐
1398 endar.
1399
1402 When you have a task with a due date that is far out into the future,
1403 you may want to hide that task for a while.
1404 $ task add Look for new apartment due:eoy
1406 Created task 10.
1407 You can provide a wait date for a task, and it will remain hidden until
1409 that date. It will no longer be cluttering your task list, but it is
1410 still there, and visible using the 'waiting' report. When the wait
1411 date comes, the task will just reappear in the list.
1412 $ task 10 wait:12/1/2010
1414 Modified 1 task.
1415 $ task list
1416 ID Project Pri Due Active Age Description
1418 -- ------- --- ---------- ------ -----
1419 ------------------------------------
1420 2 party H 10/17/2010 2 hrs Select and book a venue
1421 2010/10/16 11:20 Started
1422 task
1423 2010/10/16 11:21 Stopped
1424 task
1425 5 party H 10/22/2010 2 hrs Design invitations
1426 1 party H 10/31/2010 2 hrs Select a free weekend in
1427 November
1428 2010/10/16 00:00 the 13th
1429 looks good
1430 9 home 10/31/2010 2 hrs Pay rent at the end of
1431 the month
1432 8 1 hr Select some Music for
1433 after dinner
1434 3 party 2 hrs Mail invitations
1435 4 party 2 hrs Select a caterer
1436 6 party 2 hrs Print invitations
1437 8 tasks
1439 $ task waiting
1440 ID Project Pri Wait Age Description
1442 -- ------- --- --------- ----- ----------------------
1443 10 12/1/2010 1 min Look for new apartment
1444 1 task
1446 To illustrate this, let's set up a task with a very short wait time of
1448 five seconds.
1449 $ task add Do something in a few seconds
1451 Created task 11.
1452 $ task 11 wait:5s
1453 Modified 1 task.
1454 $ task list
1455 ID Project Pri Due Active Age Description
1457 -- ------- --- ---------- ------ -----
1458 ------------------------------------
1459 2 party H 10/17/2010 2 hrs Select and book a venue
1460 2010/10/16 11:20 Started
1461 task
1462 2010/10/16 11:21 Stopped
1463 task
1464 5 party H 10/22/2010 2 hrs Design invitations
1465 1 party H 10/31/2010 2 hrs Select a free weekend in
1466 November
1467 2010/10/16 00:00 the 13th
1468 looks good
1469 9 home 10/31/2010 2 hrs Pay rent at the end of
1470 the month
1471 8 1 hr Select some Music for
1472 after dinner
1473 3 party 2 hrs Mail invitations
1474 4 party 2 hrs Select a caterer
1475 6 party 2 hrs Print invitations
1476 8 tasks
1478 It's gone. Now we wait five seconds, then:
1480 $ task list
1482 ID Project Pri Due Active Age Description
1484 -- ------- --- ---------- ------ -------
1485 ------------------------------------
1486 2 party H 10/17/2010 2 hrs Select and book a venue
1487 2010/10/16 11:20
1488 Started task
1489 2010/10/16 11:21
1490 Stopped task
1491 5 party H 10/22/2010 2 hrs Design invitations
1492 1 party H 10/31/2010 2 hrs Select a free weekend
1493 in November
1494 2010/10/16 00:00 the
1495 13th looks good
1496 9 home 10/31/2010 2 hrs Pay rent at the end of
1497 the month
1498 8 1 hr Select some Music for
1499 after dinner
1500 11 18 secs Do something in a few
1501 seconds
1502 3 party 2 hrs Mail invitations
1503 4 party 2 hrs Select a caterer
1504 6 party 2 hrs Print invitations
1505 9 tasks
1507 And it's back. Now we delete it.
1509 $ task 11 rc.confirmation:no delete
1511 Deleting task 11 'Do something in a few seconds'.
1512
1515 Taskwarrior supports dependencies. Let's take a look at the party
1516 planning tasks, and assign dependencies.
1517 $ task list pro:party
1519 ID Project Pri Due Active Age Description
1521 -- ------- --- ---------- ------ -----
1522 ------------------------------------
1523 2 party H 10/17/2010 3 hrs Select and book a venue
1524 2010/10/16 11:20 Started
1525 task
1526 2010/10/16 11:21 Stopped
1527 task
1528 5 party H 10/22/2010 3 hrs Design invitations
1529 1 party H 10/31/2010 3 hrs Select a free weekend in
1530 November
1531 2010/10/16 00:00 the 13th
1532 looks good
1533 3 party 3 hrs Mail invitations
1534 4 party 3 hrs Select a caterer
1535 6 party 3 hrs Print invitations
1536 6 tasks
1538 Let's see. I can't mail invitations until they are printed.
1540 $ task 3 depends:6
1542 Modified 1 task.
1543 I can't print them until I design them.
1545 $ task 6 dep:5
1547 Modified 1 task.
1548 I need to select a weekend before a location.
1550 $ task 2 dep:1
1552 Modified 1 task.
1553 Design depends on location and weekend.
1555 $ task 5 dep:1,2
1557 Modified 1 task.
1558 And the caterer needs to know where.
1560 $ task 4 dep:1
1562 Modified 1 task.
1563 Let's take a look. All my tasks are blocked except task 1. That makes
1565 sense.
1566 $ task long pro:party
1568 ID Project Pri Added Started Due Recur Countdown Age
1570 Deps Tags Description
1571 -- ------- --- ---------- ------- ---------- ----- ---------
1572 ----- ---- ---- ------------------------------------
1573 2 party H 10/16/2010 10/17/2010 -10 hrs 3
1574 hrs 1 Select and book a venue
1575 2010/10/16
1576 11:20 Started task
1577 2010/10/16
1578 11:21 Stopped task
1579 5 party H 10/16/2010 10/22/2010 -5 days 3
1580 hrs 1,2 mall Design invitations
1581 1 party H 10/16/2010 10/31/2010 -2 wks 3
1582 hrs Select a free weekend in November
1583 2010/10/16
1584 00:00 the 13th looks good
1585 3 party 10/16/2010 3
1586 hrs 6 Mail invitations
1587 4 party 10/16/2010 3
1588 hrs 1 Select a caterer
1589 6 party 10/16/2010 3
1590 hrs 5 mall Print invitations
1591 6 tasks
1593 Hmm, that double dependency isn't right.
1595 $ task 5 dep:-1
1597 Modified 1 task.
1598 Here are the blocked tasks, and the opposite, the unblocked tasks.
1600 $ task blocked
1602 ID Deps Project Pri Due Active Age Description
1604 -- ---- ------- --- ---------- ------ -----
1605 -----------------------------
1606 2 1 party H 10/17/2010 3 hrs Select and book a
1607 venue
1608 2010/10/16 11:20
1609 Started task
1610 2010/10/16 11:21
1611 Stopped task
1612 5 2 party H 10/22/2010 3 hrs Design invitations
1613 3 6 party 3 hrs Mail invitations
1614 4 1 party 3 hrs Select a caterer
1615 6 5 party 3 hrs Print invitations
1616 5 tasks
1618 $ task unblocked
1619 ID Deps Project Pri Due Active Age Description
1621 -- ---- ------- --- ---------- ------ -----
1622 ------------------------------------
1623 1 party H 10/31/2010 3 hrs Select a free week‐
1624 end in November
1625 2010/10/16 00:00 the
1626 13th looks good
1627 9 home 10/31/2010 3 hrs Pay rent at the end
1628 of the month
1629 8 3 hrs Select some Music
1630 for after dinner
1631 3 tasks
1633 If we look at task 1 closely, we can see that it is blocking 2 and 4.
1635 $ task 1 info
1637 Name Value
1639 --------------------- ------------------------------------
1640 ID 1
1641 Description Select a free weekend in November
1642 2010/10/16 00:00 the 13th looks good
1643 Status Pending
1644 Project party
1645 Priority H
1646 This task is blocking 2 Select and book a venue
1647 4 Select a caterer
1648 Due 10/31/2010
1649 UUID 3a6881bb-628b-4f90-93d7-4da563b83d54
1650 Entered 10/16/2010 (3 hrs)
1651 And if we look at task 2, we see that it is blocked by 1, and blocking
1653 5.
1654 $ task 2 info
1656 Name Value
1658 --------------------- ------------------------------------
1659 ID 2
1660 Description Select and book a venue
1661 2010/10/16 11:20 Started task
1662 2010/10/16 11:21 Stopped task
1663 Status Pending
1664 Project party
1665 Priority H
1666 This task blocked by 1 Select a free weekend in November
1667 This task is blocking 5 Design invitations
1668 Due 10/17/2010
1669 UUID 773c2b02-919e-4527-95f0-814c19dd198a
1670 Entered 10/16/2010 (3 hrs)
1671 This is called a dependency chain, which is a string of tasks that are
1673 all connected not only by their project, but by dependencies. Now we
1674 understand that task 1 should be done first, but you may still violate
1675 the laws of physics if you wish. Let's complete task 2 and see what
1676 happens.
1677 Taskwarrior realizes what you are doing, and offers to fix the depen‐
1679 dency chain to reflect what you have done.
1680 $ task 2 done
1682 Task 2 is blocked by:
1684 1 Select a free weekend in November
1685 and is blocking:
1686 5 Design invitations
1687 Would you like the dependency chain fixed? (y/n) y
1688 Completed 2 'Select and book a venue'.
1689 Project 'party' is 12% complete (7 of 8 tasks remaining).
1690 Marked 1 task as done.
1691 $ task 1 info
1692 Name Value
1694 --------------------- ------------------------------------
1695 ID 1
1696 Description Select a free weekend in November
1697 2010/10/16 00:00 the 13th looks good
1698 Status Pending
1699 Project party
1700 Priority H
1701 This task is blocking 4 Select a caterer
1702 5 Design invitations
1703 Due 10/31/2010
1704 UUID 3a6881bb-628b-4f90-93d7-4da563b83d54
1705 Entered 10/16/2010 (3 hrs)
1706
1709 Taskwarrior has a good many reports. There is a report with minimal
1710 information:
1711 $ task minimal
1713 ID Project Description
1715 -- ------- ------------------------------------
1716 7 Select some Music for after dinner
1717 8 home Pay rent at the end of the month
1718 4 party Design invitations
1719 2 party Mail invitations
1720 5 party Print invitations
1721 3 party Select a caterer
1722 1 party Select a free weekend in November
1723 2010/10/16 00:00 the 13th looks good
1724 There is the basic report:
1726 $ task ls
1728 ID Project Pri Description
1730 -- ------- --- ------------------------------------
1731 1 party H Select a free weekend in November
1732 2010/10/16 00:00 the 13th looks good
1733 4 party H Design invitations
1734 7 Select some Music for after dinner
1735 8 home Pay rent at the end of the month
1736 2 party Mail invitations
1737 3 party Select a caterer
1738 5 party Print invitations
1739 There is the most common report:
1741 $ task list
1743 ID Project Pri Due Active Age Description
1745 -- ------- --- ---------- ------ -----
1746 ------------------------------------
1747 4 party H 10/22/2010 5 hrs Design invitations
1748 1 party H 10/31/2010 6 hrs Select a free weekend in
1749 November
1750 2010/10/16 00:00 the 13th
1751 looks good
1752 8 home 10/31/2010 5 hrs Pay rent at the end of
1753 the month
1754 7 5 hrs Select some Music for
1755 after dinner
1756 2 party 5 hrs Mail invitations
1757 3 party 5 hrs Select a caterer
1758 5 party 5 hrs Print invitations
1759 There is a report with most of the data shown:
1761 $ task long
1763 ID Project Pri Added Started Due Recur Countdown
1765 Age Deps Tags Description
1766 -- ------- --- ---------- ------- ---------- ------- ---------
1767 ----- ---- ---- ------------------------------------
1768 4 party H 10/16/2010 10/22/2010 -5 days 5
1769 hrs 1 mall Design invitations
1770 1 party H 10/16/2010 10/31/2010 -2 wks 6
1771 hrs Select a free weekend in November
1772 2010/10/16
1773 00:00 the 13th looks good
1774 8 home 10/16/2010 10/31/2010 monthly -2 wks 5
1775 hrs Pay rent at the end of the month
1776 7 10/16/2010 5
1777 hrs Select some Music for after dinner
1778 2 party 10/16/2010 5
1779 hrs 5 Mail invitations
1780 3 party 10/16/2010 5
1781 hrs 1 Select a caterer
1782 5 party 10/16/2010 5
1783 hrs 4 mall Print invitations
1784 There is a report containing all tasks, old and new:
1786 $ task all
1788 ID Project Pri Due Completed Active Age Description
1790 -- ------- --- ---------- ---------- ------ -----
1791 ------------------------------------
1792 9 12/31/2010 3 hrs Look for new
1793 apartment
1794 7 5 hrs Select some
1795 Music for after dinner
1796 - 10/16/2010 6 hrs Come up with a
1797 guest list
1798 - 10/16/2010 5 hrs Order a spe‐
1799 cial cake
1800 6 home 10/31/2010 5 hrs Pay rent at
1801 the end of the month
1802 8 home 10/31/2010 5 hrs Pay rent at
1803 the end of the month
1804 - party H 10/17/2010 10/16/2010 6 hrs Select and
1805 book a venue
1806 2010/10/16
1807 11:20 Started task
1808 2010/10/16
1809 11:21 Stopped task
1810 4 party H 10/22/2010 5 hrs Design invita‐
1811 tions
1812 1 party H 10/31/2010 6 hrs Select a free
1813 weekend in November
1814 2010/10/16
1815 00:00 the 13th looks good
1816 2 party 6 hrs Mail invita‐
1817 tions
1818 5 party 5 hrs Print invita‐
1819 tions
1820 3 party 6 hrs Select a
1821 caterer
1822 There is a report showing completed work:
1824 $ task completed
1826 Complete Project Pri Age Description
1828 ---------- ------- --- ----- -----------------------------
1829 10/16/2010 party H 6 hrs Select and book a venue
1830 2010/10/16 11:20 Started task
1831 2010/10/16 11:21 Stopped task
1832 10/16/2010 6 hrs Come up with a guest list
1833 10/16/2010 5 hrs Order a special cake
1834 There is a report showing recurring tasks only:
1836 $ task recurring
1838 ID Project Pri Due Recur Active Age Description
1840 -- ------- --- ---------- ------- ------ -----
1841 --------------------------------
1842 8 home 10/31/2010 monthly 5 hrs Pay rent at the
1843 end of the month
1844 There is a report to show all the waiting tasks:
1846 $ task waiting
1848 ID Project Pri Wait Age Description
1850 -- ------- --- --------- ----- ----------------------
1851 9 12/1/2010 3 hrs Look for new apartment
1852 There is a report showing all the tasks that are blocked via dependen‐
1854 cies by other tasks:
1855 $ task blocked
1857 ID Deps Project Pri Due Active Age Description
1859 -- ---- ------- --- ---------- ------ ----- ------------------
1860 4 1 party H 10/22/2010 5 hrs Design invitations
1861 2 5 party 6 hrs Mail invitations
1862 3 1 party 6 hrs Select a caterer
1863 5 4 party 5 hrs Print invitations
1864 There is a report showing tasks that are not blocked by dependencies:
1866 $ task unblocked
1868 ID Deps Project Pri Due Active Age Description
1870 -- ---- ------- --- ---------- ------ -----
1871 ------------------------------------
1872 1 party H 10/31/2010 6 hrs Select a free week‐
1873 end in November
1874 2010/10/16 00:00 the
1875 13th looks good
1876 8 home 10/31/2010 5 hrs Pay rent at the end
1877 of the month
1878 7 5 hrs Select some Music
1879 for after dinner
1880 There is a report showing the oldest tasks:
1882 $ task oldest limit:3
1884 ID Project Pri Due Active Age Description
1886 -- ------- --- ---------- ------ -----
1887 ------------------------------------
1888 1 party H 10/31/2010 6 hrs Select a free weekend in
1889 November
1890 2010/10/16 00:00 the 13th
1891 looks good
1892 2 party 6 hrs Mail invitations
1893 3 party 6 hrs Select a caterer
1894 There is a report showing the newest tasks:
1896 $ task newest limit:3
1898 ID Project Pri Due Active Age Description
1900 -- ------- --- ---------- ------ -----
1901 ----------------------------------
1902 8 home 10/31/2010 5 hrs Pay rent at the end of
1903 the month
1904 7 5 hrs Select some Music for
1905 after dinner
1906 5 party 6 hrs Print invitations
1907 There is a report showing the completed and started tasks, by week:
1909 $ task timesheet
1911 10/10/2010 - 10/16/2010
1913 Completed (3 tasks)
1914 Project Due Description
1915 Come up with a guest list
1916 Order a special cake
1917 party 10/17/2010 Select and book a venue
1918 2010/10/16 11:20 Started task
1919 2010/10/16 11:21 Stopped task
1920 Started (0 tasks)
1922 And "what should I work on next?" This one can be useful because it
1924 pulls a few of the highest priority tasks from all the projects.
1925 $ task next
1927 ID Project Pri Due Active Age Description
1929 -- ------- --- ---------- ------ -----
1930 ------------------------------------
1931 1 party H 10/31/2010 6 hrs Select a free weekend in
1932 November
1933 2010/10/16 00:00 the 13th
1934 looks good
1935 8 home 10/31/2010 5 hrs Pay rent at the end of
1936 the month
1937 7 5 hrs Select some Music for
1938 after dinner
1939
1942 You can even define your own custom report. Let's quickly create a
1943 custom report - we'll call it foo - and I can choose from a long list
1944 of fields to include in the report, but I want to see the ID, the date
1945 when I entered the task, and the description. I can specify the labels
1946 for those columns, the sort order of the report, and I can filter.
1947 $ cat >> ~/.taskrc
1949 report.foo.description=My own report
1950 report.foo.columns=id,entry,description
1951 report.foo.labels=ID,Entered,Description
1952 report.foo.sort=entry+,description+
1953 report.foo.filter=status:pending
1954 ^D
1955 Custom reports also show up on the help output.
1957 $ task help | grep foo
1959 task foo [tags] [attrs] desc... My own report
1960 I can inspect the configuration.
1962 $ task show report.foo
1964 Config variable Value
1966 ---------------------- ----------------------
1967 report.foo.columns id,entry,description
1968 report.foo.description My own report
1969 report.foo.filter status:pending
1970 report.foo.labels ID,Entered,Description
1971 report.foo.sort entry+,description+
1972 And they can be run just like the other reports.
1974 $ task foo
1976 ID Entered Description
1978 -- ---------- ------------------------------------
1979 4 10/16/2010 Design invitations
1980 2 10/16/2010 Mail invitations
1981 8 10/16/2010 Pay rent at the end of the month
1982 5 10/16/2010 Print invitations
1983 3 10/16/2010 Select a caterer
1984 1 10/16/2010 Select a free weekend in November
1985 2010/10/16 00:00 the 13th looks good
1986 7 10/16/2010 Select some Music for after dinner
1987 7 tasks
1989
1992 The history report gives monthly totals of tasks added, completed and
1993 deleted. There is also an annual version.
1994 $ task history
1996 Year Month Added Completed Deleted Net
1998 ---- ------- ----- --------- ------- ---
1999 2010 October 19 3 7 9
2000 Average 19 3 7 9
2002 $ task history.annual
2004 Year Added Completed Deleted Net
2006 ------- ----- --------- ------- ---
2007 2010 19 3 7 9
2008 Average 19 3 7 9
2010 There is a graphical monthly and annual version. [These charts do not
2012 show up in a man page]
2013 $ task ghistory
2015 ...
2016 $ task ghistory.annual
2017 ...
2018 There is a project summary report that shows progress in all the
2020 projects.
2021 $ task summary
2023 Project Remaining Avg age Complete 0%
2025 100%
2026 ------- --------- ------- --------
2027 ------------------------------
2028 (none) 2 59 mins 50% ===============
2029 home 1 3 hrs 0%
2030 party 5 6 hrs 16% =====
2031 3 projects
2033
2036 Filters are a very powerful tool. First here is an unfiltered list,
2037 which shows all tasks.
2038 $ task list
2040 ID Project Pri Due Active Age Description
2042 -- ------- --- ---------- ------ -----
2043 ------------------------------------
2044 4 party H 10/22/2010 6 hrs Design invitations
2045 1 party H 10/31/2010 6 hrs Select a free weekend in
2046 November
2047 2010/10/16 00:00 the 13th
2048 looks good
2049 8 home 10/31/2010 6 hrs Pay rent at the end of
2050 the month
2051 7 6 hrs Select some Music for
2052 after dinner
2053 2 party 6 hrs Mail invitations
2054 3 party 6 hrs Select a caterer
2055 5 party 6 hrs Print invitations
2056 7 tasks
2058 Now again, but with the text 'invit', which acts as a filter on the
2060 description field.
2061 $ task list invit
2063 ID Project Pri Due Active Age Description
2065 -- ------- --- ---------- ------ ----- ------------------
2066 4 party H 10/22/2010 6 hrs Design invitations
2067 2 party 6 hrs Mail invitations
2068 5 party 6 hrs Print invitations
2069 3 tasks
2071 This is the equivalent form using attribute modifiers. In this example
2073 we are filtering on descriptions that contain the word fragment. Here
2074 we are using the 'contains' modifier, but there are many others.
2075 $ task list description.contains:invit
2077 ID Project Pri Due Active Age Description
2079 -- ------- --- ---------- ------ ----- ------------------
2080 4 party H 10/22/2010 6 hrs Design invitations
2081 2 party 6 hrs Mail invitations
2082 5 party 6 hrs Print invitations
2083 3 tasks
2085 All tasks containing the whole word 'the'. See how annotations are
2087 also searched?
2088 $ task list desc.word:the
2090 ID Project Pri Due Active Age Description
2092 -- ------- --- ---------- ------ -----
2093 ------------------------------------
2094 1 party H 10/31/2010 6 hrs Select a free weekend in
2095 November
2096 2010/10/16 00:00 the 13th
2097 looks good
2098 8 home 10/31/2010 6 hrs Pay rent at the end of
2099 the month
2100 2 tasks
2102 Here is a list of all tasks that do not contain the whole word 'invita‐
2104 tions'.
2105 $ task list desc.noword:invitations
2107 ID Project Pri Due Active Age Description
2109 -- ------- --- ---------- ------ -----
2110 ------------------------------------
2111 1 party H 10/31/2010 6 hrs Select a free weekend in
2112 November
2113 2010/10/16 00:00 the 13th
2114 looks good
2115 8 home 10/31/2010 6 hrs Pay rent at the end of
2116 the month
2117 7 6 hrs Select some Music for
2118 after dinner
2119 3 party 6 hrs Select a caterer
2120 4 tasks
2122 Here list all tasks in the 'party' project. And the full equivalent.
2124 Here list tasks that are not in the 'party' project. I could have also
2125 used 'isnt' here - there are several synonyms for modifiers, so that
2126 the filter can be written so that it reads naturally.
2127 $ task list pro:party
2129 $ task list pro.is:party
2130 $ task list pro.not:party
2131 Here the 'over' modifier is filtering on priorities that sort higher
2133 than 'Low', and also filtering on the 'party' project. There are two
2134 terms in this filter.
2135 $ task list pro:party pri.over:L
2137 ID Project Pri Due Active Age Description
2139 -- ------- --- ---------- ------ -----
2140 ------------------------------------
2141 4 party H 10/22/2010 6 hrs Design invitations
2142 1 party H 10/31/2010 6 hrs Select a free weekend in
2143 November
2144 2010/10/16 00:00 the 13th
2145 looks good
2146 2 tasks
2148 Same again, but only show me the first two tasks. Now all tasks, but
2150 just show the first page of tasks. I don't have a page full of tasks
2151 here, but you get the idea.
2152 $ task list pro:party limit:2
2154 ID Project Pri Due Active Age Description
2156 -- ------- --- ---------- ------ -----
2157 ------------------------------------
2158 4 party H 10/22/2010 6 hrs Design invitations
2159 1 party H 10/31/2010 6 hrs Select a free weekend in
2160 November
2161 2010/10/16 00:00 the 13th
2162 looks good
2163 2 tasks, 2 shown
2165 $ task list limit:page
2166 ID Project Pri Due Active Age Description
2168 -- ------- --- ---------- ------ -----
2169 ------------------------------------
2170 4 party H 10/22/2010 6 hrs Design invitations
2171 1 party H 10/31/2010 6 hrs Select a free weekend in
2172 November
2173 2010/10/16 00:00 the 13th
2174 looks good
2175 2 tasks
2177 Now you can see how some of the built-in reports work. The 'list'
2179 report is just all tasks, filtered so that only the pending tasks are
2180 shown.
2181 $ task all status:pending
2183 ...
2184 The 'waiting' report is similarly defined.
2186 $ task all status:waiting
2188 ...
2189
2192 You can export your tasks. Here you see all tasks being exported in
2193 CSV format.
2194 $ task export.csv
2196 ´uuid','sta‐
2197 tus','tags','entry','start','due','recur','end','project','pri‐
2198 ority','fg','bg','description'
2199 ´3a6881bb-628b-4f90-93d7-4da563b83d54','pend‐
2200 ing','',1287237300,,1288497600,,,'party','H',,,'Select a free
2201 weekend in November'
2202 ´4a1de9aa-9b00-41ec-8d00-e0d0131e0e0d','pend‐
2203 ing','',1287237365,,,,,'party',,,,'Mail invitations'
2204 ´2a65e922-ff18-4db1-b867-dbe745b9626a','pend‐
2205 ing','',1287237372,,,,,'party',,,,'Select a caterer'
2206 ...
2207 Let's just export one task in CSV format...
2209 $ task export.csv venue
2211 ´uuid','sta‐
2212 tus','tags','entry','start','due','recur','end','project','pri‐
2213 ority','fg','bg','description'
2214 ´773c2b02-919e-4527-95f0-814c19dd198a','com‐
2215 pleted','',1287237350,,1287288000,,1287250285,'party','H',,,'Select
2216 and book a venue'
2217 Or in VCalendar format...
2219 $ task export.vcalendar venue
2221 BEGIN:VCALENDAR
2222 VERSION:2.0
2223 PRODID:-//GBF//task 1.9.4.beta1//EN
2224 BEGIN:VTODO
2225 UID:773c2b02-919e-4527-95f0-814c19dd198a
2226 DTSTAMP:20101016T135550Z
2227 DUE:20101017T040000Z
2228 COMPLETED:20101016T173125Z
2229 SUMMARY:Select and book a venue
2230 CLASS:PRIVATE
2231 PRIORITY:1
2232 STATUS:COMPLETED
2233 COMMENT:Started task
2234 COMMENT:Stopped task
2235 END:VTODO
2236 END:VCALENDAR
2237 Or YAML.
2239 $ task export.yaml venue
2241 %YAML 1.1
2242 ---
2243 task:
2244 depends: 3a6881bb-628b-4f90-93d7-4da563b83d54
2245 description: Select and book a venue
2246 due: 1287288000
2247 end: 1287250285
2248 entry: 1287237350
2249 priority: H
2250 project: party
2251 status: completed
2252 uuid: 773c2b02-919e-4527-95f0-814c19dd198a
2253 annotation:
2254 entry: 1287242411
2255 description: Started task
2256 annotation:
2257 entry: 1287242506
2258 description: Stopped task
2259 ...
2260 I can also import. Here I am importing simple lines of text. Taskwar‐
2262 rior recognizes the format by looking inside the file and making a
2263 guess, then confirms.
2264 $ cat file.text
2266 Remember to read the task man page
2267 $ task import file.text
2268 This looks like a text file with one task per line. Okay to
2269 proceed? (y/n) y
2270 Imported 1 tasks successfully, with 0 errors.
2271 Here is a YAML example. Taskwarrior can read several formats, includ‐
2273 ing old versions of its data files. Using YAML, you can round-trip the
2274 data without loss, which means you can export and import without any
2275 missing information. This also means that 'export.yaml' is good for
2276 making a backup copy of your tasks.
2277 $ cat file.yaml
2279 %YAML 1.1
2280 ---
2281 task:
2282 description: Visit http://taskwarrior.org
2283 due: 1281844800
2284 entry: 1281289630
2285 priority: H
2286 project: work
2287 status: pending
2288 uuid: 23afada0-a446-8d5a-c213-30d99d52c4b0
2289 ...
2290 $ task import file.yaml
2291 This looks like a YAML file. Okay to proceed? (y/n) y
2292 Imported 1 tasks successfully.
2293 Here are the imported tasks.
2295 $ task new limit:2
2297 ID Project Pri Due Active Age Description
2299 -- ------- --- ---------- ------ -----
2300 ------------------------------------
2301 11 work H 8/15/2010 9 wks Visit http://taskwar‐
2302 rior.org
2303 10 1 min Remember to read the task
2304 man page
2305 9 tasks, 2 shown
2307
2310 You'll find a quick reference page built in, with the 'help' command,
2311 or perhaps you'll want to take a look at the several man pages
2312 installed.
2313 $ task help
2315 ...
2316
2319 task was written by P. Beckingham <paul@beckingham.net>.
2320 Copyright (C) 2006 - 2011 P. Beckingham
2321 This man page was originally written by Federico Hernandez, and has
2323 been modified and supplemented by Paul Beckingham.
2324 task is distributed under the GNU General Public License. See
2326 http://www.gnu.org/licenses/gpl-2.0.txt for more information.
2327
2330 task(1), taskrc(5), task-faq(5), task-color(5), task-sync(5)
2331 For more information regarding task, the following may be referenced:
2333 The official site at
2336 <http://taskwarrior.org>
2337 The official code repository at
2340 <git://tasktools.org/task.git/>
2341 You can contact the project by writing an email to
2344 <support@taskwarrior.org>
2345
2348 Bugs in task may be reported to the issue-tracker at
2349 <http://taskwarrior.org>
2350task 1.9.4 2011-03-03 task-tutorial(5)