This tutorial assumes you have installed Timewarrior. If not, follow these download and build instructions. This is a lengthy and detailed tutorial. If you wish to learn about Timewarrior in depth, this is the place. If you prefer your information in smaller pieces, use the online docs.

Setup

As a new Timewarrior user, there is no configuration needed. Once you have installed the software, the first time you run it, a data/configuration directory is created for you if necessary, and if you allow this action.

$ timew
Create new database in ~/.timewarrior? (yes/no) yes
There is no active time tracking
$ ▒

You are told that there is no active time tracking, and that's right, because we've done nothing yet.

$ ls -l .timewarrior
data
extensions
timewarrior.cfg
$ ▒

By default a .timewarrior directory is created in your home directory, and contains a sub-directory for data, and another for extensions. There is also an empty configuration file created. Just like Taskwarrior, an empty configuration file means we are using all the default settings. If you want to use an alternate location, you can either symlink it to ~/.timewarrior, or use the TIMEWARRIORDB environment variable to specify any location.

Stopwatch

The most basic tracking can be done by using the stopwatch features. Just like a stopwatch, you start and stop a clock, and you can see the elapsed time. Start the clock when you begin work, and stop it when you are done. First let's see if the clock is running:

$ timew
There is no active timew tracking.
$ ▒ 

No it's not. You can always run timewarrior with no arguments to see if the clock is running, and no data is modified. Let's start the clock.

$ timew start
Tracking
  Started 2016-08-07T20:19:42
  Current                  42
  Total               0:00:00
$ ▒

The clock is now running. In reality there is no clock and all that happened was that the start time was recorded, so don't be concerned about using system resources, as none are being used. Now when we check, we see a summary of the time recorded so far:

$ timew start
Tracking
  Started 2016-08-07T20:19:42
  Current               20:34
  Total               0:00:52
$ ▒

Once our work is complete, we stop the clock, and look at the summary.

$ timew stop
Recorded
  Started 2016-08-07T20:19:42
  Current               21:12
  Total               0:01:30
$
$ timew summary

Wk  Date       Day Tags    Start      End    Time   Total
--- ---------- --- ---- -------- -------- ------- -------
W31 2016-08-07 Sun      20:19:42 20:21:12 0:01:30 0:01:30

                                                  -------
                                                  0:01:30

$ ▒

The summary report shows time that was tracked today by default.

There is a continue command that re-starts the previous tracking, and is useful if you stopped the clock during lunch, or overnight.

$ timew continue
Tracking
  Started 2016-08-07T20:22:06
  Current                  06
  Total               0:01:30
$
$ timew stop
Recorded
  Started 2016-08-07T20:22:06
  Current                  18
  Total               0:01:42
$
$ timew summary

Wk  Date       Day Tags    Start      End    Time   Total
--- ---------- --- ---- -------- -------- ------- -------
W31 2016-08-07 Sun      20:19:42 20:21:12 0:01:30
                        20:22:06 20:22:18 0:00:12 0:01:42

                                                  -------
                                                  0:01:42

$ ▒

See how every time the clock is started, there is a new line in the summary report?

It is important to note that it is possible, and quite likely, that you will start the clock and leave it running by mistake. This is in fact one of the most annoying problems with any time tracking solution that relies on human interaction. While some tools will detect inactivity and stop the clock for you, Timewarrior does not. Instead it deals with this problem in two ways, first by making it easy to correct tracked time, and second by way of exclusions, which we will cover later.

Tags

The examples so far did not use tags. Tags are optional, but when you do make use of tags, you start tracking time spent on different activities.

$ timew start 'Using Tags' Software
Tracking 'Using Tags' Software
  Started 2016-08-07T20:23:08
  Current                  08
  Total               0:00:00
$ ▒

This example is tracking time using two different tags. The first is Using Tags, the second is Software. The first tag is two words, and because of the space between them, the quotes are needed to keep those two words together in one tag. The second tag is a single word and needs no quotes.

$ timew stop
Recorded 'Using Tags' Software
  Started 2016-08-07T20:23:08
  Current                  48
  Total               0:00:40
$
$ timew summary

Wk  Date       Day Tags                    Start      End    Time   Total
--- ---------- --- -------------------- -------- -------- ------- -------
W31 2016-08-07 Sun                      20:19:42 20:21:12 0:01:30
                                        20:22:06 20:22:18 0:00:12
                   Software, Using Tags 20:23:08 20:23:48 0:00:40 0:02:22
                
                                                                  -------
                                                                  0:02:22

$ ▒

You can see that using tags is useful, but optional. Once you are using tags, you can use them to filter reports, such as the summary report.

$ timew summary Software

Wk  Date       Day Tags                    Start      End    Time   Total
--- ---------- --- -------------------- -------- -------- ------- -------
W31 2016-08-07 Sun Software, Using Tags 20:23:08 20:23:48 0:00:40 0:00:40
                
                                                                  -------
                                                                  0:00:40

$ ▒

There is a tags command, which will show you all the tags you have used.

$ timew tags

Tag        Description
---------- -----------
Software   -
Using Tags -

$ ▒

You may wonder how is that ‘Description’ column in the report used? It is the first example of tag metadata, which you can configure.

$ timew config tags.Software.description 'Learning about new software'
Are you sure you want to add 'tags.Software.description' with a value of 'Learning about new software'? (yes/no) yes
Config file ~/.timewarrior/timewarrior.cfg modified
$ ▒

This is not currently used, but does represent how Timewarrior will be extended to include tag metadata in future releases.

Help

Although we have just begun, it is important to mention the built-in help system. Let's look at the help for the continue command.

$ timew help continue

Syntax: timew continue

Resumes tracking the most recently closed interval. For example:

  $ timew track 09am - 10am tag1 tag2
  $ timew continue

The 'continue' command creates a new interval, starting now, and using the tags
'tag1' and 'tag2'

This command is a convenient way to resume work without re-entering the tags.

See also 'start', 'stop'

$ ▒

You can see that the help system contains examples, and introduces new commands and other help topics. From the help text, we learn that the continue command will not only resume tracking but use the same set of tags.

In addition to the built-in help, there is a man page which contains the same information plus a lot more.

$ man timew
timew(1)                          User Manuals                         timew(1)

NAME
       timew - A command line time tracker.

SYNOPSIS    
       timew <command> [<arg> ...]

Historical

We have seen how to use the stopwatch feature, and combine it with tags. Additionally we can record time ex post facto. So to track time I spent earlier in the day (but forgot to record), I use the track command.

$ timew track 9:00 - 11:00 'Outline the tutorial topics'
Recorded
  Started 2016-08-07T09:00:00
  Current            11:00:00
  Total               2:00:00
$ ▒

When Timewarrior sees a time like 9:00 it always assumes it is in the past, because Timewarrior is a tool for recording what you have done or are doing, and is not a forward-looking planning tool. This is the opposite of Taskwarrior, which always looks forward, because tasks are generally going to be completed in the future.

There are other ways to specify time in the past, for example:

$ timew track 9am for    2h   'Outline the tutorial topics'
$ timew track 9am to     11am 'Outline the tutorial topics'
$ timew track 2h  before 11am 'Outline the tutorial topics'
$ ▒

And there are many more, which can be seen in the help system.

$ timew help ranges

timew-ranges(7)                         User Manuals                        timew-ranges(7)



NAME
       timew-ranges - date and time ranges supported by Timewarrior

SYNOPSIS
DESCRIPTION
       An interval defines a block of time that is tracked.
       The syntax for specifying an interval is flexible, and may be one of:
         [from] <date>
         [from] <date> to/- <date>
         [from] <date> for <duration>
         <duration> before/after <date>
         <duration> ago
         [for] <duration>
       Examples are:
         from 9:00
         from 9am - 11am
         from 9:00:00 to 11:00
         from 9:00 for 2h
         2h after 9am
         2h before 11:00
         2h ago
         for 2h
       An interval is said to be 'closed' if there is both a start and end,
       and 'open' if there is no end date.



timew 1.4.2                            2020-09-23                           timew-ranges(7)

In addition to time, you can specify date and time, so one equivalent command would use an ISO datetime.

$ timew track 2016-07-30T09:00:00 - 2016-07-30T11:00:00 'Outline the tutorial topics'

Again, you can see all the date formats listed using the help system.

$ timew help dates

Using date synonyms you can track time for a whole month.

$ timew track june - july Training

But that command will track all 30 days, all 24 hours each in June, including weekends, holidays and lunch breaks. Or does it? This is discussed later.

Hints

Many commands support hints, which are words that start with a : and are convenient representations to save time. Here is the :quiet hint, being used to suppress all feedback:

$ timew track 9am - 10am 'Walk the dog' :quiet
$ ▒

The :quiet hint is the same as disabling verbosity, but is easier to specify, and temporary. Another hint is :yes, which is used to override confirmation, by automatically answering ‘yes’ to the question.

Some hints are shortcuts specifiers for date ranges. For example, the :yesterday hint is a date range representing all day yesterday. Similarly, :lastweek is also a date range. That makes the following two commands identical (assuming that today is the 6th):

$ timew track :yesterday Hiking
$ timew track 5th - 6th Hiking

The help system lists all the supported hints.

$ timew help hints

timew-hints(7)                          User Manuals                         timew-hints(7)



NAME
       timew-hints - Timewarrior hints

SYNOPSIS
DESCRIPTION
       Timewarrior  supports  hints, which are single-word command line features that start
       with a colon like this:
         :week
       Hints serve several purposes.  This example is a shortcut for the date range that
       defines the current week.
       Other hints, such as:
         :quiet
       Are  ways  to  control  the  behavior of Timewarrior, in this case eliminating all
       forms of feedback, for purposes of automation.
       The supported hints are:
         :quiet         Turns off all feedback. For automation
         :debug         Runs in debug mode, shows many runtime details
         :yes           Overrides confirmation by answering 'yes' to the questions
...

Charts

Timewarrior has a built-in chart that can show blocks of time by day. This is a text-based chart so it is not high resolution and has no drill-down capabilities. (Incidentally such a chart would be possible using the extension API, but by default, Timewarrior just has simple charting).

There are three charts, which are really just three variations of the same chart, all controlled by configuration. We'll take a look at these charts, but first we need some sample data to look at. Let us first track a couple of days of data, to illustrate how the charts work.

$ timew track 2016-08-06T09:00 - 2016-08-06T12:00 'Staff meeting'  :quiet
$ timew track 2016-08-06T12:45 - 2016-08-06T14:00 Training         :quiet
$ timew track 2016-08-06T14:15 - 2016-08-06T16:00 'Project review' :quiet
$ timew track 2016-08-06T16:15 - 2016-08-06T17:20 Research         :quiet
$ timew track 2016-08-07T08:45 - 2016-08-07T12:30 Research         :quiet
$ timew track 2016-08-07T13:15 - 2016-08-07T17:30 Research         :quiet
$
$ ▒

We have tracked six separate intervals, and the summary report shows just that.

$ timew summary yesterday - now

Wk  Date       Day Tags              Start      End    Time    Total
--- ---------- --- -------------- -------- -------- ------- --------
W31 2016-08-06 Sat Staff meeting   9:00:00 12:00:00 3:00:00 
                   Training       12:45:00 14:00:00 1:15:00 
                   Project review 14:15:00 16:00:00 1:45:00 
                   Research       16:15:00 17:20:00 1:05:00  7:05:00
W31 2016-08-07 Sun Research        8:45:00 12:30:00 3:45:00 
                   Research       13:15:00 17:30:00 4:15:00  8:00:00
                
                                                            --------
                                                            15:05:00

$ ▒

The summary report gives accurate time values, so this should be the preferred report for this reason. Let's look at the first chart, the day report.

$ timew day

Sun  7 0    1    2    3    4    5    6    7    8  Research▒▒▒▒▒▒▒▒▒▒▒   1Research▒▒▒▒▒▒▒▒▒▒▒▒▒▒  18   19   20   21   22   23
                                                  ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒    ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒                             


          Tracked         8:00:00
          Available      16:00:00
          Total          24:00:00

$ ▒

Like the summary report, the day report shows data for today by default. You can make it show multiple days like this:

$ timew day 4th - now

A better option is to use the week report.

$ timew week

          0    1    2    3    4    5    6    7    8    9    10   11   12   13   14   15   16   17   18   19   20   21   22   23     Total
W31 Mon 1
    Tue 2
    Wed 3
    Thu 4 
    Fri 5
    Sat 6                                              Staff▒meeting▒▒   Trainin Project▒▒ Resea                                     7:05 
    Sun 7                                            Research▒▒▒▒▒▒▒▒▒▒▒    Research▒▒▒▒▒▒▒▒▒▒▒▒▒                                    8:00
                                                                                                                                   ------
                                                                                                                                    15:05

          Tracked        15:05:00
          Available     152:55:00
          Total         168:00:00

$ ▒

There is also a month report that looks the same, but is longer.

Again, the only difference between these reports is configuration, and you can override any of this to customize these charts. See man timew for full configuration details.

Reports

We have seen the summary and tags reports, but there is another useful report that shows the untracked time in the day.

$ timew summary

Wk  Date       Day Tags              Start      End    Time   Total
--- ---------- --- -------------- -------- -------- ------- -------
W31 2016-08-07 Sun Research        8:45:00 12:30:00 3:45:00 
                   Research       13:15:00 17:30:00 4:15:00 8:00:00
                
                                                            -------
                                                            8:00:00

$
$ timew gaps

Wk  Date       Day Tags              Start      End    Time    Total
--- ---------- --- -------------- -------- -------- ------- --------
W31 2016-08-07 Sun Research        0:00:00  8:45:00 8:45:00  
                   Research       12:30:00 13:15:00 0:45:00
                   Research       17:30:00  0:00:00 6:30:00 16:00:00
                 
                                                            --------
                                                            16:00:00

$ ▒

The gaps report is useful for finding time in the day where you were not tracking time. In the example the gaps correspond well to time that was not spent working, so there is no need for adjustments.

All reports in Timewarrior can be filtered by time interval and tags, but all have a default time interval.

Themes

Timewarrior has color themes that are mostly used by the charts to color the different parts of the display. To use a color theme, add this line to your ~/.timewarrior/timewarrior.cfg file with a text editor:

import /path/to/themes/dark_green.theme

Note that the path /path/to/themes is a placeholder. Your installation will likely use a path more like this, but it should be noted that this path varies depending on platform and the wishes of the packager.

import /usr/local/share/doc/timew/doc/themes/dark_green.theme

There are a few simple themes available initially, but this collection will grow and improve. Timewarrior is also likely to make greater use of themes in future releases.

Holidays

Timewarrior can also make use of Holiday files. In the same way that a color theme was imported into the configuration file, a holiday file can also be used:

import /usr/local/share/doc/timew/doc/holidays/holidays.en-US

Again, that path is platform-dependent, so use the appropriate path for your system.

When a holiday file is used, Timewarrior knows that there are some days in the year that are not work days. While this changes nothing about your ability to track time, it does affect some automatic tracking features, which we will cover next.

There is a README document and a refresh script provided with the holiday file, which explains how to update the holiday data, and how to obtain holiday files for other locales. Note that only the en-US locale is included by default.

Exclusions

Exclusions are a very powerful Timewarrior feature, and make automatic time tracking possible. An exclusion - much like a holiday - represents a block of time where you do not expect to work.

The simplest exclusion is a day off work. Suppose you took a day off, on August 4th. You can define this day as an exclusion.

$ timew config exclusions.days.2016_08_04 off :yes
Config file ~/.timewarrior/timewarrior.cfg modified.
$ ▒

The date must be formatted in this precise way. Note the use of the :yes hint to override confirmation. Now we see on the week report that the day is marked as non-working.

$ timew week

          0    1    2    3    4    5    6    7    8    9    10   11   12   13   14   15   16   17   18   19   20   21   22   23     Total
W31 Mon 1
    Tue 2
    Wed 3
    Thu 4 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Fri 5
    Sat 6
    Sun 7
                                                                                                                                   ------
                                                                                                                                     0:00

          Tracked         0:00:00
          Available     156:00:00
          Total         156:00:00

$ ▒

Similarly, if you worked on a holiday, you can define that day as a work day, and therefore available for automatic tracking.

$ timew config exclusions.days.2016_01_01 on :yes
Config file ~/.timewarrior/timewarrior.cfg modified.
$ ▒

Here we have (re)defined January 1st as a working day, which was previously defined as a holiday in the en-US locale.

In addition to whole days working or not working, you can define exclusions for each day of the week to represent your work schedule. Suppose you work a regular weekly schedule, that starts at 8:30am, Monday to Friday, with weekends off. You take a 45-minute lunch break each day, and leave work at 5:30pm. On Fridays you leave early.

$ timew config exclusions.monday    '<8:30 12:30-13:15' :yes
$ timew config exclusions.tuesday   '<8:30 12:30-13:15' :yes
$ timew config exclusions.wednesday '<8:30 12:30-13:15' :yes
$ timew config exclusions.thursday  '<8:30 12:30-13:15' :yes
$ timew config exclusions.friday    '<8:30 12:30-13:15' :yes
$ timew config exclusions.saturday  '>0:00'             :yes
$ timew config exclusions.sunday    '>0:00'             :yes
$ ▒

You can view this in the week report, and here we will use the :blank hint to remove all the tracked data from the report, leaving only the exclusions.

$ timew week :blank

          0    1    2    3    4    5    6    7    8    9    10   11   12   13   14   15   16   17   18   19   20   21   22   23     Total
W31 Mon 1 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒                    ▒▒ ▒                     ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Tue 2 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒                    ▒▒ ▒                     ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Wed 3 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒                    ▒▒ ▒                     ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Thu 4 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Fri 5 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒                    ▒▒ ▒                ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Sat 6 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒  
    Sun 7 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
                                                                                                                                   ------
                                                                                                                                     0:00

          Tracked         0:00:00
          Available      32:00:00
          Total          32:00:00

$ ▒

Your whole work week is defined. While you are not at all constrained by this defined schedule, it does control automatic time tracking.

Automatic Tracking

Once you have defined exclusions for your workweek, the tracked time will conform to the set boundaries. Suppose this is our work week:

$ timew week august

          0    1    2    3    4    5    6    7    8    9    10   11   12   13   14   15   16   17   18   19   20   21   22   23     Total
W31 Mon 1 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒                    ▒▒ ▒                     ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Tue 2 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒                    ▒▒ ▒                     ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Wed 3 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒                    ▒▒ ▒                     ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Thu 4 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Fri 5 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒                    ▒▒ ▒                ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Sat 6 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒  
    Sun 7 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
                                                                                                                                   ------
                                                                                                                                     0:00

          Tracked         0:00:00
          Available      32:00:00
          Total          32:00:00

$ ▒

There is no tracked time, but there are 40:15:00 hours available to be tracked. If we worked the whole week on our Research project, we can track all that time with one command:

$ timew start monday Research
Tracking Research
  Started 2016-08-01T00:00:00
  Current         07T21:38:29
  Total             165:38:29
$
$ timew week august

          0    1    2    3    4    5    6    7    8    9    10   11   12   13   14   15   16   17   18   19   20   21   22   23     Total
W31 Mon 1 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒Research            ▒▒ ▒Research             ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Tue 2 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒Research            ▒▒ ▒Research             ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Wed 3 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒Research            ▒▒ ▒Research             ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Thu 4 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Fri 5 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒Research            ▒▒ ▒Research        ▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
    Sat 6 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒  
    Sun 7 ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ ▒▒▒▒ 
                                                                                                                                   ------
                                                                                                                                     0:00

          Tracked         0:00:00
          Available      32:00:00
          Total          32:00:00

$ ▒

We see that the exclusions are automatically subtracted from the time, and fill the whole week, leaving no available time.

Note that this example tracks up until ’now’, and as this tutorial is being written on a weekend, you can see that the tracking stops on Friday, and does not continue into the weekend. If this was being done on the Friday, at 16:23, then the week report would stop precisely at 16:23, because it is an open interval.

Corrections

With or without the use of exclusions, there is always the need to make corrections to the tracked time. As mentioned earlier, it is quite likely that the clock would be left running by mistake, or that the tracking was started or stopped at the wrong time. We will create some incorrect time tracking, and then correct it.

$ timew track 9am - 10am ProjectA
Recorded ProjectA
  Started 2016-08-07T09:00:00
  Ended              10:00:00
  Total               1:00:00
$ timew track 10:12am - 10:30am projectB
Recorded projectB
  Started 2016-08-07T10:12:00
  Ended                 30:00
  Total               0:18:00
$ timew start 12pm projectC
Tracking projectC
   Started 2016-08-07T12:00:00
   Current            21:41:18
   Total               9:41:18
$ timew summary 

Wk  Date       Day Tags        Start      End    Time    Total
--- ---------- --- -------- -------- -------- ------- --------
W31 2016-08-07 Sun ProjectA  9:00:00 10:00:00 1:00:00  
                   projectB 10:12:00 10:30:00 0:18:00
                   projectC 12:00:00        - 9:41:24 10:59:24
           
                                                      --------
                                                      10:59:24

$ ▒

I actually started work at 8:30am, but forgot to start the clock at the beginning. I also did not take a break at 10am, I again forgot to start the clock. Then I was working on projectC since about 11am, but didn't record it properly.

These are typical mistakes, and are easy to fix, as there are several commands for making adjustments like this.

To make an adjustment to an interval, we need first to identify that interval. The summary, day, week and month reports all support the :ids hint for this purpose. If we take a look at the summary report with the hint:

$ timew summary :ids

Wk  Date       Day ID Tags        Start      End    Time    Total
--- ---------- --- -- -------- -------- -------- ------- --------
W31 2016-08-07 Sun @3 ProjectA  9:00:00 10:00:00 1:00:00  
                   @2 projectB 10:12:00 10:30:00 0:18:00
                   @1 projectC 12:00:00        - 9:41:24 10:59:24
              
                                                         --------
                                                         10:59:24

$ ▒

Notice how the intervals now have IDs: @3 for the oldest interval. Let's make some corrections:

$ timew move @3 8:30am
Moved @3 to 2016-08-07T08:30:00
$ timew lengthen @3 30mins
Lengthened @3 by 0:30:00
$ timew move @1 11:00
Moved @1 to 2016-08-07T11:30:00
$
$ timew summary :ids

Wk  Date       Day ID Tags        Start      End     Time    Total
--- ---------- --- -- -------- -------- -------- -------- --------
W31 2016-08-07 Sun @3 ProjectA  8:30:00 10:00:00  1:30:00  
                   @2 projectB 10:12:00 10:30:00  0:18:00
                   @1 projectC 11:00:00        - 10:41:24 12:30:39
               
                                                          --------
                                                          12:30:39

$ ▒

There is still a problem, interval @2 needs to occupy the slot between 10am and 11am. There is a :fill hint that does this for us.

$ timew @2 move 10:02 :fill
Backfilled @2 to 2016-08-07T10:00:00
Filled @2 to 2016-08-07T11:00:00
Moved @2 to 2016-08-07T10:00:00
$
$ timew summary

Wk  Date       Day Tags        Start      End     Time    Total
--- ---------- --- -------- -------- -------- -------- --------
W31 2016-08-07 Sun ProjectA  8:30:00 10:00:00  1:30:00  
                   projectB 10:00:00 11:00:00  1:00:00
                   projectC 11:00:00        - 10:43:15 13:13:15
            
                                                       --------
                                                       13:13:15

$ ▒

The @1 ID always represents the newest interval. Note that if my corrections have changes the order, then the IDs would be different, and you would need to run timew summary :ids again to see the new IDs.

Finally, I actually stopped for lunch at 12:30 for 45 minutes:

$ timew stop 12:30pm
Recorded projectC
   Started 2016-08-07T11:00:00
   Current            12:30:00
   Total               1:30:00
$
$ timew continue
Tracking projectC
   Started 2016-08-07T21:43:53
   Current                  53
   Total               1:30:00
$
$ timew summary

Wk  Date       Day Tags        Start      End    Time   Total
--- ---------- --- -------- -------- -------- ------- -------
W31 2016-08-07 Sun ProjectA  8:30:00 10:00:00 1:30:00 
                   projectB 10:00:00 11:00:00 1:00:00
                   projectC 11:00:00 12:30:00 1:30:00        
                   projectC 21:43:53        - 0:00:07 4:00:07
          
                                                      -------
                                                      4:00:07

$
$ timew move @1 1:15pm
Moved @1 to 2016-08-07T13:15:00
$ ▒

Let's keep going, even though this example has already exceeded credibility, to demonstrate more. I need to change that projectB interval to use projectB1 and projectB2 tags, and divide the time between the two. We will split the interval, the re-tag it.

$ timew summary :ids

Wk  Date       Day ID Tags        Start      End    Time    Total
--- ---------- --- -- -------- -------- -------- ------- --------
W31 2016-08-07 Sun @4 ProjectA  8:30:00 10:00:00 1:30:00 
                   @3 projectB 10:00:00 11:00:00 1:00:00
                   @2 projectC 11:00:00 12:30:00 1:30:00        
                   @1 projectC 13:15:00        - 8:29:42 12:29:42
               
                                                         --------
                                                         12:29:42

$ timew @3 split
Split @3
$
$ timew summary :ids

Wk  Date       Day ID Tags        Start      End    Time    Total
--- ---------- --- -- -------- -------- -------- ------- --------
W31 2016-08-07 Sun @5 ProjectA  8:30:00 10:00:00 1:30:00 
                   @4 projectB 10:00:00 10:30:00 0:30:00
                   @3 projectB 10:30:00 11:00:00 0:30:00
                   @2 projectC 11:00:00 12:30:00 1:30:00        
                   @1 projectC 13:15:00        - 8:29:54 12:29:54
               
                                                         --------
                                                         12:29:54
$ timew untag @4 @3 projectB
Removed projectB from @4
Removed projectB from @3
$ timew tag @4 projectB1
Added projectB1 to @4
$ timew tag @3 projectB2
Added projectB2 to @3
$ timew summary :ids

Wk  Date       Day ID Tags         Start      End    Time    Total
--- ---------- --- -- --------- -------- -------- ------- --------
W31 2016-08-07 Sun @5 ProjectA   8:30:00 10:00:00 1:30:00 
                   @4 projectB1 10:00:00 10:30:00 0:30:00
                   @3 projectB2 10:30:00 11:00:00 0:30:00
                   @2 projectC  11:00:00 12:30:00 1:30:00        
                   @1 projectC  13:15:00        - 8:30:19 12:30:19
                
                                                          --------
                                                          12:30:19

$ ▒

Notice how the split command just divided @3 into two even-sized intervals. But we're still not done - I brought lunch to work and ate at my desk while working so let's eliminate that lunch break.

$ timew join @2 @1
Joined @2 and @1
$
$ timew summary

Wk  Date       Day Tags         Start      End     Time    Total
--- ---------- --- --------- -------- -------- -------- --------
W31 2016-08-07 Sun ProjectA   8:30:00 10:00:00  1:30:00 
                   projectB1 10:00:00 11:30:00  0:30:00
                   projectB2 11:30:00 11:00:00  0:30:00
                   projectC  11:00:00        - 10:46:10 13:16:10
                 
                                                        --------
                                                        13:16:10

$ ▒

Now whether this report now accurately represents your day, or whether it is a fiction you need to report (no judgement here), Timewarrior supports it, but let's stop - the example can't take much more.

We saw the stop command with a specific end time, the move, the lengthen, split, join, tag and untag commands and the :fill hint being used. There are also the shorten, cancel, and delete commands. See man timew for full details.

Extensions

Timewarrior reports are not sophisticated, they are minimally functional and focus on simply displaying the data. What if you need a report broken down by tags, with weekly subtotals?

Timewarrior supports extension reports, via the extension API. This is mechanism that allows you to write a report using any language you choose. Don't like the way the summary report shows the data? Write your own. Better yet, share the result, and we'll build a list of 3rd party reports.

We've included one extension report with Timewarrior, and will add more. The one provided is:

$ ls -l /usr/local/share/doc/timew/ext/totals.py
-rw-r--r-- 1 root admin 3606 Jul 30 15:34 /usr/local/share/doc/timew/ext/totals.py
$ ▒

Again, that path is platform-dependent, so use the appropriate path for your system. Note that this is a Python script, and to use this you'll need to have Python installed.

To install and use this extension, or any other, simply copy it to your ~/.timewarrior/extensions directory and make sure it is executable.

$ cp /usr/local/share/doc/timew/ext/totals.py ~/.timewarrior/extensions
$ chmod +x ~/.timewarrior/extensions/totals.py
$

Caution

Extensions are dangerous things. As with any downloaded program, be careful - you are giving execute permission to software that may harm you.

Fortunately this is the world of open source, and while that does not mean the software is safe, it does mean you have the necessary access to audit the code and prove it is safe. If you find the code safe, use it. If you are unsure, don't.

Once the extension is in the extensions directory, and executable, it should be visible to the extensions command.

$ timew extensions

Extensions located in:
  ~/.timewarrior/extensions

Extention Status
--------- ------
totals.py Active

$ ▒

Additionally, the diagnostics command will report the presence and status of this extension.

Once an extension is ready to use, it is used in the same way that the summary report is used, with date range and/or tag filtering. The command you use is compared to the name of the script, and if unique, is a match. All of these commands are equivalent:

$ timew totals.py
$ timew totals.p
$ timew totals.
$ timew totals
$ timew total

Here is the report run with no filter, and therefore against all recorded data, which is not much in this example.

$ timew totals

Total by Tag, for 2016-08-07 12:30:00 - 2016-08-08 01:52:44

Tag          Total
--------- --------
ProjectA   1:30:00
projectB1  0:30:00
projectB2  0:30:00
projectC  10:52:44

          --------
Total     13:22:44

$ ▒

Extensions are not restricted to emitting text, they could for example output, DOT, PDF, PNG, JPEG ...

Integration

Timewarrior integrates with Taskwarrior by means of a Taskwarrior on-modify hook script. Once installed, this means that whenever a task is active, Timewarrior is used to track the time.

Find instructions on how to install & use it on its dedicated page.

End

You've made it to the end of the tutorial. You now know more about Timewarrior than most users. If you have feedback, we are interested in hearing it, because open source is a collaborative effort, and you are part of that.