Timet

Timet refers to a command-line tool designed to track your activities by recording the time spent on each task, allowing you to monitor your work hours and productivity directly from your terminal without needing a graphical interface; essentially, it's a way to log your time spent on different projects or tasks using simple text commands

🔑 Key Features:

• Local Data Storage: Timet utilizes SQLite to store your time tracking data locally, ensuring privacy and security.
• Lightweight and Fast: Its efficient design and local data storage make Timet a speedy and responsive tool.
• Structured Data: SQLite ensures your data is organized and easily accessible.
• Scalability: Timet can handle growing time tracking needs.
• Data Integrity: SQLite maintains the accuracy and consistency of your data.
• Querying and Reporting: Generate detailed reports for specific periods.
• CSV Export: Easily export your time tracking data to CSV format for further analysis or sharing.
• Pomodoro Integration: The pomodoro option in the start command enhances time tracking by integrating the Pomodoro Technique.
• Block Time Plot: Visualizes the distribution of tracked time across a specified range of dates, with bars in each column representing the amount of time tracked during that specific hour. The plot includes a header showing the hours and a row for each date, displaying the time blocks for each hour.
• Tag Distribution Plot: Illustrates the proportion of total tracked time allocated to each tag, showing the relative contribution of each tag to the overall time tracked.

Examples:

✔️ Requirements

• Ruby version: >= 3.0.0
• sqlite3: > 1.7

Old versions of Ruby and Sqlite:

• Ruby >= 2.7

• Ruby >= 2.4

💾 Installation

Install the gem by executing:

gem install timet

⏳ Usage

Command Aliases

• timet: The primary command for interacting with the Timet application.
• tt: An alias for the timet command, providing a shorter alternative.

• timet start [tag] --notes="" --pomodoro=[minutes]: Starts tracking time for a task labeled with the provided [tag], notes and "pomodoro time" in minutes (optional). Example:

  timet start task1 --notes="Meeting with client" --pomodoro=25
  
  or
  
  tt start task1 "Meeting with client" 25
  

  Tracked time report [today]:
  +-------+------------+--------+----------+----------+----------+--------------------------+
  | Id    | Date       | Tag    | Start    | End      | Duration | Notes                    |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  |     1 | 2024-08-09 | task1  | 14:55:07 |        - | 00:00:00 | Meeting with client      |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  |                                           Total:  | 00:00:00 |                          |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  

  This command will initiate a 25-minute Pomodoro session for the task "task1" with the provided description.

  Pomodoro Integration

  The pomodoro option in the start command enhances time tracking by integrating the Pomodoro Technique. Users can specify a Pomodoro session length in minutes, like pomodoro=25, to start a 25-minute work interval. The app automatically tracks time and notifies users when the interval ends, helping maintain focus.

  Benefits

  • Flexibility: Supports various productivity strategies.
  • Focus: Encourages disciplined work practices.
  • Productivity: Helps achieve higher productivity and better time management.

• timet stop: Stops tracking the current task, records the elapsed time, and displays the total time spent on all tasks.

  timet stop
  

  Tracked time report [today]:
  +-------+------------+--------+----------+----------+----------+--------------------------+
  | Id    | Date       | Tag    | Start    | End      | Duration | Notes                    |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  |     1 | 2024-08-09 | task1  | 14:55:07 | 15:55:07 | 01:00:00 | Meeting with client      |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  |                                           Total:  | 01:00:00 |                          |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  

• timet resume: It allows users to quickly resume tracking a task that was previously in progress.

  Tracked time report [today]:
  +-------+------------+--------+----------+----------+----------+--------------------------+
  | Id    | Date       | Tag    | Start    | End      | Duration | Notes                    |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  |     2 | 2024-08-09 | task1  | 16:15:07 |        - | 00:00:00 | Meeting with client      |
  |     1 |            | task1  | 14:55:07 | 15:55:07 | 01:00:00 | Meeting with client      |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  |                                           Total:  | 01:00:00 |                          |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  

• timet edit: It allows users to update a task's notes, tag, start, or end fields. Users can either interactively select the field and provide a new value or specify them directly in the command.

• Interactive Mode:

  timet edit 1
  

  Tracked time report [today]:
  +-------+------------+--------+----------+----------+----------+--------------------------+
  | Id    | Date       | Tag    | Start    | End      | Duration | Notes                    |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  |     2 | 2024-08-09 | task1  | 16:15:07 |        - | 00:00:00 | Meeting with client      |
  |     1 |            | task1  | 14:55:07 | 15:55:07 | 01:00:00 | Meeting with client      |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  |                                           Total:  | 01:00:00 |                          |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  Edit Field? (Press ↑/↓ arrow to move and Enter to select)
  ‣ Notes
    Tag
    Start
    End
  

• Direct Specification Mode:

  timet e 1 notes "New Meeting Notes"
  

  Tracked time report [today]:
  +-------+------------+--------+----------+----------+----------+--------------------------+
  | Id    | Date       | Tag    | Start    | End      | Duration | Notes                    |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  |     2 | 2024-08-09 | task1  | 16:15:07 |        - | 00:00:00 | Meeting with client      |
  |     1 |            | task1  | 14:55:07 | 15:55:07 | 01:00:00 | New Meeting Note         |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  |                                           Total:  | 01:00:00 |                          |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  

📋 Command Reference

Date Range in Summary

The timet summary command now supports specifying a date range for generating reports. This allows users to filter and summarize data within specific date intervals. The date format is in ISO 8601 format (YYYY-MM-DD).

Examples:

• Single Date: Display a report for a specific date.

  timet su 2024-01-03
  

• Date Range: Display a report for a date range.

  timet su 2024-01-02..2024-01-03
  

Data

Timet's data is stored in ~/.timet.db

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/frankvielma/timet. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Buy Me A Coffee! ☕

Many people have contacted me asking how to contribute. Any contribution, from a virtual coffee to a kind word, is greatly appreciated and helps me continue my work. Please only donate if you're able, as there are no refunds. Your support is entirely voluntary, and I thank you for your consideration.

Bitcoin Address:

bc1qkg9me2jsuhpzu2hp9kkpxagwtf9ewnyfl4kszl

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Timet project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.