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.

CommandDescriptionrun <input>Log a run entry (or view recent run entries if no input given)check <input>Log a check entry (or view recent check entries if no input given)convert <input>Log a convert entry (or view recent convert entries if no input given)analyze <input>Log an analyze entry (or view recent analyze entries if no input given)generate <input>Log a generate entry (or view recent generate entries if no input given)preview <input>Log a preview entry (or view recent preview entries if no input given)batch <input>Log a batch entry (or view recent batch entries if no input given)compare <input>Log a compare entry (or view recent compare entries if no input given)export <input>Log an export entry (or view recent export entries if no input given)config <input>Log a config entry (or view recent config entries if no input given)status <input>Log a status entry (or view recent status entries if no input given)report <input>Log a report entry (or view recent report entries if no input given)statsShow summary statistics across all log files (entry counts, data size)export <fmt>Export all data in json, csv, or txt formatsearch <term>Full-text search across all log entries (case-insensitive)recentShow the 20 most recent entries from history.loghelpShow usage helpversionShow version (v2.0.0)

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/:

text

~/.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#

bash

# 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:

bash

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

---

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