timetrap

Create a new timesheet

$ timetrap sheet [timesheet]

$ timetrap in --at "[5 minutes ago]" [entry_notes]

$ timetrap display

$ timetrap edit --end [time]

tt [global_options] command [command_options] [arguments]

tt start [project_name]
    Begins tracking time for a new entry. If project_name is specified, it assigns that project to the entry. If an entry is currently active, it will automatically stop the existing one before starting the new entry.

tt stop
    Ceases time tracking for the currently active entry.

tt status
    Displays the current time tracking status, including the ID of the active entry, its project, start time, and elapsed duration.

tt display
    Outputs a summary of time entries. By default, it shows entries for the current day or a recent period. This command offers numerous options to filter, sort, and format the output.

tt today / tt week / tt month / tt year
    Convenience commands to display time entries specifically for the current day, week, month, or year, respectively.

tt total
    Calculates and displays the cumulative tracked time for all entries on the current sheet.

tt sum
    Presents the total time spent per project for the current sheet and the specified time period (e.g., current day, week).

tt sheet [sheet_name]
    Switches to an existing time tracking sheet or creates a new one. If sheet_name is omitted, it lists all available sheets. Sheets help organize time tracking into distinct contexts (e.g., 'Work', 'Personal').

tt list
    Lists all available time tracking sheets.

tt edit [ID]
    Opens a text editor (configured via the $EDITOR environment variable) to modify the details of a specific time entry identified by its ID. This allows adjusting start/end times, project names, or adding/editing notes.

tt delete [ID]
    Removes a time entry specified by its ID from the database.

tt punch [ID]
    If an ID is provided, it stops the current entry (if any) and restarts the specified entry. If no ID is given, it restarts the most recently stopped entry.

-m <message> (with start)
    Attaches a message or note to the time entry when it is started.

--at <time> (with start/stop)
    Specifies a custom start or stop time for the entry, useful for backdating or correcting records. Time can be in various common formats (e.g., 'HH:MM', 'YYYY-MM-DD HH:MM').

-l <limit> (with display)
    Restricts the number of time entries shown in the display output.

-s <start_date>, -e <end_date> (with display)
    Filters displayed entries to a specific date range, using various date formats.

--csv (with display)
    Outputs the displayed time data in Comma Separated Values (CSV) format, suitable for spreadsheet applications.

--json (with display)
    Outputs the displayed time data in JSON (JavaScript Object Notation) format, suitable for programmatic parsing.

--version
    Displays the installed version information of the timetrap utility.

--help
    Shows the general help message or detailed help for a specific command.

timetrap, commonly invoked as tt, is a simple and flexible command-line utility designed for tracking time spent on various projects and tasks. It enables users to quickly punch in when starting a task, punch out when finishing, and generate comprehensive reports on their time spent. Its lightweight nature and command-line interface make it an ideal tool for developers, freelancers, or anyone who prefers managing their time efficiently without a bulky graphical application.

The tool stores data locally, typically in a SQLite database, providing users with full control over their timekeeping records. Key features include the ability to manage multiple 'sheets' for different contexts, add descriptive notes to entries, easily edit past records, and display time logs in various formats, such as human-readable tables, CSV, or JSON. timetrap focuses on simplicity and efficiency, allowing seamless integration of time tracking into one's daily workflow.

timetrap is exclusively a command-line tool, meaning it does not offer a graphical user interface. While efficient for CLI-savvy users, newcomers might experience a slight learning curve. Data is stored locally in a SQLite database, typically at ~/.timetrap.db, which simplifies management but necessitates manual backup for cross-device synchronization or cloud storage. It relies on the system's timezone settings for accurate timekeeping. Although generally very fast, managing exceptionally large datasets over extended periods might eventually lead to minor performance considerations.

timetrap stores all its time entry data in a single SQLite database file, which defaults to ~/.timetrap.db in the user's home directory. This makes the data highly portable and straightforward to back up. Users can override the default database location by setting the TIMETRAP_DB environment variable, allowing for custom database paths or the management of multiple distinct databases. Other configuration preferences, such as the default text editor for modifying entries (used by tt edit), are typically managed through standard shell environment variables like $EDITOR or by defining shell aliases, ensuring deep integration with a user's preferred shell environment.

A significant strength of timetrap lies in its highly flexible reporting capabilities. Beyond the versatile built-in display command, which supports various output formats (including CSV and JSON), users can leverage external tools or custom scripts to process the raw data. Since the data resides in a standard SQLite database, it can be directly queried using SQL commands or parsed programmatically to generate highly specialized reports, integrate with invoicing systems, or feed into analytics dashboards. This extensibility makes timetrap a powerful backend for more complex and customized time management workflows.

timetrap was initially created by Scott Chacon, a prominent figure in the Git community, driven by his personal need for a simple, non-intrusive method to track project time directly from the terminal. Its design adheres to the Unix philosophy of doing one thing well, focusing on robust time-tracking without unnecessary features. As a Ruby-based application, it quickly gained traction among developers due to its ease of installation via RubyGems and its inherent hackability. Over the years, the tool has been actively maintained and enhanced by the open-source community, incorporating new features like multiple sheets and improved reporting while steadfastly retaining its core simplicity and command-line focus.

date(1), at(1), cron(8), tmux(1)