[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 -------------------------------------------------------

