1task(1) User Manuals task(1)
2
6 task - A command line todo manager.
7
10 task [subcommand] [args]
11
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 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
30 add [tags] [attrs] description
31 Adds a new task to the task list.
32 log [tags] [attrs] description
35 Adds a new task that is already completed, to the task list.
36 annotate ID description
39 Adds an annotation to an existing task.
40 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 info ID
50 Shows all data and metadata for the specified task.
51 ID With an ID but no specific command, taskwarrior runs the "info"
54 command.
55 undo Reverts the most recent action. Obeys the confirmation setting.
58 shell Launches an interactive shell with all the task commands avail‐
61 able.
62 duplicate ID [tags] [attrs] [description]
65 Duplicates the specified task and allows modifications.
66 delete ID
69 Deletes the specified task from task list.
70 start ID
73 Marks the specified task as started.
74 stop ID
77 Removes the start time from the specified task.
78 done ID [tags] [attrs] [description]
81 Marks the specified task as done.
82 projects
85 Lists all project names that are currently used by pending
86 tasks, and the number of tasks for each.
87 tags Show a list of all tags used. Any special tags used are high‐
90 lighted.
91 summary
94 Shows a report of task status by project.
95 timesheet [weeks]
98 Shows a weekly report of tasks completed and started.
99 history
102 Shows a report of task history by month. Alias to his‐
103 tory.monthly.
104 history.annual
107 Shows a report of task history by year.
108 ghistory
111 Shows a graphical report of task status by month. Alias to
112 ghistory.monthly.
113 ghistory.annual
116 Shows a graphical report of task status by year.
117 burndown.daily
120 Shows a graphical burndown chart, by day.
121 burndown.weekly
124 Shows a graphical burndown chart, by week.
125 burndown.monthly
128 Shows a graphical burndown chart, by month.
129 calendar [ y | due [y] | month year [y] | year ]
132 Shows a monthly calendar with due tasks marked.
133 stats Shows task database statistics.
136 import file
139 Imports tasks in a variety of formats, from file or URL.
140 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 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 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 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 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 ssh://[user@]host.xz[:port]/path/to/undo.data
169 rsync://[user@]host.xz[:port]/path/to/undo.data
171 [user@]host.xz:path/to/undo.data
173 /path/to/local/undo.data
175 You can set aliases for frequently used URLs in the .taskrc.
177 push URL
180 Pushes the task database to a remote another location for dis‐
181 tributing the changes made by the merge command.
182 (See annotations above for valid URL syntaxes.)
184 pull URL
187 Overwrites the task database with those files found at the URL.
188 (See annotations above for valid URL syntaxes.)
190 color [sample | legend]
193 Displays all possible colors, a named sample, or a legend con‐
194 taining all currently defined colors.
195 count [filter]
198 Displays only a count of tasks matching the filter.
199 version
202 Shows the taskwarrior version number
203 help Shows the long usage text.
206 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 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 task config name value
221 This command sets a blank value. This has the effect of sup‐
223 pressing any default value:
224 task config name ''
226 Finally, this command removes any 'name=...' entry from the
228 .taskrc file:
229 task config name
231
234 ID [tags] [attrs] [description]
235 Modifies the existing task with provided information.
236 ID /from/to/
239 Performs one substitution on task description and annotation for
240 fixing mistakes.
241 If either 'from' or 'to' contain spaces, you will need to put
243 quotes around the whole thing.
244 ID /from/to/g
247 Performs all substitutions on task description and annotation
248 for fixing mistakes.
249 If either 'from' or 'to' contain spaces, you will need to put
251 quotes around the whole thing.
252 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 append [tags] [attrs] description
262 Appends information to an existing task.
263 prepend [tags] [attrs] description
266 Prepends information to an existing task.
267
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 active [filter]
277 Shows all tasks matching the filter that are started but not
278 completed.
279 all [filter]
282 Shows all tasks matching the filter, including parents of recur‐
283 ring tasks.
284 completed [filter]
287 Shows all tasks matching the filter that are completed.
288 minimal [filter]
291 Provides a minimal listing of tasks matching the filter.
292 ls [filter]
295 Provides a short listing of tasks matching the filter.
296 list [filter]
299 Provides a more detailed listing of tasks matching the filter.
300 long [filter]
303 Provides the most detailed listing of tasks with filter.
304 newest [filter]
307 Shows the newest tasks with filter.
308 oldest [filter]
311 Shows the oldest tasks with filter
312 overdue [filter]
315 Shows all incomplete tasks matching the filter that are beyond
316 their due date.
317 recurring [filter]
320 Shows all recurring tasks matching the filter.
321 waiting [filter]
324 Shows all waiting tasks matching the filter.
325 blocked [filter]
328 Shows all blocked tasks, that are dependent on other tasks,
329 matching the filter.
330 unblocked [filter]
333 Shows all tasks that are not blocked by dependencies, matching
334 the filter.
335 next [filter]
338 Shows all tasks with upcoming due dates matching the filter.
339
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 task list project:Home
347 You can specify multiple filters, each of which further restrict the
349 results:
350 task list project:Home +weekend garden
352 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 description.contains:garden
358 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
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 +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 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 +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 project:<project-name>
391 Specifies the project to which a task is related to.
392 priority:H|M|L|N
395 Specifies High, Medium, Low and No priority for a task.
396 due:<due-date>
399 Specifies the due-date of a task.
400 recur:<frequency>
403 Specifies the frequency of a recurrence of a task.
404 until:<end-date-of-recurrence>
407 Specifies the Recurrence end-date of a task.
408 fg:<color-spec>
411 Specifies foreground color.
412 bg:<color-spec>
415 Specifies background color.
416 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 wait:<wait-date>
426 Date until task becomes pending.
427 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
437 Attribute modifiers improve filters. Supported modifiers are:
438 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 For example:
453 task list due.before:eom priority.not:L
455 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 The after modifier is the inverse of the before modifier.
463 The none modifier requires that the attribute does not have a value.
465 For example:
466 task list priority:
468 task list priority.none:
469 are equivalent, and list tasks that do not have a priority.
471 The any modifier requires that the attribute has a value, but any value
473 will suffice.
474 The is modifier requires an exact match with the value.
476 The isnt modifier is the inverse of the is modifier.
478 The has modifier is used to search for a substring, such as:
480 task list description.has:foo
482 task list foo
483 which are equivalent and will return any task that has 'foo' in the
485 description or annotations.
486 The hasnt modifier is the inverse of the has modifier.
488 The startswith modifier matches against the left, or beginning of an
490 attribute, such that:
491 task list project.startswith:H
493 task list project:H
494 are equivalent and will match any project starting with 'H'.
496 The endswith modifier matches against the right, or end of an
498 attribute.
499 The word modifier requires that the attribute contain the whole word
501 specified, such that this:
502 task list description.word:bar
504 will match the description 'foo bar baz' but does not match 'dog food'.
506 The noword modifier is the inverse of the word modifier.
508
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 Exact specification
519 task ... due:7/14/2008
520 Relative wording
523 task ... due:today
524 task ... due:yesterday
525 task ... due:tomorrow
526 Day number with ordinal
529 task ... due:23rd
530 task ... due:3wks
531 task ... due:1day
532 task ... due:9hrs
533 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 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 At some point or later
554 task ... wait:later
555 task ... wait:someday
556 This sets the wait date to 1/18/2038.
558 Next occurring weekday
561 task ... due:fri
562 FREQUENCIES
565 Recurrence periods. Taskwarrior supports several ways of specifying the
566 frequency of recurring tasks.
567 daily, day, 1d, 2d, ...
570 Every day or a number of days.
571 weekdays
574 Mondays, Tuesdays, Wednesdays, Thursdays, Fridays and
575 skipping weekend days.
576 weekly, 1w, 2w, ...
579 Every week or a number of weeks.
580 biweekly, fortnight
583 Every two weeks.
584 quarterly, 1q, 2q, ...
587 Every three months, a quarter, or a number of quarters.
588 semiannual
591 Every six months.
592 annual, yearly, 1y, 2y, ...
595 Every year or a number of years.
596 biannual, biyearly, 2y
599 Every two years.
600
604 All taskwarrior commands may be abbreviated as long as a unique prefix
605 is used, for example:
606 $ task li
608 is an unambiguous abbreviation for
610 $ task list
612 but
614 $ task l
616 could be list, ls or long.
618
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 $ task add "quoted ' quote"
627 $ task add escaped \' quote
628 The argument -- (a double dash) tells taskwarrior to treat all other
630 args as description:
631 $ task add -- project:Home needs scheduling
633 In other situations, the shell sees spaces and breaks up arguments.
635 For example, this command:
636 $ task 123 /from this/to that/
638 is broken up into several arguments, which is corrected with quotes:
640 $ task 123 "/from this/to that/"
642
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 task rc:<path-to-alternate-file>
651 Specifies an alternate configuration file.
652 task rc.<name>:<value> ...
655 Specifies individual configuration file overrides.
656
659 For examples please see the task tutorial man page at
660 man task-tutorial
662 or the online documentation starting at
664 <http://taskwarrior.org/wiki/taskwarrior/Simple>
666
669 ~/.taskrc User configuration file - see also taskrc(5).
670 ~/.task The default directory where task stores its data files. The
673 location
674 can be configured in the configuration file.
675 ~/.task/pending.data The file that contains the tasks that are not yet
678 done.
679 ~/.task/completed.data The file that contains the completed "done"
682 tasks.
683 ~/.task/undo.data The file that contains the information to the "undo"
686 command.
687
690 Taskwarrior was written by P. Beckingham <paul@beckingham.net>.
691 Copyright (C) 2006 - 2011 P. Beckingham
692 This man page was originally written by P.C. Shyamshankar, and has been
694 modified and supplemented by Federico Hernandez.
695 Thank also to T. Charles Yun.
697 Taskwarrior is distributed under the GNU General Public License. See
699 http://www.gnu.org/licenses/gpl-2.0.txt for more information.
700
703 taskrc(5), task-tutorial(5), task-faq(5), task-color(5), task-sync(5)
704 For more information regarding taskwarrior, the following may be refer‐
706 enced:
707 The official site at
710 <http://taskwarrior.org>
711 The official code repository at
714 <git://tasktools.org/task.git/>
715 You can contact the project by writing an email to
718 <support@taskwarrior.org>
719
722 Bugs in taskwarrior may be reported to the issue-tracker at
723 <http://taskwarrior.org>
724task 1.9.4 2011-03-03 task(1)