{"id":15817384,"url":"https://github.com/sumnerevans/tracktime","last_synced_at":"2025-04-01T04:58:04.034Z","repository":{"id":134313533,"uuid":"452349592","full_name":"sumnerevans/tracktime","owner":"sumnerevans","description":"A CLI program that allows you to track time on tasks.","archived":false,"fork":false,"pushed_at":"2023-06-17T00:54:39.000Z","size":460,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-06T05:41:15.418Z","etag":null,"topics":["command-line","csv","time-tracking"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sumnerevans.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"sumnerevans","liberapay":"sumner"}},"created_at":"2022-01-26T16:21:59.000Z","updated_at":"2022-09-07T15:29:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"6a1c0d05-0bfc-4a52-8e2a-6621fb6c39cb","html_url":"https://github.com/sumnerevans/tracktime","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumnerevans%2Ftracktime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumnerevans%2Ftracktime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumnerevans%2Ftracktime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumnerevans%2Ftracktime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sumnerevans","download_url":"https://codeload.github.com/sumnerevans/tracktime/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246586048,"owners_count":20801026,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","csv","time-tracking"],"created_at":"2024-10-05T05:41:21.742Z","updated_at":"2025-04-01T04:58:04.008Z","avatar_url":"https://github.com/sumnerevans.png","language":"Python","funding_links":["https://github.com/sponsors/sumnerevans","https://liberapay.com/sumner","https://liberapay.com/sumner/donate"],"categories":["Time Tracking CLI Tools"],"sub_categories":[],"readme":"# tracktime\n\n[![Lint and Build](https://github.com/sumnerevans/tracktime/actions/workflows/build.yaml/badge.svg)](https://github.com/sumnerevans/tracktime/actions/workflows/build.yaml)\n[![PyPi Version](https://img.shields.io/pypi/v/tracktime?color=4DC71F\u0026logo=python\u0026logoColor=fff)](https://pypi.org/project/tracktime/)\n[![AUR Version](https://img.shields.io/aur/version/tracktime?logo=linux\u0026logoColor=fff)](https://aur.archlinux.org/packages/tracktime/)\n[![LiberaPay Donation Status](https://img.shields.io/liberapay/receives/sumner.svg?logo=liberapay)](https://liberapay.com/sumner/donate)\n\ntracktime is a filesystem-backed time tracking solution. It uses a sane\ndirectory structure to organize CSV files that store time tracking data for each\nday.\n\n## Features\n\n- CLI\n- Start/stop/resume time entries\n- List/edit time entries for a given day\n- Generate rST, PDF, HTML reports for arbitrary date ranges (optionally\n  restricted to a particular customer or project)\n- Synchronise time spent to GitLab using the Time Tracking API\n- Synchronise time spent to Sourcehut via comments on issues\n\n## Installation\n\nUsing PyPi:\n\n    pip install --user tracktime\n\nOn Arch Linux, you can install the `tracktime` package from the AUR. For\nexample, if you use `yay`:\n\n    yay -S tracktime\n\n### Dependencies\n\nReport functionality requires `wkhtmltopdf` to be installed. If you install\nusing the AUR package, this will be installed automatically. Otherwise, you can\ninstall it using your distribution's package manager or visit their\n[homepage](https://wkhtmltopdf.org/) for installation instructions specific to\nyour operating system.\n\nAdditionally, you will need to ensure that the `wkhtmltopdf` executable is in\nyour `$PATH`.\n\n## Guiding Principles\n\n- Filesystem based (want to be able to use Git to keep track of my time entries)\n- Easy to edit manually (not a binary format)\n- Must be able to use offline\n\n## Configuration Options\n\nThere are a number of configuration options that can be set in\n`~/.config/tracktime/tracktimerc`. The `tracktimerc` file is in YAML format.\nHere is a link to an [example\nconfiguration](https://git.sr.ht/~sumner/tracktime/tree/master/examples/tracktimerc).\nBelow is a list of each of the options and what they do.\n\n- `fullname` (`string`) - your full name. This is used for generating reports.\n- `sync_time` (`boolean`, defaults to `false`) - determines whether or not to\n  synchronise with external services.\n- `editor` (`string`) - specifies the editor to use when `tt edit` is run. If\n  this value is not present, the `EDITOR` and `VISUAL` environment variables are\n  used as fallback. If none are present, then `vim` (on non-Windows OSes) or\n  `notepad` (on Windows) is used.\n- `editor_args` (`string`) - a comma separated list of arguments that should be\n  passed to the `editor` when `tt edit` is run.\n- `gitlab` (`dictionary`) - configuration of GitLab parameters\n\n  - `api_root` (`string`, defaults to `'https://gitlab.com/api/v4/'`) - the\n    GitLab API root to use.\n  - `api_key` (`string`) - can be either your GitLab API Key in plain text or a\n    shell command which returns the API key. This second option can be useful if\n    you want to store your API key in a password manager. To indicate that it is\n    a shell command, append a vertical bar (`|`) at the end of the command.\n\n    **Note:** You can create an API key here:\n    https://gitlab.com/profile/personal_access_tokens. The API Key must be\n    created with full API access. Used to sync with GitLab.\n\n- `tableformat` (`string`, defaults to `simple`) - the type of table to generate\n  when exporting a report to stdout. (See the [tabulate\n  documentation](https://bitbucket.org/astanin/python-tabulate#rst-header-table-format)\n  for details on what formats are supported.)\n- `project_rates` (`dictionary`) - a dictionary of project-rate pairs. Used to\n  calculate totals for the report export.\n- `customer_aliases` (`dictionary`) - a dictionary of alias-full name pairs.\n  Used to expand a name on the report export. Useful when a customer has\n  a really long name.\n- `customer_addresses` (`dictionary`) - a dictionary of name-address pairs. Used\n  in the report export.\n- `external_synchroniser_files` - a dictionary of `synchroniser name -\u003e\n  synchroniser Python file`. Allows users to import third party synchronisers.\n- `day_worked_min_threshold` - the number of minutes which must be worked in a\n  day to consider it a work day. This is to avoid days where you work for a few\n  minutes from skewing statistical results.\n\n## Architecture\n\n### Directory Structure\n\n    /\u003croot\u003e\n    |-\u003e 2017\n    |   |-\u003e 01\n    |   |   |-\u003e .synced\n    |   |   |-\u003e 01\n    |   |   |-\u003e 02\n    |   |   |-\u003e ...\n    |   |-\u003e 02\n    |   |-\u003e ...\n    |-\u003e 2018\n\nIn other words, the generic path is `YEAR/MONTH/DAY` where all three fields are\nthe numeric, zero-padded.\n\nEach day with time tracked will have a corresponding file and have the file\nformat as described below.\n\nThe `.synced` file in each month's directory stores the amount of time that has\nbeen reported to the external services.\n\n### Time Tracking File Format\n\nAll time tracking files will be CSVs with the following fields:\n\n- `start` - the start time for the time entry\n- `stop` - the stop time for the time entry\n- `project` - the project for the time entry\n- `type` - the type of entry (gitlab, github, or none)\n- `taskid` - the task ID (issue/PR/MR/story number)\n- `customer` - the customer the entry is for\n- `notes` - any notes about the time entry\n\nThe `start` and `stop` fields will be times, formatted in `HH:MM` where `HH` is\n24-hour time. All other fields are text fields that can hold arbitrary data.\n\n### Synced Time File Format\n\nAll `.synced` files will be CSVs with the following fields:\n\n- `type` - the type of taskid (gitlab, github, or none)\n- `project` - the project that the taskid is associated with\n- `taskid` - the task ID (issue/PR/MR/story number)\n- `synced` - the amount of time that has been successfully pushed to the\n  external service for this taskid\n\n## Synchronising to External Services\n\ntracktime can sync tracked time with external services. It does this by keeping\ntrack of how much time it has been reported to the external service using the\n`.synced` file in each month's directory. Then, it pushes changes to the\nexternal service.\n\n**This is not a two-way sync! tracktime only pushes changes, it does not poll\nfor changes to the external services.**\n\n### Supported External Services\n\n- GitLab\n- Sourcehut\n\n## Unsupported Edge Cases\n\n- Daylight savings time (if you are needing to track time at 02:00 in the\n  morning, I pitty you).\n- Time entries that span multiple days (if you are working that late, create two\n  entries).\n- Timezones (only switch timezones between days, if you have to switch, just\n  make sure that you keep the timezone consistent for a given day).\n\n## Contributing\n\nSee the [CONTRIBUTING.md](./CONTRIBUTING.md) document for details on how to\ncontribute to the project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumnerevans%2Ftracktime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsumnerevans%2Ftracktime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumnerevans%2Ftracktime/lists"}