How to use Pomodoro and report in an effective way


Usually, when working on a kernel bug, new feature, or code refactor, we put a considerable amount of work toward our goal; inevitably, developers will take breaks in their tasks. A common technique to manage these periods of working and resting is named Pomodoro. In a few words, developers define Z minutes to fully focus on something and Y minutes to rest before another focus session (for more details, read the Wikipedia page). Since this is a widespread technique, kw added support to it with the pomodoro feature; however, we also expanded it to enable developers to generate reports based on their focus time.

At this point, you might ask yourself, “What is the advantage of tying Pomodoro sessions to reports?”. If you work as a developer, then chances are that you have to write reports to your manager, company, a status update on your website, or you might want to assess your productivity. No matter your reasons, sooner or later, you will face a situation where you need a report, and if you are not ready, you will probably prepare it hastily. Lastly, if you use kw regularly, you probably have it as part of your workflow, making it easier to adopt the pomodoro and report feature.

Ok, enough with the general explanation; this is the tutorial section, right? For this tutorial, suppose that we have two situations, one where you are working on a bug and another one that you are implementing a new feature. Later you need a report with the details of your work.

Start a focus session

Since you are working on a highly complex bug, you decide to dedicate 30 minutes to make sure that you know how to reproduce the issue; you can start with:

$ kw pomodoro --set-timer 30m --tag "Super weird bug" --description "Let's make sure that I know how to reproduce this bug..."

Notice that you can use the short version of the above command:

$ kw p -t 30m -g "Super weird bug" -d "Let's make sure that I know how to reproduce this bug..."


From now on, this tutorial will use the short version

Now that you created this session, you can check how many minutes are left by using:

$ kw p --list # kw p -l

Now, forget about the world and focus on your task for 30 minutes; don’t worry, kw will notify you with a sound and a pop-up box (if you enable this in your system) when your session finishes. After you complete one round, take a break to refresh your energy and get back later.

Suppose that you already know how to reproduce that bug, and now you want to implement a workaround to fix it; let’s create a new focus session associated with the same tag:

$ kw p -t 30m -g "Super weird bug" -d "I know how to reproduce the bug! I'm going to try THIS WORKAROUND to see if it fixes the issue"

Notice that typing “Super weird bug” is tedious and error-prone, but don’t worry, kw provides a feature to list all tags and associates them with an ID. To see all the tags that you already created, use this command:

$ kw p -g
1.Super weird bug

In other words, you can use:

$ kw p -t 30m -g 1 -d "I know how to reproduce the bug! I'm going to try THIS WORKAROUND to see if it fixes the issue"

You can create as many focus sessions as you want at any time and day.

Generate a report

At this point, you are already familiar with the basic functionality around the Pomodoro feature, and you use it daily. However, now someone is asking you for a report on your last week, and you worked on so many things that you don’t even know where to start; don’t worry, kw has your back. It is now time to use the report feature. If you want to get this week’s summary, you can use:

$ kw report --week

Or just:

$ kw r --week

The report will look like this:

# Report: YYYY/MM/DDD
 * Total hours of focus: 48:43:00
 * Total focus session(s): 23

## Super weird bug
 - Total focus time: 04:20:00
 - Total repetitions: 22

 * [15:00:00-15:30:00][30m]: Let's make sure that I know how to reproduce this bug...
 * [17:00:00-17:30:00][30m]: I know how to reproduce the bug! I'm going to try THIS WORKAROUND to see if it fixes the issue

## Another Tag
 - Total focus time: HH:MM:SS
 - Total repetitions: 4

 * [08:15:50-08:45:50][30m]: More descriptions

As you can see, the report starts with a generic summary, and then displays a breakdown of the sessions per tag. Each tag will receive its own section, and each description will be put in order in the Summary part. This feature allows you to generate reports with the following granularity:

  • Day: Provide a day using the format YYYY/MM/DD.

  • Week: You need to provide a target day (no matter the weekday), and kw will look for the first day of the week associated with that date and generate a report based on that.

  • Month: Provide a month using YYYY/MM and kw will give you the report for the target month.

  • Year: Provide the year as YYYY and kw will provide the summary for the entire year.

By default, if you do not provide specific dates, kw report will assume the closest date; for example:

$ kw report         # Shows today's report
$ kw report --week  # Shows this week's report
$ kw report --month # Shows this month's report
$ kw report --year  # Shows this year's report


As you can see, Pomodoro and report are very powerful tools to help you track your work. If you use this feature regularly, there is a good chance that all of this data is valuable to you; in this sense, we recommend you take a look at kw backup feature since it creates a backup of all your Pomodoro data.