Timet

• 🔑 Key Features
• ✔️ Requirements
• Examples
• 💾 Installation
• ⏳ Usage
• 📋 Command Reference
• 🗃️ Data
• 🔒 S3 Cloud Backup Configuration
• Contributing
• License

Timet is a command-line tool designed to track your activities by recording the time spent on each task. This tool allows you to monitor your work hours and productivity directly from your terminal, eliminating the need for a graphical interface. Essentially, it's a way to log your time spent on different projects or tasks using simple text commands.

• Local Data Storage: Timet uses 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. Each column represents the amount of time tracked during a specific hour, with 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.
• Detailed Statistics: Displays detailed statistics for each tag, including total duration, average duration, and standard deviation.
• iCalendar Export: Easily export your time tracking data to iCalendar format for integration with calendar applications.
• S3 Cloud Backup: Seamlessly backup and sync your time tracking data with S3-compatible storage services, providing an additional layer of data protection and accessibility.

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

For older versions of Ruby and Sqlite:

• Ruby >= 2.7
• Ruby >= 2.4

Install the gem by executing:

gem install timet

• 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 [id]: This command allows users to quickly resume tracking a task that was previously in progress. If an ID is provided, it resumes the tracking session for the specified task. If no ID is provided, it resumes the last completed task.

  timet resume 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 |                          |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  

• timet edit: 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 |                          |
  +-------+------------+--------+----------+----------+----------+--------------------------+
  

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).

• 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

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

Timet supports backing up and syncing your time tracking data with S3-compatible storage services (such as Supabase S3). To configure S3 backup, follow these steps:

Create a .env file in your project root (~/.timet) with the following variables:

S3_ENDPOINT=your_s3_endpoint_url
S3_ACCESS_KEY=your_access_key
S3_SECRET_KEY=your_secret_key
S3_REGION=your_s3_region

• Keep your .env file private and never commit it to version control
• Use strong, unique access keys
• Regularly rotate your S3 access credentials
• Implement appropriate IAM policies to restrict bucket access

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.

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.

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

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

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