{"id":13530730,"url":"https://github.com/larose/utt","last_synced_at":"2025-04-01T19:30:33.819Z","repository":{"id":9383370,"uuid":"11243271","full_name":"larose/utt","owner":"larose","description":"Ultimate Time Tracker - A simple command-line time tracker written in Python","archived":false,"fork":false,"pushed_at":"2024-07-21T13:10:06.000Z","size":573,"stargazers_count":334,"open_issues_count":5,"forks_count":55,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-05T23:23:22.675Z","etag":null,"topics":["command-line-app","python","time-tracker","timesheet","timetracker"],"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/larose.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","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":"larose"}},"created_at":"2013-07-08T01:24:30.000Z","updated_at":"2025-02-16T16:46:48.000Z","dependencies_parsed_at":"2023-12-09T15:25:04.663Z","dependency_job_id":"44d7ce0d-a336-429f-ae2f-9f4856dc0cd6","html_url":"https://github.com/larose/utt","commit_stats":{"total_commits":265,"total_committers":11,"mean_commits":24.09090909090909,"dds":"0.30188679245283023","last_synced_commit":"8b84653aee815bdcba75a4f8cae95a66adad6bc0"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larose%2Futt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larose%2Futt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larose%2Futt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larose%2Futt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/larose","download_url":"https://codeload.github.com/larose/utt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246700016,"owners_count":20819811,"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-app","python","time-tracker","timesheet","timetracker"],"created_at":"2024-08-01T07:00:54.237Z","updated_at":"2025-04-01T19:30:33.202Z","avatar_url":"https://github.com/larose.png","language":"Python","readme":"Ultimate Time Tracker\n======================\n\nUltimate Time Tracker (utt) is a simple command-line time tracking\napplication written in Python.\n\n**Table of Contents**\n\n\n- [Ultimate Time Tracker](#ultimate-time-tracker)\n  - [Quick Start](#quick-start)\n    - [hello](#hello)\n    - [add](#add)\n    - [report](#report)\n    - [edit](#edit)\n  - [Commands](#commands)\n    - [`hello`](#hello-1)\n    - [`add`](#add-1)\n      - [Activity Type](#activity-type)\n    - [`edit`](#edit-1)\n    - [`report`](#report-1)\n      - [Sections](#sections)\n      - [Report Date](#report-date)\n      - [Current Activity](#current-activity)\n    - [`stretch`](#stretch)\n  - [Plugins](#plugins)\n    - [Plugin development](#plugin-development)\n  - [Configuration](#configuration)\n    - [Timezone](#timezone)\n  - [Bash Completion](#bash-completion)\n  - [Contributing](#contributing)\n  - [Contributors](#contributors)\n  - [License](#license)\n  - [Website](#website)\n\n\n## Quick Start\n\n\n### Prerequisites\n\n`utt` requires Python version 3.7 or above.\n\n\n### Installing `utt`\n\nInstall `utt` from PyPI:\n\n`$ pip install utt`\n\n\n### hello\n\nSay hello when you arrive in the morning:\n\n`$ utt hello`\n\n\n### add\n\nAdd a task when you have finished working on it:\n\n`$ utt add \"programming\"`\n\n\n### report\n\nShow report:\n\n```\n$ utt report\n\n------------------------ Monday, Jul 08, 2013 (week 28) ------------------------\n\nWorking Time: 0h07\nBreak   Time: 0h00\n\n----------------------------------- Projects -----------------------------------\n\n(0h07) : programming\n\n---------------------------------- Activities ----------------------------------\n\n(0h07) : programming\n\n\n----------------------------------- Details ------------------------------------\n\n(0h07) 08:27-08:34 programming\n```\n\n\n### edit\n\nEdit your timesheet:\n\n`$ utt edit`\n\n\n## Commands\n\n### `hello`\n\n`$ utt hello` should be the first command you execute when you start\nyour day. It tells `utt` that you are now tracking your time.\n\nExample:\n\n```\n$ utt hello\n```\n\n### `add`\n\nWhen you have completed a task, add it to `utt` with the `add`\ncommand.\n\nExample:\n\n`$ utt add programming`\n\nYou add a task when you have completed it, not when you start doing\nit.\n\n#### Activity Type\n\nThere are three types of activities: working, break and\nignored. Working activities contribute to the working time, break\nactivities to the break time and ignored activities to neither. This\nfeature is very useful when viewing your timesheet with the `report`\ncommand as it enables `utt` to group your activities by type.\n\nThe activity type is defined by its name. If it ends with `**` it's a\nbreak activity. If it ends with `***` it's an ignored\nactivity. Otherwise, it's a working activity.\n\nExamples:\n\n\n- Working activity\n\n```\n$ utt add \"task #4\"\n```\n\n- Break activity\n\n```\n$ utt add \"lunch **\"\n```\n\n- Ignored activity\n\n```\n$ utt add \"commuting ***\"\n```\n\n\n### `edit`\n\n`edit` opens your timesheet in a text editor so you can edit it.\n\nExample:\n\n```\n$ utt edit\n```\n\n`utt` opens the text editor defined by the environment variable\n`$VISUAL` and, if not set, by the environment variable `$EDITOR`. If\nneither is set, `utt` opens `vi`.\n\n\n### `report`\n\n`$ utt report` shows your timesheet.\n\nExamples:\n\n- Timesheet for today: `$ utt report`\n\n- Timesheet for a specific date: `$ utt report 2018-03-25`\n\n- Timesheet for a period: `$ utt report --from 2018-10-22 --to 2018-10-26`\n\n\n\n#### Sections\n\nThere are four sections in a report. As we will see, each one is a\naggregated view of the previous one.\n\n1. Summary: shows the report date and the total working and break\ntime.\n\n2. Projects: groups activities by project. This is useful to track the\ntotal time by projects. We will see how to specify the project for an\nactivity.\n\n3. Activities: groups activities by name. This is useful to track the\ntotal time worked on a task when you have worked on it multiple times.\n\n4. Details: timeline of your activities.\n\n\nLet's look at an example. Let's say you entered those activities\nthroughout the day:\n\n```\n$ utt hello\n$ utt add \"project-1: task-3\"\n$ utt add \"project-2: task-2\"\n$ utt add \"project-1: task-1\"\n$ utt add \"lunch **\"\n$ utt add \"project-2: task-2\"\n$ utt add \"project-1: task-2\"\n```\n\nAnd then you view your timesheet:\n\n```\n$ utt report\n\n----------------------- Saturday, Nov 03, 2018 (week 44) -----------------------\n\nWorking Time: 7h00\nBreak   Time: 1h00\n\n----------------------------------- Projects -----------------------------------\n\n(5h00) project-1: task-1, task-2, task-3\n(2h00) project-2: task-2\n\n---------------------------------- Activities ----------------------------------\n\n(2h15) project-1: task-1\n(2h15) project-1: task-2\n(0h30) project-1: task-3\n(2h00) project-2: task-2\n\n(1h00) : lunch **\n\n----------------------------------- Details ------------------------------------\n\n(0h30) 09:00-09:30 project-1: task-3\n(0h15) 09:30-09:45 project-2: task-2\n(2h15) 09:45-12:00 project-1: task-1\n(1h00) 12:00-13:00 lunch **\n(1h45) 13:00-14:45 project-2: task-2\n(2h15) 14:45-17:00 project-1: task-2\n```\n\nThe first section, the summary section, shows that you worked 7h and\nhad a 1-hour break.\n\nThen, the projects section shows that you worked 5h on project 1 and\n2h on project 2. You can specify the project of an activity by\nprefixing it with a non-whitespace string followed by a colon (e.g\n`project-1:`, `project2:`).\n\nThe next section, the activities section, shows how long you worked on\neach activity. For instance, even though you worked twice on\n`project-2: task-2` (0h15 + 1h45), it is shown once in that section.\n\nFinally, the details section shows a timeline of all your activity.\n\n\n#### Report Date\n\nYou can choose the report date by passing a date to the `report`\ncommand. The date must be either an absolute date formatted as\n\"%Y-%m-%d\" or a day of the week.\n\nExamples:\n\nAbsolute date:\n\n```\n$ utt report 2013-07-01\n```\n\nDay of the week:\n\n```\n$ utt report monday\n```\n\nIf today is Wednesday, Feb 18, the report date is Monday, Feb 16.\n\nYou can also specify a date range. All the activities will be aggregated for\nthe given time period.\n\nTo report activities from 2013-07-01 00:00:00 to 2013-12-31 23:59:59 :\n```\n$ utt report --from 2013-07-01 --to 2013-12-31\n```\n\nTo report activities since Monday:\n```\n$ utt report --from monday\n```\n\n\n#### Current Activity\n\nA `-- Current Activity --` is inserted if the current time is included in the report range.\n\nThe first duration between the parentheses (1h00) represents the\nworking time without the current activity. The second duration between\nthe parentheses (0h22) represents the duration of the current\nactivity.\n\nExample:\n\n```\n$ utt add \"#12\"\n$ utt report\n\n------------------------ Monday, Jul 08, 2013 (week 28) ------------------------\n\nWorking Time: 1h22 (1h00 + 0h22)\nBreak   Time: 0h00\n\n----------------------------------- Projects -----------------------------------\n\n(1h22) : #12, -- Current Activity --\n\n---------------------------------- Activities ----------------------------------\n\n(1h00) : #12\n(0h22) : -- Current Activity --\n\n...\n```\n\nYou can change the current activity name with the `--current-activity`\nargument.\n\nExample:\n\n```\n$ utt report --current-activity \"#76\"\n\n------------------------ Monday, Jul 08, 2013 (week 28) ------------------------\n\nWorking Time: 1h22 (1h00 + 0h22)\nBreak   Time: 0h00\n\n----------------------------------- Projects -----------------------------------\n\n(1h22) : #12, #76\n\n---------------------------------- Activities ----------------------------------\n\n(1h00) : #12\n(0h22) : #76\n\n...\n```\n\nOr, you can remove the current activity with the\n`--no-current-activity` flag.\n\nExample:\n\n```\n$ utt report --no-current-activity\n\n------------------------ Monday, Jul 08, 2013 (week 28) ------------------------\n\nWorking Time: 1h00\nBreak   Time: 0h00\n\n----------------------------------- Projects -----------------------------------\n\n(1h00) : #12\n\n---------------------------------- Activities ----------------------------------\n\n(1h00) : #12\n```\n\n### `stretch`\n\nStretch the latest task to the current time:\n\nExample:\n\n```\n$ utt stretch\nstretched 2013-07-08 08:34 programming\n        → 2013-07-08 09:00 programming\n```\n\n## Plugins\n\nutt can be extended by installing plugins. Unfortunately, since this\nis a recent feature, no plugins have been listed here yet. Write to\nMathieu Larose \u003c\u003cmathieu@mathieularose.com\u003e\u003e to add your plugin here.\n\n\n### Plugin development\n\nSee\n[docs/CONTRIBUTING.md#how-can-i-create-a-plugin](docs/CONTRIBUTING.md#how-can-i-create-a-plugin)\nhow to create a utt plugin.\n\n\n## Configuration\n\n### Timezone\n\nWarning: timezone is an experimental feature.\n\nTo enable timezone support, get the config filename:\n\n```\n$ utt config --filename\n`/home/\u003cuser\u003e/.config/utt/utt.cfg`\n```\n\nThen, open it with a text editor and change it so it looks like this:\n\n```\n[timezone]\nenabled = true\n```\n\n## Bash Completion\n\n`utt` uses [argcomplete](https://github.com/kislyuk/argcomplete) to\nprovide bash completion.\n\nFirst, make sure\n[`bash-completion`](https://github.com/scop/bash-completion) is\ninstalled:\n\n- Fedora: `$ sudo dnf install bash-completion`\n- Ubuntu: `$ sudo apt-get install bash-completion`\n\n\nThen execute:\n\n```\n$ register-python-argcomplete utt \u003e\u003e ~/.bashrc\n```\n\nFinally, start a new shell.\n\n\n## Contributing\n\nSee [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for how to contribute to utt.\n\n\n## Contributors\n\n- Mathieu Larose \u003c\u003cmathieu@mathieularose.com\u003e\u003e\n- David Munger \u003c\u003cmungerd@gmail.com\u003e\u003e\n- Paul Ivanov \u003c\u003cpi@berkeley.edu\u003e\u003e\n- Jason Stewart \u003c\u003csupport@eggplantsd.com\u003e\u003e\n- Kit Choi \u003c\u003ckit@kychoi.org\u003e\u003e\n- Henrik Holm \u003c\u003cukrutt@gmail.com\u003e\u003e\n- Stephan Gross \u003c\u003cstephangross6@gmail.com\u003e\u003e\n- Kent Martin \u003c\u003ckentaasvang@gmail.com\u003e\u003e\n- fighterpoul \u003c\u003cfighter.poul@gmail.com\u003e\u003e\n\n\n## License\n\nutt is released under the GPLv3. See the LICENSE file for details.\n\n\n## Website\n\nhttp://github.com/larose/utt\n","funding_links":["https://github.com/sponsors/larose"],"categories":["Productivity","Python","Time Tracking CLI Tools","\u003ca name=\"time-tracker\"\u003e\u003c/a\u003eTime trackers"],"sub_categories":["Time Tracking"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarose%2Futt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flarose%2Futt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarose%2Futt/lists"}