How gtlsgamr/tt works
Project type and purpose
• This is a CLI time-tracking tool written as a shell script (“tt”).
• Purpose: let users start/stop tasks, record durations, display reports, and export raw data for piping.
File structure
• Top-level:
• LICENSE
• README.md
• tt (the executable shell script)
• No separate “src” or “lib” folders – all logic lives in the single tt file.
• Configuration resides externally in ~/.config/tt/ (or as specified by $TITTY_CONFIG_DIR).
Key insights from README
• Commands: start, status, stop/raw, display, delete, help.
• Data persistence: writes to a “masterlist” (presumably a flat file) under the config directory.
• Integration point: raw output is piped to other tools.
Main components and interactions
A. User & Shell Environment
• User invokes tt via a shell.
• Environment variables (e.g. $TITTY_CONFIG_DIR) flow in.
B. tt CLI Script
1. Command Parser
– Parses subcommands, arguments, optional time offsets.
2. Timer Engine
– Calculates start/stop times, accumulates durations.
3. Configuration Manager
– Reads/writes config from ~/.config/tt/.
4. Data Storage Interface
– Reads/writes the “masterlist” log file.
5. Output Formatter
– Generates human-readable status/display or raw lines.
C. File System
• Persistent storage of config files and logs.
D. External Tools
• Downstream pipelines consuming “tt raw” output.
• Standard POSIX utilities (date, awk, etc.) invoked by the script.
Relationships and Data Flow:
– User → Shell → tt CLI
– CLI → Command Parser → appropriate subcomponent (Timer, Config, Storage)
– Storage ↔ File System (config + log)
– Output Formatter → STDOUT → User display or pipe to external tools
Architectural patterns and principles
• Single-entry script with modular internal functions.
• Separation of concerns:
• Parsing vs. timing logic vs. persistence vs. formatting.
• Extensibility point: raw output for integration with other reporting tools.
Putting it all together
1. User & Shell
3. File System (config + logs)
4. External Tools
– Ensure labels include file paths, env variables, and command names.