Using Tags

Enhance your time tracking with tags.

In the previous section, you recorded simple intervals and displayed them. That is a good start, but what if you want to track time spent on different activities? How would you be able to tell those intervals apart?

Here is where tags come in. Tags allow you to categorize your time tracking. Think of them as labels for your recorded intervals.

Let’s again track some time, but this time we add a tag to the interval. A tag is simply an extra string after the start command. For example, when you want to track time spent on a client project, you can use the tag CLIENT:

$ timew start CLIENT
Note: 'CLIENT' is a new tag.
Tracking CLIENT
  Started 2025-02-23T11:02:13
  Current                  13
  Total               0:00:00
$ ▒

Timewarrior now reports that it is tracking CLIENT. You are also notified that CLIENT is a new tag.

Previously, you saw that when using the start command repeatedly, Timewarrior would only report on the current tracking.

This is the same when using tags, but only when you use the same tag set. When you call start with a different tag set, Timewarrior will stop the current tracking and start a new one.

Let’s assume you have a phone call in the context of CLIENT and you want to track this as well. Instead of explicitly stopping the first recording and then starting the next, just call start with the new tag set:

$ timew start PHONE CLIENT
Recorded CLIENT
  Started 2025-02-23T11:02:13
  Ended                 14:56
  Total               0:12:43
Note: 'PHONE' is a new tag.
Tracking CLIENT PHONE
  Started 2025-02-23T11:14:56
  Current                  56
  Total               0:00:00
$ ▒

Timewarrior reports that it has recorded an interval with tag CLIENT and that it is now tracking PHONE and CLIENT. Because PHONE is a new tag you are notified about this, but not for CLIENT as it is already known.

When you are done with the phone call, you could switch your time tracking back to working on CLIENT by calling start with only CLIENT as the tag set. However, you can also just call stop with the tags you no longer want to track, i.e. in our case PHONE:

$ timew stop PHONE
Recorded CLIENT PHONE
  Started 2025-02-23T11:14:56
  Ended                 19:22
  Total               0:04:26

Tracking CLIENT
  Started 2025-02-23T11:19:22
  Current                  22
  Total               0:00:00
$ ▒

You see that Timewarrior reports on the tracked interval with the tags PHONE and CLIENT, and that it is now tracking only CLIENT again.

When you call the stop command without any tags, Timewarrior will stop all tracking:

$ timew stop
Recorded CLIENT
  Started 2025-02-23T11:19:22
  Ended                 34:07
  Total               0:14:45
$ ▒

Using the summary command, you can have a look on your recorded intervals again:

$ timew summary :ids

^[[4mWk^[[0m ^[[4mDate      ^[[0m ^[[4mDay^[[0m ^[[4mID^[[0m ^[[4mTags         ^[[0m ^[[4m   Start^[[0m ^[[4m     End^[[0m ^[[4m   Time^[[0m ^[[4m  Total^[[0m
W8 2025-02-23 Sun @6                8:05:21  8:22:56 0:17:35
                  @5                8:31:07  9:20:02 0:48:55
                  @4                9:23:00  9:54:28 0:31:28
                  @3 CLIENT        11:02:13 11:14:56 0:12:43
                  @2 CLIENT, PHONE 11:14:56 11:19:22 0:04:26
                  @1 CLIENT        11:19:22 11:34:07 0:14:45 2:09:52
                                                             ^[[4m       ^[[0m
                                                             2:09:52

$ ▒

You see that now with tags you have a better idea of what you have been doing during those intervals.

But what about the previous intervals (@4, @5, and @6) that you tracked without tags? Do they have to stay like this? No, you can add tags to them as well.

In the next section, you will learn how to add, remove, and change tags of your recorded intervals.

Or you return to the Tutorial section and pick another topic of interest.