Download the PHP package wick-ed/timely without Composer

Timely

Simple PHP console tool to track your times and push them into a remote time-keeping tool such as Jira.

Introduction

Semantic versioning

This tool follows semantic versioning and its public API defines as follows:

• The commands it exposes over the command line interface
• The format of its storage file
• The format of its configuration file and the given configuration options

Usage

As an alias like:

And use like:

Commands

There are several simple commands available, to track your everyday work:

• track
• show
• pause
• push

track

NAME

The show command tracks an activity you just started This activity has to be in relation to an identifier such as a ticket ID from your ticket system. Although this is only to structure your tracked times, it will be used when interaction with an actual ticket system.

An example call would be:

timely show FOO-42 Doing some stuff now

track -- Track tickets you are starting to work on just now

SYNOPSIS

timely track ticket-id comment

DESCRIPTION

The track command tracks an activity you just started This activity has to be in relation to an identifier such as a ticket ID from your ticket system. Although this is only to structure your tracked times, it will be used when interaction with an actual ticket system.

EXAMPLES

Start tracking your work on ticket FOO-42 leaving a comment

show

NAME

show -- Show tracked tasks, filterable by ticket id

SYNOPSIS

timely show [yesterday|today|current] [-t|f|s] [--to|from|specific] [ticket-id]

DESCRIPTION

The show command is used to display times you have already tracked. By default, these times are grouped by the (ticket) identifier you used for tracking. Example output would look like this:

Only tracked activities that already last or lasted longer than 15 minutes are shown.

EXAMPLES

The tracked times in question can also be filter by supplying the optional (ticket) identifier:

You can further filter by narrowing the time interval. This can be done by using supplied filter keywords current, today or yesterday:

or

This filters for the tracking currently active (as in "what you are currently doing") or all tracked times of yesterday.

Filtering the processed time trackings is also possible through the from, to and specific options. These options support the PHp date and time format as described here: https://www.php.net/manual/en/datetime.formats.php This allows for refined filtering as shown in the examples below.

Filter for a certain specific date:

Filter for a given time range:

Filter for the last week:

Filter for everything within the last October:

pause

NAME

pause -- Pause the current tracking until explicitly resumed

SYNOPSIS

timely pause [-r|--resume|comment]

DESCRIPTION

The pause command allows to pause the tracking of your current task. This makes sense e.g. for a small break, lunch or simply for leaving work to continue the next morning.

After the pause is over, the current tracking must be resumed:

If you start with something else, using the track command during an ongoing pause will also end the pause automatically.

EXAMPLES

See above.

push

NAME

push -- Pushes booked times against the configured remote

SYNOPSIS

timely push [yesterday|today|current] [-t|f|s] [--to|from|specific] [ticket-id]

DESCRIPTION

The push command is used to push tracked times to an external time keeping service. Jira being an example of a supported service. Using the push command requires configuration of the service's endpoint and possibly authentication within the .env configuration file.

The command has the same syntax and usability as the show command. On execution the command will use the service's internal format to process all tracked times that a similar show command would have displayed.

The following command would create e.g. Jira worklogs for yesterday's tasks:

The push command keeps track of already pushed time trackings so nothing gets pushed twice.

EXAMPLES

The tracked times in question can also be filter by supplying the optional (ticket) identifier:

You can further filter by narrowing the time interval. This can be done by using supplied filter keywords current, today or yesterday:

or

This filters for the tracking currently active (as in "what you are currently doing") or all tracked times of yesterday.

Filtering the processed time trackings is also possible through the from, to and specific options. These options support the PHp date and time format as described here: https://www.php.net/manual/en/datetime.formats.php This allows for refined filtering as shown in the examples below.

Filter for a certain specific date:

Filter for a given time range:

Filter for the last week:

Filter for everything within the last October:

Storage format

By default tracking data is stored within a simple text file called timely-log.txt within the data directory. Storage was intentionally kept this simple so manipulating your trackings could be done with text editors only. This allows for maximal flexibility, but lacks some of the more sophisticated features a database would give us. Trackings are saved chronologically with the most recent tracking on top. Also to allow for easy manual manipulation.

Working with the storage file always requires knowledge of the format in which trackings are saved.

Trackings are based on the following synopsis:

An example tracking looks like this:

An example tracking which was already pushed to a remote time-keeping service (Jira in this example) looks like this:

This contains the name of the service and a timestamp of the actual push.

Pauses utilized by the pause command have the same format, but use a specific identifier so they can be identified as meta information. An example of a pause (e.g. for a lunch break) containing start and end looks like this: