Timewarrior Documentation

The timew modify command supports two specific hints to handle interval boundaries and collisions:

• :fill: Automatically adjusts the interval to close gaps with adjacent intervals.
  • When using start, it fills the gap between the interval and the previous interval.
  • When using end, it fills the gap between the interval and the next interval.
  • When using range, it fills gaps on both sides.
• :adjust: Forces the modification even if the new range overlaps with an existing interval. This will overwrite the overlapping interval.

Timewarrior configuration is stored in timewarrior.cfg. On Unix systems, it defaults to ~/.config/timewarrior/timewarrior.cfg (following XDG Base Directory specs) unless ~/.timewarrior exists. On non-Unix systems, it is located at ~/.timewarrior/timewarrior.cfg.

You can also override the data location using the TIMEWARRIORDB environment variable.

Timewarrior uses flexible syntax to define intervals (blocks of time). An interval can be 'closed' (having both a start and an end date) or 'open' (having only a start date).

You can specify intervals using the following patterns:

• [from] <date>: An open interval starting at a specific time.
• [from] <date> to/- <date>: A closed interval between two points.
• [from] <date> for <duration>: An open interval starting at a time and lasting for a specific duration.
• <duration> before/after <date>: A closed interval relative to a specific time.
• <duration> ago: A closed interval relative to the current time.
• [for] <duration>: An open interval representing a duration (often used relative to now).

Note: <duration> refers to time lengths like 2h (2 hours).

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

The Timewarrior DOM (Document Object Model) provides a hierarchical way to access data from the Timewarrior database. All DOM references must start with the dom prefix. The structure is divided into four primary sub-references:

1. dom.tracked: Accesses all intervals returned by a database query. This reference supports filtering by range and tags.
2. dom.active: Accesses the currently active time tracking interval. This is invalid if no time is being tracked.
3. dom.tags: Accesses all tags present in the database.
4. dom.rc: Accesses Timewarrior configuration settings.

Because named dates (like today, yesterday, etc.) are defined with the time 0:00:00, using them as the upper bound of a range will exclude the day they represent.

If you want to include the current day in a relative sum, use now or tomorrow instead of today.

Example: Summing the last 2 days

To exclude the current day:

$ timew sum 2d before today

To include the current day:

$ timew sum 2d before now
$ timew sum 2d before tomorrow

Use basic commands to manage active time intervals.

• start: Creates a new open interval. If an interval is already active, it closes the current one and starts a new one only if the provided tags differ from the current ones.
• stop: Closes the current open interval at the specified date. If tags are provided, it creates a new open interval containing only the tags from the current interval that were not in the provided list.
• cancel: Deletes the current open interval entirely.

timew start
timew stop 17:00
timew cancel