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.
| Command | Description |
|---|---|
run <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) |
stats |
Show summary statistics across all log files (entry counts, data size) |
export <fmt> |
Export all data in json, csv, or txt format |
search <term> |
Full-text search across all log entries (case-insensitive) |
recent |
Show the 20 most recent entries from history.log |
help |
Show usage help |
version |
Show 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>.logand writes tohistory.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
- Tracking timed activities — Log start/stop times for tasks, pomodoro sessions, or work intervals throughout the day.
- Comparing performance across runs — Use
compareandanalyzeto log different attempts, thensearchorstatsto review trends. - Batch processing records — Use
batchto log bulk operations, thenexport jsonto feed results into other tools. - Quick status checks in automation — Integrate
stopwatch statusorstopwatch statsinto cron jobs or CI pipelines for operational dashboards. - Generating reports from logged data — Use
reportto log milestones, thenexport csvto 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