[Make window 116x32 for movie recording, light text, dark background] This is the script from which a 1.9.3-specific movie will be made. On the left are the typed commands, and on the right is the voice track. It is intended that the left and right be combined and the result will be a new task-tutorial.5 man page. ---------------------------------------- Intro ----------------------------------------------------- http://taskwarrior.org Hello, and welcome to this taskwarrior version 1.9.3 demo. I'm going to show you over 100 features, so don't blink, or you'll miss some. Even experienced users are going to learn *something*. I will start off with basic usage, and proceed to more sophisticated commands as we go along. ---------------------------------------- Basic Usage ----------------------------------------------- Let's get started. We're planning a party, and there is a lot of work to do, so let's capture these tasks. task add Select a free weekend in August First decide 'when'. task add Select and book a venue Then decide 'where'. task add Come up with a guest list Then decide 'who'. task add Mail invitations Let's send out nice invitations. task add Select a caterer And a caterer. task list Let's take a look. Good. task log Order a special cake Now I've already ordered a cake, so rather than 'add' this, I'm going to 'log' it. This just means that I want to keep track of the task, but I've already done it. It saves me a step. task 4 duplicate /Mail/Design/ As for those invitations, I'm going to need to design them task 4 dup /Mail/Print/ first. And I'm also going to need print them. Here we are task list duplicating a task and making a substitution. Notice how the commands can be abbreviated, provided they are still unique. task 3 done That looks good - but now I think of it, I already have my task list guest list, so I can mark that one as done. And that's basic usage, and you already know enough to be productive using taskwarrior. If you stopped here, you would be perfectly able to manage your task list. But if you want to see what it can really do, keep watching... ---------------------------------------- Projects -------------------------------------------------- task add Pay teh rent on teh 31st Remember to pay the rent at the end of the month. Oh, task 7 /teh/teh/g that was sloppy, but it can be fixed with a global task list substitution. task 7 project:home We can now use projects to separate home chores from the party preparation. Let's assign that last task to the 'home' project. Note that a task may only belong to one project. task 1-6 project:party And we will put those first six tasks in the 'party' project. See how we specify a range of tasks? Taskwarrior will want to confirm bulk changes like this, but we'll accept all changes here. task projects Now that we have multiple projects, as shown here, we can task list project:home use project as a filter for the list report. You can see task li pro:par again that we can abbreviate 'list' and 'project', but when we abbreviate 'party', we are filtering all the projects that begin with 'par'. ---------------------------------------- Priorities ------------------------------------------------ task 1-3,5 priority:H Priorities are another way to organize tasks. You can use task list priority values of high, medium and low, and taskwarrior knows these as H, M or L. task 3 pri: You can remove priorities by specifying a blank value. ---------------------------------------- Tags ------------------------------------------------------ task list A task may only have one project, but it may have any number of tags, which are just single words associated with the task. task 3,5,6 +mall I can go to the print shop at the mall, and do all the invitation tasks, so let's tag them all. task long The long report shows tags, too, task list +mall and I can use tags as a filter to any report too. task 3 -mall I made a mistake - I can't mail out the invitations at the mall, so let's remove that tag. ---------------------------------------- Modifications --------------------------------------------- task 7 Pay rent at the end of the month Task 7 is not worded correctly, so I can modify that by specifying a task ID and a new description. This is also considered a bulk change, and so requires confirmation. task add music We'll need music. task 8 prepend Select some I can prepend to that. task 8 append for after dinner I can append to that. task list task edit I can also go straight into an editor and modify anything. task add Hire a band? <--- Sometimes the command will confuse the shell. In this case, what would happen if there was a file named 'bands' in the current directory? The shell would expand that wildcard, so to avoid that, you can... task add Hire a band\? <--- escape the wildcard... task add "Hire a band?" <--- or quote the whole description... task add -- Hire a band\? +dj You can also use the minus minus operator which tells taskwarrior to stop being clever and interpret the rest of the arguments as a task description. Otherwise, that +dj would be interpreted as a tag. task undo We don't need a band, so the easiest way to get rid of that task is to undo the last change. Taskwarrior has a complete undo stack, so you can undo all the way back to the beginning. task 1 delete The undo operation gets rid of the task completely, but I task undo could also have just deleted the task, then the deletion itself would be tracked, and also undoable. ---------------------------------------- Info ------------------------------------------------------ task 1 info During that undo operation, taskwarrior displayed metadata task 1 that is associated with the task. You can display this with the info command, and its shortcut. task stats There are also statistics that taskwarrior gathers, which I can display. ---------------------------------------- Annotations ----------------------------------------------- task 1 annotate the 12th looks good Annotations are little notes that can be added to a task. task 1 annotate or the 13th There can be any number, and each has a time stamp. task list task list rc.annotations:full You can choose to display annotations in different ways. task list rc.annotations:sparse task list rc.annotations:none task 1 denotate 13th Annotations can be removed by providing a matching pattern. task list ---------------------------------------- Configuration --------------------------------------------- task show There is a 'show' command, that is used to display the active configuration. There are hundreds of settings that can be changed, and every one has a sensible default. man taskrc If you want a complete list of all the settings and their meanings, read the man page. task config answer 42 The 'config' command is used to modify the settings, and in this case the configuration variable 'answer' is given the value of 42. task show answer The 'show' command indicates that the value was changed, task config answer and also that the variable is unrecognized. The show command performs a detailed check on your configuration, and alerts you to several kinds of problem. The config command can also remove a value. task rc.report.list.sort=description+ list A very powerful feature is the ability to override the configuration variables temporarily. Here I am requesting an ascending sort on the description field only. ---------------------------------------- Defaults -------------------------------------------------- task config default.command list There is a default command, which can be set to anything, task in this case it is set to the 'list' report. Then running taskwarrior with no command name runs the default command. task config default.priority H I can also specify a default priority and project, which task config default.project Work means that any tasks added will use them, unless an task add New task alternative is provided. task list task undo Let's just revert those changes, to clean up. task config default.priority task config default.project ---------------------------------------- Aliases --------------------------------------------------- task config alias.zzz list You can create aliases to effectively rename commands. task zzz task z You can abbreviate those, too. ---------------------------------------- Color ----------------------------------------------------- task config color on All the examples so far have been shown with color turned task list off. How about some color? What you see is the result of a set of color rules being applied to the tasks. There is a hierarchy of color rules that colorize a task based on the metadata task 1 "bg:on red" Here is an example of an explicit override to the color task list rules where a specific task is given a red background. task 1 bg: Note that the quotes are necessary, otherwise the shell will consider "bg:on" and "red" to be separate arugments. task color Taskwarrior supports 256 colors on certain terminal emulators, and this shows the range of colors available. task color white on red This is how to show a color sample. task color legend Or samples of all the active color settings. Themes are a simple way to use coordinated color schemes so by including a color theme into the configuration file, you can see some striking effects. A blue theme. # include /usr/local/share/doc/task/rc/dark-blue-256.theme vi ~/.taskrc task color legend task list A red theme. # include /usr/local/share/doc/task/rc/dark-red-256.theme vi ~/.taskrc task color legend task list A general dark theme. # include /usr/local/share/doc/task/rc/dark-256.theme vi ~/.taskrc task list Here is are two color rules that specify a dark blue background for all tasks that are part of the 'party' project, and uses bold to identify any tasks with the keyword 'invitations' in the description. task "rc.color.project.party=on rgb001" rc.color.keyword.invit=bold list man task-color There is a man page with a writeup of all the color capabilities. ---------------------------------------- Active tasks ---------------------------------------------- task 2 start I'm selecting a venue, so let's indicate that task 2 is task list active by starting it. See how active tasks are affected by the color rules. task active There is an active report that shows only active tasks, and task 2 stop you can mark any active task as inactive, by stopping it. task config journal.time on (y) There is a journalling feature that records the start and task config dateformat.annotation 'Y/m/d H:N' (y) task 2 start stop times as annotations. We'll turn that on, and add task list venue the time to the annotation date format. task 2 stop task list venue ---------------------------------------- Due dates ------------------------------------------------- task 1 due:7/31/2010 Due dates can be specified as dates... task 1 due:2wks as some distance into the future... task 1 due:-2wks or past... task 1 due:eom or by mnemonic (end of month)... task 2 due:8th or by ordinal... task 2 due:sunday or by day of week... task 5 due:eow task list Some of these dates are in the past, so now you see there task overdue are overdue tasks. Due dates have different colors for due, imminent, today and overdue values. task rc.dateformat.report:Y-M-DTH:N:SZ list You can also choose the format - for input and output. ---------------------------------------- Calendar -------------------------------------------------- task calendar When tasks have due dates, you can see them on the calendar. vi ~/.taskrc # include /usr/local/share/doc/task/rc/holidays-US.rc task calendar Taskwarrior provides sample holiday files. You can create your own, or use one of the samples to show holidays on the calendar. task cal 2010 You can see the whole year. task rc.calendar.details:full cal You can see the tasks with due dates also. task rc.calendar.holidays:full cal And you can see the holidays. ---------------------------------------- Recurrence ------------------------------------------------ task 7 info Remember the task we added to pay the rent? We're going to task 7 due:eom recur:monthly need to do that every month. Recurring tasks allow us to task 7 set up a single task that keeps coming back, just as you'd expect. task 7 until:eoy You can also limit the extent of the recurrence. Let's make sure the task doesn't recur after the lease ends. task recurring And there is a recurring report that shows you only the recurring tasks. To illustrate a point, let's set up a recurring annual task as a reminder to pay taxes, and put the due date in the past. This will cause task to fill in the gaps, and create a series of severely overdue tasks. task add Pay taxes due:4/15/2007 recur:yearly task long task 11 delete # y y Deletions to recurring tasks can be escalated to include all task list the recurrences of a task. ---------------------------------------- Shell ----------------------------------------------------- task shell You can use the shell command to create a more immersive task> projects environment. Any task command you run outside the shell task> tags can also be run inside the shell, without the need to prefix task> list every command with "task". task> quit ---------------------------------------- Special Tags ---------------------------------------------- task 6 +nocolor You've seen tags, but there are also 'special tags' that task list have effects on individual tasks. The 'nocolor' special tag causes the color rules to be bypassed. task tags Special tags are highlighted by the 'tags' command. task 6 -nocolor There are others - the 'nonag' special tag prevents the generation of nag messages when you work on low priority tasks when there are more important ones. The 'nocal' special tag will prevent a task from appearing on the calendar. ---------------------------------------- Waiting --------------------------------------------------- task add Look for new apartment due:eoy When you have a task with a due date that is far out into task list the future, you may want to hide that task for a while. task 10 wait:12/1/2010 You can provide a wait date for a task, and it will remain task list hidden until that date. It will no longer be cluttering task waiting your task list, but it is still there, and visible using the 'waiting' report. When the wait date comes, the task will just pop back into the list. task add Do something in a few seconds To illustrate this, let's set up a task with a very short task 11 wait:5s wait time of five seconds. task list It's gone. (sleep 5) We wait for 5 seconds... task list And it's back. task 11 rc.confirmation:no delete And now it's deleted. ---------------------------------------- Dependencies ---------------------------------------------- task list pro:party Taskwarrior supports dependencies. Let's take a look at the party planning tasks, and assign dependencies. task 3 depends:6 Let's see. I can't mail invitations until they are printed. task 6 dep:5 I can't print them until I design them. task 2 dep:1 I need to select a weekend before a location. task 5 dep:1,2 Design depends on location and weekend. task 4 dep:1 And the caterer needs to know where. task long pro:party All my tasks are blocked except task 1. That makes sense. task 5 dep:-1 Hmm, that double dependency isn't right. task blocked Here are the blocked tasks. task unblocked and the opposite, the unblocked tasks. task 1 info If we look at task 1 closely, we can see that it is blocking task 2 info 2 and 4. And if we look at task 2, we see that it is blocked by 1, and blocking 5. This is called a dependency chain, which is a string of tasks that are all connected not only by their project, but by dependencies. Now we understand that task 1 should be done first, but you may still violate the laws of physics if you wish. Let's complete task 2 and see what happens. task 2 done (y) Taskwarrior realizes what you are doing, and offers to fix task 1 info the dependency chain to reflect what you have done. ---------------------------------------- Reports --------------------------------------------------- task minimal Taskwarrior has a good many reports. There is the bare minimum. task ls The simple. task list The standard. task long The kitchen sink. task all The packrat. task completed Nostalgia. task recurring Groundhog day. task waiting Surprises. task blocked Wedged. task unblocked Unencumbered. task oldest Ancient history. task newest Contemporary. task timesheet Corporate. task next And "what should I work on next?" This one can be useful because it pulls a few of the highest priority tasks from all the projects. It's the report we should all be using. ---------------------------------------- Custom Report --------------------------------------------- You can even define your own custom report. Let's quickly create a custom report - we'll call it foo - and I can choose from a long list of fields to include in the report, but I want to see the ID, the date when I entered the task, and the description. I can specify the labels for those columns, the sort order of the report, and I can filter. cat >> ~/.taskrc report.foo.description=My own report report.foo.columns=id,entry,description report.foo.labels=ID,Entered,Description report.foo.sort=entry+,description+ report.foo.filter=status:pending task help | grep foo Custom reports also show up on the help output. task show report.foo I can inspect the configuration. task foo And they can be run just like the other reports. ---------------------------------------- Charts ---------------------------------------------------- task history The history report gives monthly totals of tasks added, task history.annual completed and deleted. There is also an annual version. task ghistory There is a graphical monthly... task ghistory.annual and annual version. task summary There is a project summary report that shows progress in all the projects. ---------------------------------------- Advanced Filters ------------------------------------------ task list Filters are a very powerful tool. First here is an task list invit unfiltered list, which shows all tasks. Now again, but with the text 'invit', which acts as a filter on the description field. task list description.contains:invit This is the equivalent form using attribute modifiers. In this example we are filtering on descriptions that contain the word fragment. Here we are using the 'contains' modifier, but there are many others. task list desc.word:the All tasks containing the whole word 'the'. See how annotations are also searched? task list desc.noword:invitations Here is a list of all tasks that do not contain the whole word 'invitations'. task list pro:party Here list all tasks in the 'party' project. task list pro.is:party And the full equivalent. task list pro.not:party Here list tasks that are not in the 'party' project. I could have also used 'isnt' here - there are several synonyms for modifiers, so that the filter can be written so that it reads naturally. task list pro:party pri.over:L Here the 'over' modifier is filtering on priorities that sort higher than 'Low', and also filtering on the 'party' project. There are two terms in this filter. task list pro:party limit:2 Same again, but only show me the first two tasks. task list limit:page Now all tasks, but just show the first page of tasks. I don't have a page full of tasks here, but you get the idea. task all status:pending Now you can see how some of the built-in reports work. The 'list' report is just all tasks, filtered so that only the pending tasks are shown. task all status:waiting The 'waiting' report is similarly defined. ---------------------------------------- Import/Export --------------------------------------------- task export.csv You can export your tasks. Here you see all tasks being exported in CSV format. task export.csv venue Let's just export one task in CSV format... task export.vcalendar venue Or in VCalendar format... task export.yaml venue Or YAML. cat file.text I can also import. Here I am importing simple lines of task import file.text text. Taskwarrior recognizes the format and confirms. cat file.yaml Here is a YAML example. Taskwarrior can read several task import file.yaml formats, including old versions of its data files. Using YAML, you can round-trip the data without loss. task new limit:2 Here are the imported tasks. ---------------------------------------- Help ------------------------------------------------------ task help You'll find a quick reference page built in, with the 'help' man task command, or perhaps you'll want to take a look at the several man taskrc man pages installed. This demo has superficially shown man task-color many features which have more capability and depth which you can find in the man pages, and online. man task-tutorial This screencast is actually just a recording of me going through the tutorial. man task-faq Some frequently asked questions are answered here. man task-sync You've patiently watched this whole movie, so here's your reward - taskwarrior 1.9.3 has network synchronization features, for sharing tasks across computers. But this is just a teaser - synch will be shown in the next movie. ---------------------------------------- Wrap up --------------------------------------------------- task version And that's it. Don't forget to take a look at taskwarrior.org. Thank you for watching. ---------------------------------------- End -------------------------------------------------------