Stopwatch

Stopwatch v2.0.0 — a versatile utility toolkit for logging, tracking, and managing time-related entries from the command line. Each command logs timestamped entries to individual log files, provides history viewing, summary statistics, data export, and full-text search across all records.

Commands

Run stopwatch <command> [args] to use.

How It Works

Every command (run, check, convert, analyze, etc.) works the same way:

• With arguments: Saves a timestamped entry (YYYY-MM-DD HH:MM|input) to <command>.log and writes to history.log.
• Without arguments: Displays the 20 most recent entries from that command's log file.

This gives you a lightweight, file-based logging system for any kind of time-tracking workflow.

Data Storage

All data is stored locally in ~/.local/share/stopwatch/:

~/.local/share/stopwatch/
├── run.log          # Run entries (timestamp|value)
├── check.log        # Check entries
├── convert.log      # Convert entries
├── analyze.log      # Analyze entries
├── generate.log     # Generate entries
├── preview.log      # Preview entries
├── batch.log        # Batch entries
├── compare.log      # Compare entries
├── export.log       # Export entries
├── config.log       # Config entries
├── status.log       # Status entries
├── report.log       # Report entries
├── history.log      # Master activity log
└── export.<fmt>     # Exported data files

Override the data directory by setting STOPWATCH_DIR (if supported) or editing the DATA_DIR variable in the script.

Requirements

• Bash (4.0+)
• Standard POSIX utilities: date, wc, du, tail, grep, sed, cat
• No external dependencies — works on any Linux or macOS system out of the box

When to Use

1. Tracking timed activities — Log start/stop times for tasks, pomodoro sessions, or work intervals throughout the day.
2. Comparing performance across runs — Use compare and analyze to log different attempts, then search or stats to review trends.
3. Batch processing records — Use batch to log bulk operations, then export json to feed results into other tools.
4. Quick status checks in automation — Integrate stopwatch status or stopwatch stats into cron jobs or CI pipelines for operational dashboards.
5. Generating reports from logged data — Use report to log milestones, then export csv to create spreadsheets or feed into reporting tools.

Examples

# Log a run entry
stopwatch run "Morning sprint: 25 minutes"

# Check recent activity
stopwatch recent

# View all run entries
stopwatch run

# Search for a specific term across all logs
stopwatch search "sprint"

# Get summary statistics
stopwatch stats

# Export everything to JSON
stopwatch export json

# Export to CSV for spreadsheet import
stopwatch export csv

Output

All commands output to stdout. Redirect to a file if needed:

stopwatch stats > report.txt
stopwatch export json  # writes to ~/.local/share/stopwatch/export.json

Powered by BytesAgain | bytesagain.com | hello@bytesagain.com