Package: tracktime
tracktimetracktime is a filesystem-backed time tracking solution. It uses a sane
directory structure to organize CSV files that store time tracking data for each
day.FeaturesCLIStart/stop/resume time entriesList/edit time entries for a given dayGenerate rST, PDF, HTML reports for arbitrary date ranges (optionally
restricted to a particular customer or project)Synchronise time spent to GitLab using the Time Tracking APISynchronise time spent to Sourcehut via comments on issuesInstallationUsing PyPi:pip install --user tracktimeOn Arch Linux, you can install thetracktimepackage from the AUR. For
example, if you useyay:yay -S tracktimeDependenciesReport functionality requireswkhtmltopdfto be installed. If you install
using the AUR package, this will be installed automatically. Otherwise, you can
install it using your distribution's package manager or visit theirhomepagefor installation instructions specific to
your operating system.Additionally, you will need to ensure that thewkhtmltopdfexecutable is in
your$PATH.Guiding PrinciplesFilesystem based (want to be able to use Git to keep track of my time entries)Easy to edit manually (not a binary format)Must be able to use offlineConfiguration OptionsThere are a number of configuration options that can be set in~/.config/tracktime/tracktimerc. Thetracktimercfile is in YAML format.
Here is a link to anexample
configuration.
Below is a list of each of the options and what they do.fullname(string) - your full name. This is used for generating reports.sync_time(boolean, defaults tofalse) - determines whether or not to
synchronise with external services.editor(string) - specifies the editor to use whentt editis run. If
this value is not present, theEDITORandVISUALenvironment variables are
used as fallback. If none are present, thenvim(on non-Windows OSes) ornotepad(on Windows) is used.editor_args(string) - a comma separated list of arguments that should be
passed to theeditorwhentt editis run.gitlab(dictionary) - configuration of GitLab parametersapi_root(string, defaults to'https://gitlab.com/api/v4/') - the
GitLab API root to use.api_key(string) - can be either your GitLab API Key in plain text or a
shell command which returns the API key. This second option can be useful if
you want to store your API key in a password manager. To indicate that it is
a shell command, append a vertical bar (|) at the end of the command.Note:You can create an API key here:https://gitlab.com/profile/personal_access_tokens. The API Key must be
created with full API access. Used to sync with GitLab.tableformat(string, defaults tosimple) - the type of table to generate
when exporting a report to stdout. (See thetabulate
documentationfor details on what formats are supported.)project_rates(dictionary) - a dictionary of project-rate pairs. Used to
calculate totals for the report export.customer_aliases(dictionary) - a dictionary of alias-full name pairs.
Used to expand a name on the report export. Useful when a customer has
a really long name.customer_addresses(dictionary) - a dictionary of name-address pairs. Used
in the report export.external_synchroniser_files- a dictionary ofsynchroniser name -> synchroniser Python file. Allows users to import third party synchronisers.day_worked_min_threshold- the number of minutes which must be worked in a
day to consider it a work day. This is to avoid days where you work for a few
minutes from skewing statistical results.ArchitectureDirectory Structure/<root>
|-> 2017
|   |-> 01
|   |   |-> .synced
|   |   |-> 01
|   |   |-> 02
|   |   |-> ...
|   |-> 02
|   |-> ...
|-> 2018In other words, the generic path isYEAR/MONTH/DAYwhere all three fields are
the numeric, zero-padded.Each day with time tracked will have a corresponding file and have the file
format as described below.The.syncedfile in each month's directory stores the amount of time that has
been reported to the external services.Time Tracking File FormatAll time tracking files will be CSVs with the following fields:start- the start time for the time entrystop- the stop time for the time entryproject- the project for the time entrytype- the type of entry (gitlab, github, or none)taskid- the task ID (issue/PR/MR/story number)customer- the customer the entry is fornotes- any notes about the time entryThestartandstopfields will be times, formatted inHH:MMwhereHHis
24-hour time. All other fields are text fields that can hold arbitrary data.Synced Time File FormatAll.syncedfiles will be CSVs with the following fields:type- the type of taskid (gitlab, github, or none)project- the project that the taskid is associated withtaskid- the task ID (issue/PR/MR/story number)synced- the amount of time that has been successfully pushed to the
external service for this taskidSynchronising to External Servicestracktime can sync tracked time with external services. It does this by keeping
track of how much time it has been reported to the external service using the.syncedfile in each month's directory. Then, it pushes changes to the
external service.This is not a two-way sync! tracktime only pushes changes, it does not poll
for changes to the external services.Supported External ServicesGitLabSourcehutUnsupported Edge CasesDaylight savings time (if you are needing to track time at 02:00 in the
morning, I pitty you).Time entries that span multiple days (if you are working that late, create two
entries).Timezones (only switch timezones between days, if you have to switch, just
make sure that you keep the timezone consistent for a given day).ContributingSee theCONTRIBUTING.mddocument for details on how to contribute to the project.