Timet

Table of Contents

• 🔑 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.

<h2 id="key-features">🔑 Key Features:</h2>

• 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.
• Enhanced Summary Report: Provides a detailed, color-coded explanation of tag distribution, including percentages, total duration, average duration, and standard deviation, via the --report option in the summary command.
• 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.
• Discord Integration: Receive notifications in your Discord channels upon Pomodoro timer completion, enhancing real-time productivity tracking.

Examples:

<a name="requirements"></a>

<h2 id="requirements">✔️ Requirements</h2>

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

For older versions of Ruby and Sqlite:

• Ruby >= 2.7
• Ruby >= 2.4

<a name="installation"></a>

💾 Installation

Install the gem by executing:

gem install timet

<a name="usage"></a>

⏳ 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. This notification is now automatically triggered upon the completion of the Pomodoro timer, ensuring timely alerts.

  Benefits:

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

  Discord Integration

  Timet now supports sending notifications to Discord channels upon Pomodoro timer completion. To enable this feature, you need to configure a webhook in your Discord channel and export the webhook URL as an environment variable.

Setup:

1. Create a Discord Webhook: In your Discord server, go to Server Settings -> Integrations -> Webhooks -> New Webhook. Copy the generated webhook URL.

2. Export Environment Variable: Before running timet, export the webhook URL as DISCORD_WEBHOOK_URL:

   export DISCORD_WEBHOOK_URL="YOUR_DISCORD_WEBHOOK_URL_HERE"
   

   Replace "YOUR_DISCORD_WEBHOOK_URL_HERE" with the actual webhook URL you copied from Discord.

Once configured, Timet will automatically send a notification to your Discord channel when a Pomodoro session ends.

---

---

• 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
  

  To resume with a Pomodoro timer:

  timet resume 1 --pomodoro=25
  

  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
  

  This will edit the last tracked item.

  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"
  

  ``