The Repository Dictates the Prompt: Inside git-gen

How a Rust-based CLI uses version-controlled Markdown to force LLMs to write conventional commits without the cognitive overhead.

6 min read · pyk/git-gen

A vintage mechanical clockwork mechanism with a neatly folded paper blueprint sitting inside the glass casing next to the brass gears. This illustrates the concept of instructions living natively alongside the logic in a repository. — By placing a GITGEN.md file in the repository root, git-gen ensures the prompt lives directly next to the code it describes.

Key Takeaways

git-gen shifts LLM prompt engineering from hidden local configurations to version-controlled repository assets via a GITGEN.md file.
The tool structures context gathering by wrapping staged diffs and recent commit history in strict XML tags to prevent LLM hallucination.
Designed as an autocomplete for intent, the CLI preserves developer-provided commit prefixes rather than autonomously overriding human input.
Written in Rust, the single binary features custom error handling and exponential backoff retry logic for robust, compiler-grade terminal UX.

Checking the Prompt into Version Control

The market is flooded with quick bash scripts that pipe git diff into an LLM. The story here is how git-gen treats the AI prompt not as a hidden user preference, but as a repository asset. Instead of relying on global .gitconfig aliases or hidden IDE settings, the tool looks for a GITGEN.md file in the repository root.

This file uses YAML frontmatter for API settings and plain Markdown for the LLM instructions. This ensures that whether a junior developer or a senior maintainer runs the tool, the generated commits adhere to the exact same repository-specific rules. It is a shift from individual preferences to automated compliance.

The XML-Tagged Worldview

The tool does not just read the current diff. It builds a complete worldview for the LLM by analyzing both staged changes and the last ten commits. Crucially, git-gen avoids flat text concatenation. It wraps this data in strict XML tags like <git_diff> and <user_prompt>.

This structured approach gives the LLM a highly organized payload to parse. It reduces the chance of the model confusing project history with the current staged changes, resulting in more accurate and context-aware commit messages.

The Context Assembly Pipeline systematically builds a structured XML payload before making the HTTP request.

A split composition showing a messy pile of torn paper scraps being shoved into a pneumatic mail tube on the left, and neatly sorted folders with stamped metal index tabs sliding into a filing cabinet on the right. This contrasts flat text prompts with strict XML-tagged prompts. — Standard "grep and pray" flat-string prompts versus git-gen's strict XML-tagged prompt architecture.

Finishing the Developer's Thought

The embedded INSTRUCTIONS.md file establishes several non-negotiable rules for the LLM. If a developer provides a hint via the CLI, such as typing git commitgen "feat(ui):", the LLM is strictly instructed to keep that prefix and flesh out the rest.

This design choice turns the tool into an autocomplete for developer intent. It acts as an assistant that respects human input, rather than an autonomous agent attempting to override the developer's contextual knowledge.

Compiler-Grade UX in a Micro-Tool

Written in Rust using the 2024 edition, git-gen elevates itself above typical weekend scripts. It features a custom error-handling framework in src/error.rs that uses notes and helps to provide clean, actionable terminal output for the user.

The Gemini provider implementation includes robust logic for the real world. It utilizes exponential backoff with jitter for 5xx server errors, ensuring the CLI remains reliable even when the underlying LLM API experiences turbulence.