@amnesia2k/git-aic

v2.1.12

Published

9 days ago

Git AIC

0High
0Medium
0Low

git aic ai git-aic gemini google-gemini llm conventional-commits commit-generator diff-explanations productivity cli typescript

Git AIC: AI-Powered Conventional Commits

Git AIC is a TypeScript CLI for two related workflows inside a Git repository:

generating AI-assisted conventional commit messages from staged changes
generating AI-explained markdown diff reports from selected working-tree changes

It is built for local Git usage with interactive file selection, Gemini-based summarization, and a low-friction terminal UX.

What It Does

Commit flow

git aic

inspects the repository for changed files
auto-stages deleted files and excludes them from the selection list
shows the remaining local changes and lets you choose which ones to stage
stages only the files you selected, then generates the commit from that staged set
sends the staged diff to Gemini
generates a Conventional Commits style message
commits with that message

git aic --push / git aic -p

runs the same commit flow
pushes after a successful commit

Diff report flow

git aic --diff / git aic -d

inspects the repository for changed files
lets you choose which files should be included in the report when there are multiple changed files
does not stage or unstage files for the diff workflow
reads the selected changes directly from the working tree
generates a markdown report in git-diffs/
explains each selected file diff with AI
includes current repo metadata such as branch and base commit hash

Key Behaviors

Conventional commit generation: Commit messages are guided by strict prompt rules.
Single logical change stays one line: If multiple files all belong to one logical change, the generated commit message stays a one-line summary.
Unrelated changes may become a list: If the changes are clearly unrelated, the generated commit message may use a summary line plus bullet points.
Interactive file selection: Multi-file changes open a selector so the user can choose the exact file set to commit, push, or document.
AI diff reports: Diff reports explain the selected changes before showing the raw patch.
Structured diff naming: Report filenames use a concise type-topic.md format such as feat-auth-flow.md.
Organized output: Reports are written to git-diffs/ in the current working directory.
Git ignore support: On the first diff report run that creates git-diffs/, the tool adds git-diffs/ to the current directory’s .gitignore if it is not already ignored.
Visible loading states: Uses cli-loaders with the arrows_3 loader and step-specific status messages.
Retry-safe AI requests: Retries temporary Gemini rate limits and transient failures, then falls back cleanly if needed.

Diff Report Contents

Each generated markdown report includes:

report title
metadata section
generated timestamp
current branch
short base commit hash
full base commit hash
selected file list
one section per file
AI explanation above the raw diff block

Installation

1. Global Installation (Standard)

The easiest way to use Git AIC is to install it globally via npm or bun:

npm install -g @amnesia2k/git-aic
# or
bun install -g @amnesia2k/git-aic

Once installed, you can skip the manual setup and use the built-in configuration commands:

git-aic set-key your_gemini_api_key_here
git-aic alias

2. Local Development (Clone)

For developers or users who want to run the tool from the source code:

Clone the repository:

git clone https://github.com/amnesia2k/git-aic.git
cd git-aic

Install dependencies:

bun install

(Optional) Link the package locally:

npm link

Configuration & API Key

Git AIC requires a Google Gemini API key.

A. Persistent Configuration (Recommended)

You can securely store your API key in your user profile:

git-aic set-key your_gemini_api_key_here

To see your current configuration:

git-aic show

B. Environment Variables (Manual)

Alternatively, you can set the GEMINI_COMMIT_MESSAGE_API_KEY variable.

Windows PowerShell:

setx GEMINI_COMMIT_MESSAGE_API_KEY "your_gemini_api_key_here"

MacOS & Linux:

export GEMINI_COMMIT_MESSAGE_API_KEY=your_gemini_api_key_here

Restart the terminal after setting the variable.

Usage

1. The "git aic" Alias

To use the tool as a native Git subcommand (git aic), you need to set up a Git alias.

Option A: Automatic Setup (Global NPM)

If you installed via NPM, run:

git-aic alias

Option B: Manual Setup (Local Clone)

If you are running from a local clone, point the alias to your entry point:

Windows PowerShell:

git config --global alias.aic '!npx tsx "C:/Users/YourName/path/to/git-aic/bin/cli.ts"'

macOS / Linux:

git config --global alias.aic '!npx tsx "/Users/YourName/path/to/git-aic/bin/cli.ts"'

2. Commands

Generate and create a commit:

git aic

Generate, commit, and push:

git aic --push

Generate a markdown diff report:

git aic --diff

Show current configuration:

git aic show

Display help:

git aic help

[!TIP] Use git aic help or git aic -h to see the help menu. Git reserves --help for its own internal documentation search, which causes raw --help to fail on custom aliases.

Also supported:

git aic -d : This is a shortcut for `git aic --diff`
git aic -p : This is a shortcut for `git aic --push`

Important Workflow Notes

Commit mode auto-stages deletions, then stages your selection

Commit workflows are based on the staged diff.

When you run git aic or git aic --push:

deleted files are staged automatically and are not shown in the selection list
the tool lists the remaining local changes and prompts you to choose which ones to stage
only the files you selected, plus the auto-staged deletions, remain staged for the commit
the final commit message is generated from the resulting staged diff

Diff mode does not stage files

Diff report workflows are based on the selected changes directly.

When you select files for -d / --diff:

the tool does not stage files
the tool does not unstage files
the tool reads the selected diffs and generates the markdown report from them

This keeps the report flow non-destructive and avoids changing index state unnecessarily.

Example Output Location

Example generated report paths:

git-diffs/feat-auth-flow.md
git-diffs/fix-config-loading.md
git-diffs/refactor-cli-loader.md

If a filename already exists, numeric suffixes are used:

feat-auth-flow.md
feat-auth-flow-1.md
feat-auth-flow-2.md

Technologies Used

| Technology | Description | | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | | Primary language for robust and scalable code. | | | JavaScript runtime used to execute the CLI tool. | | | Fast all-in-one JavaScript runtime. | | | Large Language Model for intelligent commit message generation. | | | Promise-based HTTP client for API requests. | | | Facilitates Git operations programmatically. | | | Interactive command-line interface prompts. | | | Provides animated terminal loaders for visible CLI progress. | | | Terminal string styling for enhanced readability. | | | Framework for building robust command-line interfaces. | | | Runs the TypeScript CLI entrypoint directly during local usage. | | | Supports direct TypeScript execution in the project scripts. |