DEV Community

Cover image for A nice Ruby-based command-line time tracker
Frank Vielma
Frank Vielma

Posted on • Edited on

A nice Ruby-based command-line time tracker

Timet is 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

It uses SQLite to store data locally, so you don't have to worry about losing your data in the cloud. Timet can track time in seconds, minutes, hours, days, etc. This makes it perfect for tracking any kind of task, from short breaks to long projects.

Timet also has a pomodoro integration feature. Pomodoro is a time management technique that involves working in focused 25-minute intervals with short breaks in between. Timet can help you stay on track with your pomodoro sessions and ensure that you're making the most of your time.

With Timet, you can finally take control of your πŸ• and get more done.

πŸ“„ Table of Contents


πŸ”‘ Key Features

  1. Local Data Storage: Uses SQLite for secure and private local data storage.
  2. Lightweight and Fast: Efficient design and local storage ensure speed and responsiveness.
  3. Structured Data: SQLite organizes data for easy access and management.
  4. Scalability: Capable of handling increasing time tracking needs.
  5. Data Integrity: Ensures accuracy and consistency of stored data.
  6. Querying and Reporting: Generate detailed reports for specific periods.
  7. CSV Export: Export time tracking data to CSV for analysis or sharing.
  8. Pomodoro Integration: Enhances time tracking with the Pomodoro Technique.
  9. Block Time Plot: Visualizes time distribution across dates, showing tracked hours.
  10. Tag Distribution Plot: Illustrates the proportion of time allocated to each tag.
  11. Detailed Statistics: Displays detailed statistics for each tag, including total duration, average duration, and standard deviation.
  12. iCalendar Export: Easily export your time tracking data to iCalendar format for integration with calendar applications.
  13. 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.

Timet demo

βœ”οΈ Requirements

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

πŸ’Ύ Installation

Install the gem by executing:

gem install timet
Enter fullscreen mode Exit fullscreen mode

⏳ Usage

Timet offers a straightforward command-line interface for tracking your time.

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

Here's a breakdown of some essential commands:

  • Start Tracking Time:

Use the timet start command to begin tracking time for a specific task using with a note and "pomodoro time" in minutes (optional).

For instance, to start tracking time for a task named "task1", you would run:

timet start task1 --notes="My notes" --pomodoro=25

or 

tt start task1 "My notes" 25
Enter fullscreen mode Exit fullscreen mode
  • Stop Tracking Time:

To stop tracking the current task and record the elapsed time, use the timet stop command. This will also display a report summarizing the total time spent on all tasks.

  • Resume Tracking:

If you need to pause your work and then pick up where you left off, the timet resume command allows you to resume tracking a previously stopped task.

  • Edit a task: To modify the details of a previously recorded task, use the timet edit [id] command. Replace [id] with the unique identifier of the task you wish to edit. This command allows you to update the task's notes, tag, start time, or the end time.

Example:

  timet edit 1 notes "New Meeting Notes"
Enter fullscreen mode Exit fullscreen mode
  • 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
Enter fullscreen mode Exit fullscreen mode
  • Date Range: Display a report for a date range.
  timet su 2024-01-02..2024-01-03
Enter fullscreen mode Exit fullscreen mode
  • Export Time Reports to CSV:

The summary command has the option to export your time data to a CSV file by specifying the --csv flag. For example:

timet su t --csv=summary_today.csv
Enter fullscreen mode Exit fullscreen mode

This will create a CSV file (summary_today.csv) containing all tracked tasks for the current day, making it easy to share or import into other tools. You can use this flag with any of the summary filters (t, y, w, m).

When exporting to CSV, timestamps for start and end times are converted to a readable date format (YYYY-MM-DD HH:MM:SS), ensuring compatibility with software like Excel or LibreOffice.

  • Delete Tasks:

The timet d [id] command allows you to remove unwanted tasks. You can find the task ID from the time reports generated using the summary commands.

  • Cancel Tracking:

Use timet c to stop any active time tracking.

πŸ“‹ Command Reference

Command Description Example Usage
timet start [tag] --notes='' --pomodoro=[time] Start tracking time for a task labeled [tag] and notes (optional). timet start Task "My notes" 25
timet stop Stop tracking time. timet start Task "My notes"
timet summary today (t) Display a report of tracked time for today. timet su t or timet su
timet summary yesterday (y) Display a report of tracked time for yesterday. timet su y
timet summary week (w) Display a report of tracked time for the week. timet su w
timet summary month (m) Display a report of tracked time for the last month. timet su m
timet su t --csv=[filename] Display a report of tracked time for today and export it to filename.csv. timet su t --csv=file.csv
timet resume (r) Resume tracking the last task. timet r
timet delete [id] Delete a task by its ID. timet d [id]
timet cancel Cancel active time tracking. timet c
timet edit [id] Update a task's notes, tag, start or end fields. timet e [1]
timet su [date] Display a report of tracked time for a specific date. timet su 2024-01-03
timet su [start_date]..[end_date] Display a report of tracked time for a date range. timet su 2024-01-02..2024-01-03
timet sync Sync local db with remote (S3) external db timet sync

πŸ“Ž Github

For more information check out here

Top comments (0)