A command line time tracking tool for people who need to track the time they work on their personal and client projects.
go install github.com/mrcook/time_warrior/...@latest
This installs to
$HOME/go/bin/ by default, which can be added to your
tw in your terminal to get started. You can view the help by typing
tw -h, or by prefixing each sub command with
help, like so:
tw help start.
By default, running the application will display the help page, however, if you have a pending timeslip in progress then those details will be printed instead:
MyProject.SetupTask | Started: 2017-12-11 13:37 | Worked: 22 minutes | Status: started
Worked time format is displayed using
seconds, along with two abbreviated combinations:
1h 23m and
On the very first time you run TimeWarrior on your system, a directory will be created in
$HOME/time_warrior. This is where all your project data files will be stored - it can be useful to make this into a
Common commands have a short alias:
Start New Timeslip
$ tw start MyProject.SetupTask
This command will start a new pending timeslip with a project name of
MyProject and a task name of
SetupTask. This timeslip will be saved in the
$HOME/time_warrior/.pending file, and the details printed to the command line:
MyProject.SetupTask | Started: 2017-12-11 13:35 | Worked: 0 seconds | Status: started
Recommendations for starting new timeslips:
- Use CamelCase for Project and Task names.
- Always including a Task name, this will improve the generated reports.
- Tasks can span several work sessions, so it's okay to use the same Project.Task name multiple times.
There are several points to take note of regarding starting new timeslips:
- Use only ASCII characters for the
Project.Tasknames - upper and lower case alphanumeric characters.
- Spaces are not allowed.
- The task name is optional, but recommended.
- Only one timeslip can be started at a time.
$ tw pause
This will pause the currently running timeslip, and print the details to the terminal:
MyProject.SetupTask | Started: 2017-12-11 13:37 | Worked: 2 minutes | Status: paused (2017-12-11 13:39)
$ tw resume
This will resume a paused timeslip and print the details to the terminal:
MyProject.SetupTask | Started: 2017-12-11 13:37 | Worked: 2 minutes | Status: started
Done! Complete Timeslip
$ tw done "Basic project setup with a nice README"
When you've finished your current task you can mark the slip as done, giving a short description of the work made. You should use either 'single' or "double" quotes.
The details will again be printed on the command line:
MyProject.SetupTask | Started: 2017-12-11 13:37 | Worked: 9m 23s | Status: completed
If this is a new project a data file will be created using the project name you gave (
MyProject) and saved as
$HOME/time_warrior/my_project.json. Each timeslip created for this project will be save on a separate line in this file.
If you forget to
resume your current timeslip, you can use the
adjust command to add/subtract a time duration to the
Adjustments are made using a simple duration string in the format of a decimal number followed by a single time unit character (e.g.
10m). Allowed units are
s, for hours, minutes, and seconds, respectively.
Here's some examples adding worked time:
$ tw adjust 2h $ tw adjust 30m $ tw adjust 45s $ tw adjust 72m $ tw adjust 720s
To subtract time you need to specify the
-n (negative) flag. Examples:
$ tw adjust -n 1h $ tw adjust -n 20m $ tw adjust -n 90s
Here is a full example of adding
1 hour and
15 minutes to a running timeslip:
$ tw MyProject.SetupTask | Started: 2017-12-11 18:01 | Worked: 15m | Status: started $ tw adjust 75m MyProject.SetupTask | Started: 2017-12-11 18:01 | Worked: 1h 30m | Status: started
Caution! This action can not be undone!
$ tw delete
If you make a mistake when starting a new timeslip, perhaps using an incorrect project name, you can delete it easily with this command.
Reports can be generated using the
report command, with the listing printed to the terminal:
$ tw report 3h 01m : Project A 1h 22m : Project B ----------- 0h 10m : Project A pending timeslip =========== 4h 33m
The time worked is specified in the
m columns (hours, minutes), which is followed by the project name.
At the end of each listing the total time worked is displayed. If there are any pending timeslips in progress,
this information is also included.
When no project name has been given, all projects found in the
$HOME/time_warrior directory will be included, and displayed in alphabetical order.
$ tw report 3h 01m : Project A 11h 22m : Project B 70h 52m : TimeWarrior =========== 85h 05m
When specifying a project name, all tasks within that project will be included, and displayed in alphabetical order.
$ tw report TimeWarrior Project Name: TimeWarrior Task List 10h 5m : . 8h 19m : AdjustCommand . . . 4h 11m : Timeslip ----------- 0h 10m : Reports pending timeslip =========== 70h 62m
. task name above. If a timeslip is recorded without a task name being used then these will be grouped here.
To have a better breakdown in your reports it's recommended that task names be used when starting new timeslips.
Report Time Periods
Although it is interesting to know the total time worked on a project, it's more common for a specific period of time, such as today or last month, to be requested.
report command takes a
-p flag to specify a time period:
$ tw report -p w TimeWarrior Project Name: TimeWarrior Time Period: This Week (Jan 7, 2019 to Jan 13, 2019) Task List 1h 32m : Documentation 10h 20m : Reports =========== 11h 52m
The following time periods are available:
w- This Week
m- This Month
y- This Year
1w- Last Week
1m- Last Month
1y- Last Year
A time period of
1d can be described as one day previous, otherwise known as yesterday, and
1m would be one month previous (last month).
I've tried to follow the same pattern as with the adjust command, hopefully this nomenclature is clear.
To contribute to the source code or documentation, you should fork the TimeWarrior GitHub project and clone it to your local machine. Then making a PR (Pull Request) for review.
If you believe you have found a defect in TimeWarrior or its documentation, use the GitHub issue tracker to report the problem to the TimeWarrior maintainers.
When reporting the issue, please provide the version of TimeWarrior in use (