AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Development Commands

  • Build: just build (outputs binary as formatted-commit)
  • Run during development: just run [flags]
  • Format code: just fmt
  • Update dependencies: go mod tidy
  • Test: go test ./...

Example usage:

just run -t feat -m "add validation" -T "Co-authored-by: Name <email>"

Project Purpose

This is a CLI tool that formats git commit messages according to Conventional Commits specification and pipes them directly to git commit -F -. It enforces:

  1. Subject length: max 50 characters in format type(scope): message
  2. Body wrapping: strictly 72 columns using Markdown formatter
  3. Trailer validation: follows git's trailer specification

Architecture

Single-file CLI application (main.go) using:

  • cobra: CLI framework for flags and commands
  • fang: Charmbracelet's execution wrapper (provides version handling, etc.)
  • Future: Will need a Markdown formatter for body text (likely from Charmbracelet ecosystem based on dependencies)

Critical Implementation Details

Subject Validation (50 char limit)

The subject is constructed as type(scope): message or type: message (when scope is empty). Breaking changes add a ! after the type/scope like type(scope)!: message.

When validation fails, clearly mark where the subject exceeds 50 characters in error output.

Body Formatting

The body (-b flag) must be:

  1. Sanitised because it should only be basic text and bullets
  2. Formatted as Markdown, properly wrapping bullets with hanging indents on following lines like this
  3. Strictly wrapped to 72 columns using a pure-Go formatter
  4. Separated from subject by one blank line
  5. Separated from trailers by one blank line

Trailer Formatting (Critical)

Trailers follow git's specification precisely:

  • Format: Key: value (newline-delimited pairs)
  • No whitespace before or inside the key
  • Any number of spaces/tabs allowed between key and separator :
  • Values can be multiline with continuation lines starting with whitespace (RFC 822 folding)
  • The trailer group must be:
    • At the end of input, OR
    • The last non-whitespace lines before a line starting with ---
    • Preceded by one or more empty/whitespace-only lines

Example valid trailer:

Co-authored-by: This is a very long value, with spaces and
  newlines in it.

Flag Nuance

  • -B / --breaking: Boolean flag for breaking changes (adds ! to subject)
  • -b / --body: String flag for commit body text
  • -T / --trailer: Repeatable flag for trailers

Final Output

The formatted commit message must be piped to git commit -F - to read from stdin.