genius-commit

Utilities for working with staged Git changes:

• gccommit turns a staged diff into a Conventional Commit message by calling Gemini.
• gccopy copies the staged diff or appends file contents to the clipboard.

The project follows a feature-first layout (src/features/*) backed by infrastructure adapters (src/infra/*).

Installation

From GitHub (no local clone needed):

pip install "git+https://github.com/gr0vity-dev/genius-commit.git@main"

To install from a specific branch, replace main with the branch name.

From a local clone:

pip install .

Both methods expose the gccommit and gccopy console scripts.

Configuration

Variable	Required	Description
GEMINI_API_KEY	✔	API key for Google Gemini (see Google AI Studio).
GEMINI_API_MODEL	✖	Override the Gemini model used by gccommit (default gemini-2.5-flash-lite).

Add them to your shell profile, for example:

export GEMINI_API_KEY="your-api-key-here"
export GEMINI_API_MODEL="gemini-1.5-pro"

Commands

gccommit

Generate, preview, and apply a Conventional Commit message for the staged diff.

git add <files>
gccommit

Workflow:

1. The staged diff is sent to Gemini using the prompt in src/infra/ai/prompts.py.
2. The structured JSON response is parsed and rendered as a commit message.
3. You choose an action:
   • c – commit immediately with the suggested message.
   • e – open $EDITOR (falls back to vim) to tweak the message, then commit.
   • a – abort without committing.

Tip: update the prompt or parser behaviour under src/infra/ai/ if you need different output formatting.

gccopy

Run gccopy without arguments to copy the staged diff to your clipboard. The command auto-detects a clipboard utility (pbcopy, clip.exe, xclip, or wl-copy).

git add <files>
gccopy

• Prints “gccopy: no staged changes to copy.” and exits with code 0 when nothing is staged.
• Reports the clipboard tool used when the diff is copied.
• Returns a non-zero exit code if Git fails or no clipboard utility is available.

Provide one or more file paths to append their contents to the clipboard. The default delimiter is --- wrapped in newlines, keeping sections clearly separated.

gccopy docs/intro.md src/usage.py

Customise the delimiter with -d / --delimiter:

gccopy -d "***" README.md CONTRIBUTING.md

• Existing clipboard content is preserved and separated with the delimiter block.
• Errors (missing files, permission issues, clipboard failures) include a gccopy prefix for clarity.

Development

• Source code lives under src/features/ (feature-layer handlers/models) and src/infra/ (Git, clipboard, AI adapters).

• Run the automated test suite with:

  python -m unittest

• Update prompts or Gemini parsing rules in src/infra/ai/ if the API behaviour changes.

Requirements

• Python 3.8+
• Git repository
• Google Gemini API access for gccommit
• At least one clipboard utility (pbcopy, clip.exe, xclip, or wl-copy / wl-paste) to use gccopy