clock-tracking 0.0.1

Time tracking management from python / command line

clock

Simple command-line time tracker based on a simple text file format.

Introduction

This simple utility uses a text file to store tasks with date/time information. Each time you start working on a task, a new line is created on the file with the current time and a description of the task you are starting to work on.

At the end of the day, or anytime, you can then generate reports and statistics based on the file.

File structure

The file structure is very simple and can be edited using the script or directly with your favorite text editor. Here is an example file:

[2022-01-01]
10:00 Starting project X +projectX
11:23 Starting documentation of project X +projectX +doc
12:00 [Stop]
[2022-01-02]
08:05 Starting workday, checking emails +office +emails
09:00 Back on documentation +projectX +doc
10:00 [Stop]

Tags and ids

An entry in this file can be associated with tags if you start the tag with a + (+tag) or ID if you start with a . (.456).

Tags allow for powerful filtering and reporting. They are ordered, meaning that +project +doc is different from +doc +project (see reports and filters below).

IDs allow to track time of tasks from an external tool, such as Jira. Entries with an ID are automatically assigned a default tag (+jira).

Special tasks

The [Stop] task is used to stop the last task. It is not required if you switch tasks without taking a break.

Installation

The program is available as a python packge through Pypi, so you can download it using pip:

python -m pip install --index-url https://test.pypi.org/simple/ clock-tracking-computoms

Usage

Tracking tasks

Using the clock_tracking python package to run the program, i.e. python -m clock_tracking.

You can add a new entry by adding the entry definition after the package name:

$ python -m clock_tracking Definition of the prototype +myapp +proto
Added: 08:10 Definition of the prototype +myapp +proto

Duration   Date                  Start      Stop       Tags            Name                               IDs
00:00      2022-01-01            08:10      08:10      +myapp,+proto   Definition of the prototype         

To switch to a new task, just use the same command:

$ python -m clock_tracking Switching to new task
Added: 09:02 Switching to a new task

Duration   Date                  Start      Stop       Tags            Name                               IDs
00:00      2022-01-01            08:10      08:10                      Switching to a new task

This will automatically stop the last task and start a new one. When you have finished working, use the stop command:

$ python -m clock_tracking stop
Added: 10:00 [Stop]

Reports

You can show reports/statistics with the show command:

$ python -m clock_tracking show

All tasks are ordered by first tag by default. Several filters are available, see ./clock --help for the full documentation.

To show all the tasks with their details:

$ python -m clock_tracking show --details

To filter by a tag:

$ python -m clock_tracking show +tag

To filter by an ID:

$ python -m clock_tracking show .345

Examples

Show today's tasks:

Show tasks by tags:

Show today's tasks details:

Documentation

usage: clock [-h] [-a HH:MM] [-c] [-f FILE] [-t] [-w] [-s YYYY-mm-dd]
             [-e YYYY-mm-dd] [-T HH:MM] [-D HH:MM] [-d]
             command

Helps managing time tracking

positional arguments:
  command

optional arguments:
  -h, --help            show this help message and exit
  -a HH:MM, --at HH:MM  <add> Specify a time (format HH:MM) of a new entry
  -c, --current         <add> Modify the description of the current entry
  -f FILE, --file FILE  Speficy the file to store time entries. Default is
                        ./clock.txt
  -t, --today           <show> Show only entries from today
  -w, --week            <show> Show only entries from the current week
  -s YYYY-mm-dd, --from YYYY-mm-dd
                        <show> Include entries with start date later or equal
                        to given date (format YYYY-mm-dd)
  -e YYYY-mm-dd, --to YYYY-mm-dd
                        <show> Include entries with start date earlier or
                        equal to given date (format YYYY-mm-dd)
  -T HH:MM, --target HH:MM
                        <show> Sets expected target time (format HH:MM) and
                        computes the difference with actual times in the
                        reports
  -D HH:MM, --target-per-day HH:MM
                        <show> Sets expected target time per day (format
                        HH:MM) and computes the difference with actual times
                        in the reports
  -d, --details         <show> Shows detailed report