{"id":25765511,"url":"https://github.com/jidn/idid-rust","last_synced_at":"2025-02-26T22:19:38.897Z","repository":{"id":237975891,"uuid":"795613699","full_name":"jidn/idid-rust","owner":"jidn","description":"A command-line tool for keeping track of time spent on various tasks or accomplishments. It allows users to record, edit, and view their activities in a simple, structured format.","archived":false,"fork":false,"pushed_at":"2025-02-12T15:34:22.000Z","size":109,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-12T16:35:15.688Z","etag":null,"topics":["cli","rust","time","track"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jidn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-MIT","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}},"created_at":"2024-05-03T16:49:36.000Z","updated_at":"2025-02-12T15:34:26.000Z","dependencies_parsed_at":"2025-02-12T16:38:02.489Z","dependency_job_id":null,"html_url":"https://github.com/jidn/idid-rust","commit_stats":null,"previous_names":["jidn/idid-rust"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jidn%2Fidid-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jidn%2Fidid-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jidn%2Fidid-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jidn%2Fidid-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jidn","download_url":"https://codeload.github.com/jidn/idid-rust/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240941959,"owners_count":19882123,"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":["cli","rust","time","track"],"created_at":"2025-02-26T22:19:38.324Z","updated_at":"2025-02-26T22:19:38.889Z","avatar_url":"https://github.com/jidn.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# idid\n\n[![Build Status](https://github.com/jidn/idid-rust/actions/workflows/rust.yml/badge.svg)](https://github.com/jidn/idid-rust/actions/workflows/rust.yml)\n[![Crates.io](https://img.shields.io/crates/v/idid)](https://crates.io/crates/idid)\n![Crates.io Downloads (recent)](https://img.shields.io/crates/dr/idid)\n\n**Idid** is a command-line tool for tracking time spent and kept in a simple, structured format.\n\n---\n\n**Table of Contents**\n\n- [Why another time tracker](#why)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n  - [Start your day](#start-your-day)\n  - [Add entry](#additional-activity)\n  - [Edit entries](#edit-your-history)\n  - [What did I last do?](#what-did-i-last-do)\n  - [Show your day](#show-your-day)\n    - [DATE formats](#date-formats)\n- [Usage](#usage)\n  - [Commands](#commands)\n  - [Options](#options)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Why\n\nWhy another time tracker? Simply, the others didn't meet my needs. I wanted:\n\n- Easy command line.\n- Simple data structure.\n- Simple to edit and modify.\n- Geared for my needs, not any manger or corprate desires.\n- Focus on what I actually did, not what I planned on doing; these are not the same.\n\n**Easy command line**.\nThere are only five commands: start, add, edit, last, and show.\nOf thoses you could be happy only knowing the first three.\nSome of the other popular time trackers have well over 15 different commands, far too many.\n\n**Simple data structure**.\nIt is a two column tab-separated-value (TSV) file.\nThe timestamp and a text description of what I did.\nNo start time or duration is needed as it can be calculated from the previous entry.\n\n**Simple to edit and modify**.\nThis tool does not attempt to make changes.\nThe possibilities are vast, so you edit the TSV file directly.\nYou want to insert a task?\nJust add a row and because start and duration is calculated from previous rows you don't need to modify an others.\n\n**Geared for my needs**.\nI wanted to accurately track interuptions; people dropping by needing help, mentoring, or solving problems.\nI also was curious about the actual amount of time I spent on various activities and discovered it didn't match what I remembered in a day or two.\n\n**Focus on what I did**.\nMost of the alternate solutions start with the premis, \"I plan to start THIS.\"\nWhat I quickly discovered is planning rarely survives the actual encounter.\nSo I needed to record what I did.\nIt is at this point I can reflect.\nIf an interruption is happening, I can quickly jot down what I was doing with work-in-progress \"@WIP\".\n\n### Evolution of `idid`\n\nThis started as a simple bash script, adding features as I needed.\nIt worked well.  \nEventually, it moved to Python for duration calculation; see `idid show --help`.\nHowever, I got frustrated with [externally managed systems](https://peps.python.org/pep-0668) when setting `idid` up on other machines.\nI was learning Rust and here was an opportunity to migrate to an app, dragging my TSV file with me.\n\n## Installation\n\nThere are a number of ways to install `idid` either repository, cargo, or Arch Linux makepkg.\nRead the [INSTALL.md](INSTALL.md) file for details.\n\n## Quick Start\n\n`idid` revolves around the idea of recording what you just did, hence the name `idid`.\nAs you record your activity, the duration is calculated from your previous entry.\nThus, your first entry for the day is starting.\n\n### Start your day\n\nYour first accomplishment of the day is just to start `idid` recording for the day.\n\n```sh\nidid start\nStarting at 07:55 AM.  All right!\n```\n\nWow, nice feedback. If you prefer no response, just use the `--quiet` flag.\n\nAltering the start time is easy. Just give it the number of minutes ago or the time.\nFor example, as I was coming in, Tim stopped me in the hall for about 10 minutes going over an item and it is now 8:05 am.\n\n```sh\nidid start -t 10\nStarting at 07:55 AM.  Keep it up.\n\nidid start -t 7:55\nStarting at 07:55 AM.  Sensational.\n```\n\n### Additional activity\n\nAs you finish a task, milestone, or item of note, record what you did.\n\n```sh\nidid add +project spoke with Tim\n00:10  Super.\n```\n\nand 25 minutes later\n\n```sh\nidid add cleared inbox\n00:25  Well done!\n```\n\nNice. I see the duration in HH:MM format and some positive feedback.\n\nLater on, you forgot to record fixing an issue 10 minutes ago at 9:50.\nTo alter the time, use the `-t` option with either the number of minutes or the time.\n\n```\nidid add -t 10 fixed issue #42\nMon 09:50 AM for 01:30  Well done!\n```\n\nor\n\n```sh\nidid add -t 9:50 fixed issue #42\nMon 09:50 for 01:30  Well done!\n```\n\nNotice there is more information about when the task started.\n\nRemember you are typing in your shell so some characters will cause problems.\nThe most common issues are single quotes, semi-colons, redirection, and ampersands.\nYou will have to quote them or use natural language.\n\n### Multiple, distinct activity/projects\n\nFreelancers need to track multiple projects/client as they switch tasks throughout the day.\nI use a [TodoTxt.org](https://github.com/todotxt/todo.txt?tab=readme-ov-file#context)\ncontext tag at the beginning of `add` text, a word starting with a plus sign.\nUse whatever works best for you.\n\n```sh\nidid add -q \"+acme emailed CJ on next steps\"\n```\n\nUse command line tools filter results.\n\n```sh\nidid show today | grep '+acme'\n```\n\n### Noncontiguous: lunch and extended breaks\n\nLunch or extended breaks may not be something you want to track.\nFor some reason, those to whom I report do not want that time included.\nAdd an entry before leaving about what you have done up to that point with `idid add 'project poodles work-in-progress (WIP)'` or something similar.\nNow use `idid start` after returning.\nHowever, if you want to document your time, use a personal context or whatever makes sense to you and your workflow.\n\n```sh\nidid add +personal hotdog lunch at Costco\n```\n\n### Edit your history\n\nIf you need to alter time, insert an entry, or edit an entry; just edit the TSV file and everything adjusts accordingly.\nThe `edit` sub-command allows you to quickly use the vi family of editors open the TSV file and place you at the file's end.\n\n```shell\nidid edit\n```\n\nIf you are using another text editor. The file is usually found at `$XDG_DATA_HOME/idid/idid.tsv` or `~/.local/share/idid/idid.tsv`.\n\nNow you can make changes.\n\n- Remove that double entry.\n- Add the accomplishment you forgot.\n- Fix the typos.\n\nThings to remember.\n\n- The TSV must be in chronological order. The start and duration depends on it.\n- Blank lines and comments are not allowed.\n- Do not alter the start text \"`*~*~*--------------------`\".\n\n### What did I last do?\n\nOpening the TSV file is a bit of an overkill to answer the question.\nYou can use `last` without any arguments to see the duration from the last time you added anything.\nIf you give last a number then it will show that number of entries in the TSV.\n\n```sh\nidid last\n00:25\n```\n\nIt has been 25 minutes from my last entry. Time is flying past.\n\n```sh\nidid last 3\n2024-04-01T10:40:24-05:00\tIssue #680 solution tested\n2024-04-01T08:57:43-05:00\tHelp CJ with @ACME problem\n2024-04-01T08:43:07-05:00\tIssue #680 fix +WIP\n```\n\nNote the most recent is first, and you can see I recorded helping CJ.\nNow I have choices. Do I make edits or can I just add a new entry?\n\n### Show your day\n\nIt would be nice to show a list entries for today.\n\n```shell\n$ idid show today\n2024-04-01T15:02:24-05:00\t00:10  emailed status update to PH\n...  (redacted)\n2024-04-01T08:02:25-05:00\t00:04  daily planning\n```\n\nThis is not a neat report. It is not a report at all.\nIt is simple a dump of all of today's entries with the duration in HH:MM format.\nAnd yes, I know the date looks a bit funny. It is a format specified in [RFC 3339](http://tools.ietf.org/html/rfc3339).\nWhile \"readable\" may be debated, it has several benefits as it remains in chronological order when sorted, is strictly defined, and has common library support.\nYou can give any number of **`[DATE](#date-format)`**s or use the `--range` with two dates to get all entries within the range.\n\nThis consistant output format allows you to create additional tools to transforms the information for reporting, invoicing, or whatever your mind dreams up. See [group-by-day.sh](scripts/group-by-day.sh) as an example.\n\nThere are a couple of options to help with additional processing.\nYou can get the duration in seconds and json output rather than TSV.\nI hope these convience will help in creating new external processing tools.\nSee `idid show --help` for details.\n\n#### DATE formats\n\nThe word `today` is a special `DATE`, as is `yesterday`.\nYou can also use the number of days in the past and `idid show 0` is the same as `idid show today`.\nWhile `DATE` as a number is difficult to use for anything over a handful of digits, any number less than a thousand is valid.\n\nA much easier format is the two-digit month and day as **`MM-DD`** or **`MMDD`**; the dash is optional.\nAs long as the date is within the last 264ish days, you don't need to specify the year.\n\nTo specify the year, use **`YYYY-MM-DD`** or **`YY-MM-DD`** assuming date is after the year 2000.\nAgain, dashes are optional in calendar dates.\n\nJust remember that if today is Monday, then 'mon' is last Monday not today.\nIf you want to add additional weeks, append a number to the DOW.\nThe Monday one week before the last Monday is `mon1`.\n\nIf today were Monday, April 1, 2024, then Sunday, March 31, 2024, could be represented by any of the following:\n\n- sun\n\n* yesterday\n* 1\n* 03-31 or 0331\n* 2024-03-31, 240331, or 20240331\n\nI know. It seems a bit excessive. But I use them, so use the ones that work best for your needs.\nIf you need a quick reminder, execute `idid show --help`.\n\n## Usage\n\nThe idid tool provides several commands and options for managing your accomplishments. Here's a brief overview:\n\n### Commands\n\n- **start**: Start recording time for the day.\n- **add**: Add a new accomplishment.\n- **edit**: Edit the TSV (Tab-Separated Values) file using your default editor.\n- **last**: See the duration from today's last entry or display a specific number of lines from the TSV file.\n- **show**: Show selected accomplishments.\n\n### Options\n\n- `--tsv \u003cFILE\u003e`: Specify a custom TSV file instead of the default location.\n- `-h, --help`: Display help information.\n- `-V, --version`: Display the version of **idid**.\n\nFor detailed usage instructions and examples, run `idid --help` or `idid \u003ccommand\u003e --help`.\n\n## Contributing\n\nContributions to idid-rust are welcome! If you'd like to contribute, please follow these steps:\n\n- Fork the repository.\n- Create your feature branch (`git checkout -b feature/my-feature`).\n- Commit your changes (`git commit -am 'Add new feature'`).\n- Push to the branch (`git push origin feature/my-feature`).\n- Create a new Pull Request.\n\n## License\n\n`idid` is distributed under the terms of the [MIT license](LICENSE-MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjidn%2Fidid-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjidn%2Fidid-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjidn%2Fidid-rust/lists"}