1task(1) User Manuals task(1)
2
3
4
6 task - A command line todo manager.
7
8
10 task [subcommand] [args]
11
12
14 Taskwarrior is a command line todo list manager. It maintains a list of
15 tasks that you want to do, allowing you to add/remove, and otherwise
16 manipulate them. Task has a rich list of subcommands that allow you to
17 do various things with it.
18
19 At the core, taskwarrior is a list processing program. You add text and
20 additional related parameters and redisplay the information in a nice
21 way. It turns into a todo list program when you add due dates and
22 recurrence. It turns into an organized todo list program when you add
23 priorities, tags (one word descriptors), project groups, etc. Taskwar‐
24 rior turns into an organized to do list program when you modify the
25 configuration file to have the output displayed the way you want to see
26 it.
27
28
30 add [tags] [attrs] description
31 Adds a new task to the task list.
32
33
34 log [tags] [attrs] description
35 Adds a new task that is already completed, to the task list.
36
37
38 annotate ID description
39 Adds an annotation to an existing task.
40
41
42 denotate ID description
43 Deletes an annotation for the specified task. If the provided
44 description matches an annotation exactly, the corresponding
45 annotation is deleted. If the provided description matches anno‐
46 tations partly, the first partly matched annotation is deleted.
47
48
49 info ID
50 Shows all data and metadata for the specified task.
51
52
53 ID With an ID but no specific command, taskwarrior runs the "info"
54 command.
55
56
57 undo Reverts the most recent action. Obeys the confirmation setting.
58
59
60 shell Launches an interactive shell with all the task commands avail‐
61 able.
62
63
64 duplicate ID [tags] [attrs] [description]
65 Duplicates the specified task and allows modifications.
66
67
68 delete ID
69 Deletes the specified task from task list.
70
71
72 start ID
73 Marks the specified task as started.
74
75
76 stop ID
77 Removes the start time from the specified task.
78
79
80 done ID [tags] [attrs] [description]
81 Marks the specified task as done.
82
83
84 projects
85 Lists all project names that are currently used by pending
86 tasks, and the number of tasks for each.
87
88
89 tags Show a list of all tags used. Any special tags used are high‐
90 lighted.
91
92
93 summary
94 Shows a report of task status by project.
95
96
97 timesheet [weeks]
98 Shows a weekly report of tasks completed and started.
99
100
101 history
102 Shows a report of task history by month. Alias to his‐
103 tory.monthly.
104
105
106 history.annual
107 Shows a report of task history by year.
108
109
110 ghistory
111 Shows a graphical report of task status by month. Alias to
112 ghistory.monthly.
113
114
115 ghistory.annual
116 Shows a graphical report of task status by year.
117
118
119 burndown.daily
120 Shows a graphical burndown chart, by day.
121
122
123 burndown.weekly
124 Shows a graphical burndown chart, by week.
125
126
127 burndown.monthly
128 Shows a graphical burndown chart, by month.
129
130
131 calendar [ y | due [y] | month year [y] | year ]
132 Shows a monthly calendar with due tasks marked.
133
134
135 stats Shows task database statistics.
136
137
138 import file
139 Imports tasks in a variety of formats, from file or URL.
140
141
142 export Exports all tasks in the default format. This is an alias to
143 the command export.yaml. Redirect the output to a file, if you
144 wish to save it, or pipe it to another command.
145
146
147 export.csv
148 Exports all tasks in CSV format. Redirect the output to a file,
149 if you wish to save it, or pipe it to another command.
150
151
152 export.ical
153 Exports all tasks in iCalendar format. Redirect the output to a
154 file, if you wish to save it, or pipe it to another command.
155
156
157 export.yaml
158 Exports all tasks in YAML 1.1 format. Redirect the output to a
159 file, if you wish to save it, or pipe it to another command.
160
161
162 merge URL
163 Merges two task databases by comparing the modifications that
164 are stored in the undo.data files. The location of the second
165 undo.data file must be passed on as argument. URL may have the
166 following syntaxes:
167
168 ssh://[user@]host.xz[:port]/path/to/undo.data
169
170 rsync://[user@]host.xz[:port]/path/to/undo.data
171
172 [user@]host.xz:path/to/undo.data
173
174 /path/to/local/undo.data
175
176 You can set aliases for frequently used URLs in the .taskrc.
177
178
179 push URL
180 Pushes the task database to a remote another location for dis‐
181 tributing the changes made by the merge command.
182
183 (See annotations above for valid URL syntaxes.)
184
185
186 pull URL
187 Overwrites the task database with those files found at the URL.
188
189 (See annotations above for valid URL syntaxes.)
190
191
192 color [sample | legend]
193 Displays all possible colors, a named sample, or a legend con‐
194 taining all currently defined colors.
195
196
197 count [filter]
198 Displays only a count of tasks matching the filter.
199
200
201 version
202 Shows the taskwarrior version number
203
204
205 help Shows the long usage text.
206
207
208 show [all | substring]"
209 Shows all the current settings in the taskwarrior configuration
210 file. If a substring is specified just the settings containing
211 that substring will be displayed.
212
213
214 config [name [value | '']]
215 Add, modify and remove settings directly in the taskwarrior con‐
216 figuration. This command either modifies the 'name' setting
217 with a new value of 'value', or adds a new entry that is equiva‐
218 lent to 'name=value':
219
220 task config name value
221
222 This command sets a blank value. This has the effect of sup‐
223 pressing any default value:
224
225 task config name ''
226
227 Finally, this command removes any 'name=...' entry from the
228 .taskrc file:
229
230 task config name
231
232
234 ID [tags] [attrs] [description]
235 Modifies the existing task with provided information.
236
237
238 ID /from/to/
239 Performs one substitution on task description and annotation for
240 fixing mistakes.
241
242 If either 'from' or 'to' contain spaces, you will need to put
243 quotes around the whole thing.
244
245
246 ID /from/to/g
247 Performs all substitutions on task description and annotation
248 for fixing mistakes.
249
250 If either 'from' or 'to' contain spaces, you will need to put
251 quotes around the whole thing.
252
253
254 edit ID
255 Launches an editor to let you modify all aspects of a task
256 directly. In general, this is not the recommended method of
257 modifying tasks, but is provided for exceptional circumstances.
258 Use carefully.
259
260
261 append [tags] [attrs] description
262 Appends information to an existing task.
263
264
265 prepend [tags] [attrs] description
266 Prepends information to an existing task.
267
268
270 A report is a listing of information from the task database. There are
271 several reports currently predefined in taskwarrior. The output and
272 sort behavior of these reports can be configured in the configuration
273 file. See also the man page taskrc(5).
274
275
276 active [filter]
277 Shows all tasks matching the filter that are started but not
278 completed.
279
280
281 all [filter]
282 Shows all tasks matching the filter, including parents of recur‐
283 ring tasks.
284
285
286 completed [filter]
287 Shows all tasks matching the filter that are completed.
288
289
290 minimal [filter]
291 Provides a minimal listing of tasks matching the filter.
292
293
294 ls [filter]
295 Provides a short listing of tasks matching the filter.
296
297
298 list [filter]
299 Provides a more detailed listing of tasks matching the filter.
300
301
302 long [filter]
303 Provides the most detailed listing of tasks with filter.
304
305
306 newest [filter]
307 Shows the newest tasks with filter.
308
309
310 oldest [filter]
311 Shows the oldest tasks with filter
312
313
314 overdue [filter]
315 Shows all incomplete tasks matching the filter that are beyond
316 their due date.
317
318
319 recurring [filter]
320 Shows all recurring tasks matching the filter.
321
322
323 waiting [filter]
324 Shows all waiting tasks matching the filter.
325
326
327 blocked [filter]
328 Shows all blocked tasks, that are dependent on other tasks,
329 matching the filter.
330
331
332 unblocked [filter]
333 Shows all tasks that are not blocked by dependencies, matching
334 the filter.
335
336
337 next [filter]
338 Shows all tasks with upcoming due dates matching the filter.
339
340
342 A filter is a set of search criteria that the report applies before
343 displaying the results. For example, to list all tasks belonging to
344 the 'Home' project:
345
346 task list project:Home
347
348 You can specify multiple filters, each of which further restrict the
349 results:
350
351 task list project:Home +weekend garden
352
353 This example applies three filters: the 'Home' project, the 'weekend'
354 tag, and the description or annotations must contain the characters
355 'garden'. In this example, 'garden' is translated internally to:
356
357 description.contains:garden
358
359 as a convenient shortcut. The 'contains' here is an attribute modi‐
360 fier, which is used to exert more control over the filter than simply
361 absence or presence. See 'ATTRIBUTE MODIFIERS' for a complete list of
362 modifiers.
363
364
366 ID Tasks can be specified uniquely by IDs, which are simply the
367 index of the task in a report. Be careful, as the IDs of tasks
368 may change after a modification to the database. Always run a
369 report to check you have the right ID for a task. IDs can be
370 given to task as a sequences, for example,
371 task del 1,4-10,19
372
373
374 +tag|-tag
375 Tags are arbitrary words associated with a task. Use + to add a
376 tag and - to remove a tag from a task. A task can have any quan‐
377 tity of tags.
378
379 Certain tags (called 'special tags'), can be used to affect the
380 way tasks are treated. For example, is a task has the special
381 tag 'nocolor', then it is exempt from all color rules. The sup‐
382 ported special tags are:
383
384 +nocolor Disable color rules processing for this task
385 +nonag Completion of this task suppresses all nag mes‐
386 sages
387 +nocal This task will not appear on the calendar
388
389
390 project:<project-name>
391 Specifies the project to which a task is related to.
392
393
394 priority:H|M|L|N
395 Specifies High, Medium, Low and No priority for a task.
396
397
398 due:<due-date>
399 Specifies the due-date of a task.
400
401
402 recur:<frequency>
403 Specifies the frequency of a recurrence of a task.
404
405
406 until:<end-date-of-recurrence>
407 Specifies the Recurrence end-date of a task.
408
409
410 fg:<color-spec>
411 Specifies foreground color.
412
413
414 bg:<color-spec>
415 Specifies background color.
416
417
418 limit:<number-of-rows>
419 Specifies the desired number of tasks a report should show, if a
420 positive integer is given. The value 'page' may also be used,
421 and will limit the report output to as many lines of text as
422 will fit on screen. This defaults to 25 lines.
423
424
425 wait:<wait-date>
426 Date until task becomes pending.
427
428
429 depends:<id1,id2 ...>
430 Declares this task to be dependent on id1 and id2. This means
431 that the tasks id1 and id2 should be completed before this task.
432 Consequently, this task will then show up on the 'blocked'
433 report.
434
435
437 Attribute modifiers improve filters. Supported modifiers are:
438
439 before (synonyms under, below)
440 after (synonyms over, above)
441 none
442 any
443 is (synonym equals)
444 isnt (synonym not)
445 has (synonym contains)
446 hasnt
447 startswith (synonym left)
448 endswith (synonym right)
449 word
450 noword
451
452 For example:
453
454 task list due.before:eom priority.not:L
455
456 The before modifier is used to compare values, preserving semantics, so
457 project.before:B list all projects that begin with 'A'. Priority 'L'
458 is before 'M', and due:2011-01-01 is before due:2011-01-02. The syn‐
459 onyms 'under' and 'below' are included to allow filters that read more
460 naturally.
461
462 The after modifier is the inverse of the before modifier.
463
464 The none modifier requires that the attribute does not have a value.
465 For example:
466
467 task list priority:
468 task list priority.none:
469
470 are equivalent, and list tasks that do not have a priority.
471
472 The any modifier requires that the attribute has a value, but any value
473 will suffice.
474
475 The is modifier requires an exact match with the value.
476
477 The isnt modifier is the inverse of the is modifier.
478
479 The has modifier is used to search for a substring, such as:
480
481 task list description.has:foo
482 task list foo
483
484 which are equivalent and will return any task that has 'foo' in the
485 description or annotations.
486
487 The hasnt modifier is the inverse of the has modifier.
488
489 The startswith modifier matches against the left, or beginning of an
490 attribute, such that:
491
492 task list project.startswith:H
493 task list project:H
494
495 are equivalent and will match any project starting with 'H'.
496
497 The endswith modifier matches against the right, or end of an
498 attribute.
499
500 The word modifier requires that the attribute contain the whole word
501 specified, such that this:
502
503 task list description.word:bar
504
505 will match the description 'foo bar baz' but does not match 'dog food'.
506
507 The noword modifier is the inverse of the word modifier.
508
509
511 DATES
512 Taskwarrior reads dates from the command line and displays dates in the
513 reports. The expected and desired date format is determined by the
514 configuration variable dateformat in the taskwarrior configuration
515 file.
516
517
518 Exact specification
519 task ... due:7/14/2008
520
521
522 Relative wording
523 task ... due:today
524 task ... due:yesterday
525 task ... due:tomorrow
526
527
528 Day number with ordinal
529 task ... due:23rd
530 task ... due:3wks
531 task ... due:1day
532 task ... due:9hrs
533
534
535 Start of (work) week (Monday), calendar week (Sunday or Monday),
536 month and year
537 task ... due:sow
538 task ... due:soww
539 task ... due:socw
540 task ... due:som
541 task ... due:soy
542
543
544 End of (work) week (Friday), calendar week (Saturday or Sunday),
545 month and year
546 task ... due:eow
547 task ... due:eoww
548 task ... due:eocw
549 task ... due:eom
550 task ... due:eoy
551
552
553 At some point or later
554 task ... wait:later
555 task ... wait:someday
556
557 This sets the wait date to 1/18/2038.
558
559
560 Next occurring weekday
561 task ... due:fri
562
563
564 FREQUENCIES
565 Recurrence periods. Taskwarrior supports several ways of specifying the
566 frequency of recurring tasks.
567
568
569 daily, day, 1d, 2d, ...
570 Every day or a number of days.
571
572
573 weekdays
574 Mondays, Tuesdays, Wednesdays, Thursdays, Fridays and
575 skipping weekend days.
576
577
578 weekly, 1w, 2w, ...
579 Every week or a number of weeks.
580
581
582 biweekly, fortnight
583 Every two weeks.
584
585
586 quarterly, 1q, 2q, ...
587 Every three months, a quarter, or a number of quarters.
588
589
590 semiannual
591 Every six months.
592
593
594 annual, yearly, 1y, 2y, ...
595 Every year or a number of years.
596
597
598 biannual, biyearly, 2y
599 Every two years.
600
601
602
604 All taskwarrior commands may be abbreviated as long as a unique prefix
605 is used, for example:
606
607 $ task li
608
609 is an unambiguous abbreviation for
610
611 $ task list
612
613 but
614
615 $ task l
616
617 could be list, ls or long.
618
619
621 Some task descriptions need to be escaped because of the shell and the
622 special meaning of some characters to the shell. This can be done
623 either by adding quotes to the description or escaping the special
624 character:
625
626 $ task add "quoted ' quote"
627 $ task add escaped \' quote
628
629 The argument -- (a double dash) tells taskwarrior to treat all other
630 args as description:
631
632 $ task add -- project:Home needs scheduling
633
634 In other situations, the shell sees spaces and breaks up arguments.
635 For example, this command:
636
637 $ task 123 /from this/to that/
638
639 is broken up into several arguments, which is corrected with quotes:
640
641 $ task 123 "/from this/to that/"
642
643
645 Taskwarrior stores its configuration in a file in the user's home
646 directory: ~/.taskrc . The default configuration file can be overridden
647 with
648
649
650 task rc:<path-to-alternate-file>
651 Specifies an alternate configuration file.
652
653
654 task rc.<name>:<value> ...
655 Specifies individual configuration file overrides.
656
657
659 For examples please see the task tutorial man page at
660
661 man task-tutorial
662
663 or the online documentation starting at
664
665 <http://taskwarrior.org/wiki/taskwarrior/Simple>
666
667
669 ~/.taskrc User configuration file - see also taskrc(5).
670
671
672 ~/.task The default directory where task stores its data files. The
673 location
674 can be configured in the configuration file.
675
676
677 ~/.task/pending.data The file that contains the tasks that are not yet
678 done.
679
680
681 ~/.task/completed.data The file that contains the completed "done"
682 tasks.
683
684
685 ~/.task/undo.data The file that contains the information to the "undo"
686 command.
687
688
690 Taskwarrior was written by P. Beckingham <paul@beckingham.net>.
691 Copyright (C) 2006 - 2011 P. Beckingham
692
693 This man page was originally written by P.C. Shyamshankar, and has been
694 modified and supplemented by Federico Hernandez.
695
696 Thank also to T. Charles Yun.
697
698 Taskwarrior is distributed under the GNU General Public License. See
699 http://www.gnu.org/licenses/gpl-2.0.txt for more information.
700
701
703 taskrc(5), task-tutorial(5), task-faq(5), task-color(5), task-sync(5)
704
705 For more information regarding taskwarrior, the following may be refer‐
706 enced:
707
708
709 The official site at
710 <http://taskwarrior.org>
711
712
713 The official code repository at
714 <git://tasktools.org/task.git/>
715
716
717 You can contact the project by writing an email to
718 <support@taskwarrior.org>
719
720
722 Bugs in taskwarrior may be reported to the issue-tracker at
723 <http://taskwarrior.org>
724
725
726
727task 1.9.4 2011-03-03 task(1)