How knbr13/gitcs works
Project Type and Purpose
• Type: Command‐line tool for visualizing Git commit histories locally.
• Purpose: Scan a local Git repository, aggregate commit data by date/author, and render a heatmap graph to the terminal.
File Structure
• main.go – Entry point: parses flags (-path, -email, -since, -until) and orchestrates components.
• scan.go – Implements scanning of the Git repository (calls git log) and parses commit metadata.
• stats.go – Aggregates parsed commit data into a date‐based matrix of commit counts.
• print.go – Renders the heatmap graph to the terminal output.
• utils.go – Shared helpers (e.g., date parsing, flag validation).
• Tests (*_test.go) alongside each module ensure component correctness.
• CI workflows (.github/workflows/*.yaml) automate testing and release.
README for Additional Insights
• External Dependency: Git command‐line tool.
• Data Flow: Local Git repo → scanner → stats aggregator → printer → terminal.
Main Architecture Components
a. CLI Frontend (main.go)
– Flag parsing (Go’s flag package)
– Input validation (paths, dates, email)
– Invokes Scanner, Stats, and Printer
b. Scanner Module (scan.go)
– Executes git log via Go’s os/exec
– Parses raw commit lines into a slice of commit records
c. Statistics Module (stats.go)
– Receives commit records
– Builds a matrix: dates ↔ commit counts
– Applies “since/until” filters
d. Renderer Module (print.go)
– Takes the date/count matrix
– Outputs a terminal-friendly heatmap
e. Utility Module (utils.go)
– Date parsing, validation, shared types
f. External Systems
– Local Git CLI (data source)
– File system (repo directory and .git)
g. CI/CD Pipelines
– GitHub Actions for testing and releases
Relationships and Interactions
• main.go → invokes → scan.go → returns commit records → passed to → stats.go → returns matrix → passed to → print.go → writes to → Terminal
• scan.go ↔ executes ↔ Git CLI
• All modules share utils.go for common functions
• Tests invoke each module in isolation
• CI pipelines trigger go test and go install on push/release
Key Architectural Patterns & Principles
• Modular design: single‐responsibility per Go file
• Pipeline data flow: raw data → processed data → rendered output
• Test‐driven: _test.go files per module
• CLI‐centric: minimal external dependencies beyond Git