diff --git a/man/git-commitiq.1 b/man/git-commitiq.1 new file mode 100644 index 0000000..0a37d92 --- /dev/null +++ b/man/git-commitiq.1 @@ -0,0 +1,138 @@ +.\" generated with Ronn-NG/v0.9.1 +.\" http://github.com/apjanke/ronn-ng/tree/0.9.1 +.TH "GIT\-COMMITIQ" "1" "August 2026" "" "Git Extras" +.SH "NAME" +\fBgit\-commitiq\fR \- semantic commit summaries as a git subcommand +.SH "SYNOPSIS" +\fBgit commitiq\fR [git commit args\.\.\.] +.br +\fBgit commitiq commit\fR [git commit args] +.br +\fBgit commitiq setup\fR [\-\-provider

] [\-\-api\-key ] [\-\-model ] +.br +\fBgit commitiq config\fR [ []] +.br +\fBgit commitiq notes\-enable\fR [remote] +.br +\fBgit commitiq push\fR [git push args] +.br +\fBgit commitiq show\fR +.br +\fBgit commitiq log\fR +.br +.SH "DESCRIPTION" +Runs a normal \fBgit commit\fR and then asks a configured LLM (Anthropic, OpenAI, Gemini, Ollama, a local OpenAI\-compatible endpoint, or a local CLI tool) to produce a structured JSON summary of the diff\. That summary is attached to the commit as a git note (\fBrefs/notes/commits\fR)\. +.P +Because the notes ref is automatically configured on the first commit in a repo, \fBgit push\fR / \fBgit fetch\fR will include the notes without any manual setup step\. +.SS "Supported providers" +.TP +\fBanthropic\fR +Claude models via the Anthropic Messages API +.TP +\fBopenai\fR +GPT models via the OpenAI Chat Completions API +.TP +\fBgemini\fR +Gemini models via the Google Generative Language API +.TP +\fBollama\fR +Local models served by Ollama (no API key needed) +.TP +\fBlocal\fR +Any local server with an OpenAI\-compatible /chat/completions endpoint (e\.g\. LM Studio, LocalAI) +.TP +\fBcli\fR +Any local CLI tool that reads stdin and writes to stdout (e\.g\. \fBagy\fR, \fBclaude\fR, \fBaichat\fR, \fBllm\fR) +.SH "OPTIONS" + +.P +All arguments are forwarded to \fBgit commit\fR\. If the commit fails, no LLM call is made and no note is attached\. +.P +setup [\-\-provider

] [\-\-api\-key ] [\-\-model ] +.P +Interactive setup wizard or non\-interactive via flags\. +.P +config get|set|unset|list +.P +Manage provider, model, api_key, endpoint, and command config values\. +.P +notes\-enable [remote] +.P +Configure the repository so \fBgit push\fR / \fBgit fetch\fR also syncs git notes\. Called automatically on the first commitiq commit\. +.P +push [args] +.P +Like \fBgit push\fR, but also syncs \fBrefs/notes/*\fR when appropriate\. +.P +show +.P +Print the stored JSON summary for the given commit\. +.P +log +.P +List commits that have a stored summary\. +.SH "JSON SCHEMA" +The note attached to each commit is a single JSON object: +.IP "" 4 +.nf +{ + "type": "feat|fix|refactor|docs|chore|test|perf|build|ci|revert|style", + "scope": "", + "summary": "imperative summary under 60 characters", + "description": "2\-4 sentences on what changed and why it matters", + "changed_files": ["exact file paths from the diff"], + "breaking_change": false, + "review_notes": "" +} +.fi +.IP "" 0 +.SH "EXAMPLES" +Commit with an automatic summary: +.IP "" 4 +.nf +$ git commitiq \-m "fix login bug" +.fi +.IP "" 0 +.P +Set up Anthropic as the provider: +.IP "" 4 +.nf +$ git commitiq setup \-\-provider anthropic \-\-api\-key sk\-ant\-\.\.\. \-\-model claude\-3\-5\-sonnet\-latest +.fi +.IP "" 0 +.P +View a stored summary: +.IP "" 4 +.nf +$ git commitiq show a1b2c3 +.fi +.IP "" 0 +.P +Push commits and notes together: +.IP "" 4 +.nf +$ git commitiq push origin main +.fi +.IP "" 0 +.SH "ENVIRONMENT" +ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY +.P +API keys can be set via environment variables as an alternative to \fBgit commitiq setup\fR\. +.P +COMMITIQ_PROVIDER +.P +Force a specific provider (lowercase: \fBanthropic\fR, \fBopenai\fR, etc\.) +.SH "FILES" +~/.commitiq/config +.P +Persistent configuration file (key=value format, permissions 600)\. +.P +.commitiq/.commitiq.log +.P +Per\-repo log file for LLM request errors\. +.SH "AUTHOR" +Written by commitiq contributors\. +.SH "REPORTING BUGS" +<\fIhttps://github\.com/tj/git\-extras/issues\fR> +.SH "SEE ALSO" +<\fIhttps://github\.com/tj/git\-extras\fR> \ No newline at end of file diff --git a/man/git-commitiq.md b/man/git-commitiq.md new file mode 100644 index 0000000..fc43f0a --- /dev/null +++ b/man/git-commitiq.md @@ -0,0 +1,130 @@ +git-commitiq(1) -- semantic commit summaries as a git subcommand +================================== + +## SYNOPSIS + +`git commitiq` [git commit args...] +`git commitiq commit` [git commit args] +`git commitiq setup` [--provider

] [--api-key ] [--model ] +`git commitiq config` [ []] +`git commitiq notes-enable` [remote] +`git commitiq push` [git push args] +`git commitiq show` +`git commitiq log` + +## DESCRIPTION + +**git-commitiq** runs a normal `git commit` and then asks a configured LLM +(Anthropic, OpenAI, Gemini, Ollama, a local OpenAI-compatible endpoint, or a +local CLI tool) to produce a structured JSON summary of the diff. That summary +is attached to the commit as a [git note](https://git-scm.com/docs/git-notes) +(`refs/notes/commits`). + +Because the notes ref is automatically configured on the first commit in a +repo, `git push` / `git fetch` will include the notes without any manual +setup step. + +### Supported providers + + * **anthropic** - Claude models via the Anthropic Messages API + * **openai** - GPT models via the OpenAI Chat Completions API + * **gemini** - Gemini models via the Google Generative Language API + * **ollama** - Local models served by Ollama (no API key needed) + * **local** - Any local server with an OpenAI-compatible `/chat/completions` endpoint (e.g. LM Studio, LocalAI) + * **cli** - Any local CLI tool that reads stdin and writes to stdout (e.g. `agy`, `claude`, `aichat`, `llm`) + +## OPTIONS + + * ``: + All arguments are forwarded to `git commit`. If the commit fails, + no LLM call is made and no note is attached. + + * `setup [--provider

] [--api-key ] [--model ]`: + Interactive setup wizard or non-interactive via flags. + + * `config get|set|unset|list`: + Manage provider, model, api_key, endpoint, and command config values. + + * `notes-enable [remote]`: + Configure the repository so `git push` / `git fetch` also syncs git + notes. Called automatically on the first commitiq commit. + + * `push [args]`: + Like `git push`, but also syncs `refs/notes/*` when appropriate. + + * `show `: + Print the stored JSON summary for the given commit. + + * `log`: + List commits that have a stored summary. + +## JSON SCHEMA + +The note attached to each commit is a single JSON object: + +```json +{ + "type": "feat|fix|refactor|docs|chore|test|perf|build|ci|revert|style", + "scope": "", + "summary": "imperative summary under 60 characters", + "description": "2-4 sentences on what changed and why it matters", + "changed_files": ["exact file paths from the diff"], + "breaking_change": false, + "review_notes": "" +} +``` + +## EXAMPLES + +Commit with an automatic summary: + +```bash +$ git commitiq -m "fix login bug" +``` + +Set up Anthropic as the provider: + +```bash +$ git commitiq setup --provider anthropic --api-key sk-ant-... --model claude-3-5-sonnet-latest +``` + +View a stored summary: + +```bash +$ git commitiq show a1b2c3 +``` + +Push commits and notes together: + +```bash +$ git commitiq push origin main +``` + +## ENVIRONMENT + + * `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GOOGLE_API_KEY`: + API keys can be set via environment variables as an alternative to + `git commitiq setup`. + + * `COMMITIQ_PROVIDER`: + Force a specific provider (lowercase: `anthropic`, `openai`, etc.). + +## FILES + + * `~/.commitiq/config`: + Persistent configuration file (key=value format, permissions 600). + + * `.commitiq/.commitiq.log`: + Per-repo log file for LLM request errors. + +## AUTHOR + +Written by commitiq contributors. + +## REPORTING BUGS + +<<>> + +## SEE ALSO + +<<>> \ No newline at end of file diff --git a/man/git-extras.md b/man/git-extras.md index 178595b..81be529 100644 --- a/man/git-extras.md +++ b/man/git-extras.md @@ -40,6 +40,7 @@ git-extras(1) -- Awesome GIT utilities - **git-clear(1)** Rigorously clean up a repository - **git-coauthor(1)** Add a co-author to the last commit - **git-commits-since(1)** Show commit logs since some date + - **git-commitiq(1)** Semantic commit summaries as a git subcommand - **git-continue(1)** Continue current git operation - **git-contrib(1)** Show user's contributions - **git-count(1)** Show commit count diff --git a/man/index.txt b/man/index.txt index 77ec05c..1389f02 100644 --- a/man/index.txt +++ b/man/index.txt @@ -12,6 +12,7 @@ git-clear-soft(1) git-clear-soft git-clear(1) git-clear git-coauthor(1) git-coauthor git-commits-since(1) git-commits-since +git-commitiq(1) git-commitiq git-continue(1) git-continue git-contrib(1) git-contrib git-count(1) git-count