Timewarrior (timew) is a time management tool for the terminal. At its heart is a stopwatch-like timer that tags blocks of time with descriptive text. Data is stored locally in JSON format to ensure portability. From this data detailed time tracking reports can be generated. Like its sibling Taskwarrior, the Timewarrior application has a large ecosystem of related tools that have grown up around it.
USE flags for app-misc/timew Tracks your time from the command line, and generates reports
emerge --ask app-misc/timew
Timewarrior is designed to optionally integrate into Taskwarrior by means of event-based hooks. To integrate the two programs /usr/share/doc/timew-<ver>/ext/on-modify.timewarrior must be copied to the .task/ directory inside of the user's home.
- $TIMEWARRIORDB - specifies the location of the timewarrior directory.
- ~/.timewarrior/timewarrior.cfg - the default location of user configuration data.
- ~/.timewarrior/data/YYYY-MM.data - time tracking data files separated by year and month.
If timew is run without any arguments it will provide information on any active tracking the application is performing:
There is no active time tracking.
Starting the time tracking process is as simple as:
‾ The timer will run until it is stopped by user action:
To get a summary of recently logged time:
Wk Date Day Tags Start End Time Total ‾‾ ‾‾‾‾ ‾‾‾ ‾‾‾‾ ‾‾‾‾‾ ‾‾‾ ‾‾‾‾ ‾‾‾‾‾ W17 2023-04-26 Wed 19:31:26 19:34:00 0:02:34 0:02:34 _______ 0:02:34
Tagging allows the user to track time for specific projects. Tags can be single words or, if enclosed in single quotes, multiple words long.
timew start 'wiki edits'
This could then display as:
Wk Date Day Tags Start End Time Total ‾‾ ‾‾‾‾ ‾‾‾ ‾‾‾‾ ‾‾‾‾‾ ‾‾‾ ‾‾‾‾ ‾‾‾‾‾ W17 2023-04-26 Wed 19:31:26 19:34:00 0:02:34 wiki edits 19:57:47 19:59:28 0:01:41 0:04:15 _______ 0:04:15
Usage: timew [--version] timew annotate @<id> [@<id> ...] <annotation> timew cancel timew config [<name> [<value> | '']] timew continue [@<id>] [<date>|<interval>] timew day [<interval>] [<tag> ...] timew delete @<id> [@<id> ...] timew diagnostics timew export [<interval>] [<tag> ...] timew extensions timew gaps [<interval>] [<tag> ...] timew get <DOM> [<DOM> ...] timew help [<command> | dates | dom | durations | hints | ranges] timew join @<id> @<id> timew lengthen @<id> [@<id> ...] <duration> timew modify (start|end) @<id> <date> timew month [<interval>] [<tag> ...] timew move @<id> <date> timew [report] <report> [<interval>] [<tag> ...] timew shorten @<id> [@<id> ...] <duration> timew show timew split @<id> [@<id> ...] timew start [<date>] [<tag> ...] timew stop [<tag> ...] timew summary [<interval>] [<tag> ...] timew tag @<id> [@<id> ...] <tag> [<tag> ...] timew tags [<interval>] [<tag> ...] timew track <interval> [<tag> ...] timew undo timew untag @<id> [@<id> ...] <tag> [<tag> ...] timew week [<interval>] [<tag> ...] Additional help: timew help <command> timew help dates timew help dom timew help durations timew help hints timew help ranges Additional help: timew help <command> timew help dates timew help dom timew help durations timew help hints timew help ranges Interval: [from] <date> [from] <date> to/- <date> [from] <date> for <duration> <duration> before/after <date> <duration> ago [for] <duration> Tag: Word 'Single Quoted Words' "Double Quoted Words" Escaped\ Spaces Configuration overrides: rc.<name>=<value>
Timewarrior is not respecting the XDG Directory Specification
Curently Timewarrior has partial support for the XDG Directory specification. If the $TIMEWARRIORDB variable is set then timew will store its data at the location specified by the variable. If the directory ~/.timewarrior/ exists and the $TIMEWARRIORDB variable is not set, then this directory is used by timew to store data. If neither of these conditions are true, $XDG_CONFIG_HOME/timewarrior/ is used instead.
Provided timew is not running, moving an existing Timewarrior data directory from its legacy location to its XDG location should be as simple as:
mv ~/.timewarrior $XDG_CONFIG_HOME/timewarrior
emerge --ask --depclean --verbose app-misc/timew