How jsburckhardt/gic works
Step 1: Identify Project Type and Purpose
• This is a CLI tool (“gic”) written in Go.
• Purpose: Automate git commit message generation by reading staged diffs, feeding them (with user‐provided instructions) to an LLM, and applying the resulting commit message.
Step 2: Analyze the File Structure
• Top‐level binaries:
• main.go + cmd/root.go – entrypoint and cobra CLI commands
• internal/ – core packages:
• config – parses .gic/.env config
• git – wrappers around Git CLI to fetch diffs, stage commits
• llm – abstraction over multiple LLM providers (OpenAI, Azure, Ollama)
• logger – structured logging
• script/install-gic.sh – installs the CLI binary
Step 3: Extract Insights from the README
• Configuration model: .gic or .gic.yaml with llm_instructions
• Environment variables select SERVICE_PROVIDER and credentials
• Workflow: CLI reads config → gathers git diff → calls LLM → prints/applies commit
A. Main Components
1. CLI Frontend
• Cobra-based command (cmd/root.go)
• main.go initialises config & logger
2. Config Loader
• Reads .gic file and .env
• Populates internal/config
3. Git Adapter
• Fetch staged diff (git diff --staged)
• Execute git commit -m or print
4. LLM Adapter
• internal/llm abstracts providers
• Chooses implementation based on SERVICE_PROVIDER
• Communicates over REST/HTTP to OpenAI, Azure, Ollama
5. Logger
• Structured output of errors/info
6. External Services
• OpenAI / Azure OpenAI / Ollama endpoints
1. User invokes gic → CLI Frontend
2. CLI → Config Loader → Config object
3. CLI → Logger initialized
4. CLI → Git Adapter (fetch diff)
5. CLI → LLM Adapter (pass diff + instructions) → External LLM API
6. External LLM API → LLM Adapter (response)
7. CLI → Git Adapter (git commit) or print to stdout
C. Architectural Patterns & Principles
• Single-binary CLI with package-level isolation
• Dependency injection for LLM provider
• Separation of concerns: config, git I/O, LLM I/O, logging
• Interface-based adapters for testability (see internal/git_test.go)
D. Key Technologies and Frameworks
• Go modules (go.mod)
• Cobra (CLI)
• net/http (LLM REST calls)
• Git CLI (shell out)
• Environment configuration (.env, cspell, devcontainer)
• Core functionality: prompt generation, LLM call, git integration
• Extension points: how new LLM providers fit into internal/llm
• Config file and env var injection
Step 6: Diagramming Guidelines
• Internal modules (solid blue)
• Environment variables feeding into config loader
Step 7: Emphasize Detail Without Overcomplicating
• Script or build step only if it affects runtime (e.g., install-gic.sh)
• That each component’s primary responsibility is annotated
• main.go & cmd/root.go at the top
• internal/config, internal/logger feeding into the CLI runtime
• internal/git and internal/llm side by side, each pointing to external systems (Git CLI and LLM APIs)
This will fully capture the gic architecture, highlight extension points, and clearly communicate flows.