gitpt 1.6.1 → 1.7.2

package/README.md

@@ -1,208 +1,75 @@
 # GitPT
 
-Git Prompt Tool is a CLI tool that helps you write commit messages using AI through [OpenRouter](https://openrouter.ai/) or a local LLM. It acts as a complete git wrapper, enhancing specific commands with AI while passing through all other git commands directly.
+GitPT (Git Prompt Tool) is a git command alias that writes your commit messages with an LLM, built for on-device models. Use it anywhere you use git: every command it doesn't change passes straight through, so you can replace git with it and lose nothing. The one command that changes is `commit`, which writes the message for you.
 
-## Features
+Big remote models already write commits fine. The harder case is the small local model on your machine (Apple's Foundation Models, Ollama, LM Studio), which holds only a few thousand tokens. A real diff is much larger, so GitPT summarizes it file by file until it fits the model's context window, then writes the message from that summary. Remote APIs (OpenAI, Anthropic, OpenRouter) work too.
 
-- Acts as a complete git replacement - all git commands are supported
-- Generate commit messages with AI based on your code changes
+![GitPT generating a commit message](assets/demo.gif)
 
-  `gitpt commit`
-- Create pull requests with AI-generated titles and descriptions
+<sub>The diff is summarized to fit the model's context window before the message is written.</sub>
 
-  `gitpt pr create`
-- Compatible with all regular git options (flags, arguments, etc.)
-- Edit suggested messages before committing
-- Works with various AI models via OpenRouter
-- Support for local LLMs with OpenAI-compatible API
-- Support for Apple Foundation Models on-device (macOS 27+, no API key required)
-- [Commitlint](https://commitlint.js.org/) support - read directly from your repository
+> **New: Apple Foundation Models.** On macOS 27 and later, GitPT runs on Apple's built-in on-device model. No API key, no signup, nothing leaves your Mac. Run `gitpt setup` and choose Apple Foundation Models.
 
-## Installation
+## Install
 
 ```bash
-# Install globally
 npm install -g gitpt
-
-# Or use npx
-npx gitpt
-```
-
-## Set up
-
-To configure GitPT with your OpenRouter API key and select a model:
-
-```bash
-gitpt setup
-```
-
-This will guide you through:
-1. Entering your OpenRouter API key
-2. Selecting an AI model from popular options or specifying a custom one
-
-_It's recommended using small models, such as `openai/gpt-4.1-mini` as your model choice. Mainly due to its large context window, fast response times & cost-effective pricing._
-
-
-You'll need an [OpenRouter](https://openrouter.ai/) account to get an API key.
-
-## Usage
-
-### Using GitPT as a Complete Git Replacement
-
-GitPT can be used as a direct replacement for git - any git command can be run through GitPT:
-
-```bash
-# Standard git commands work exactly the same
-gitpt status
-gitpt log
-gitpt branch
-gitpt checkout -b new-feature
-gitpt push origin main
-
-# GitPT passes all arguments and options to git
-gitpt log --oneline --graph
-gitpt merge --no-ff feature-branch
 ```
 
-### Adding Files
-
-Add files to the staging area just like you would with git:
+## Setup
 
 ```bash
-# Same as git add . (supports all the regular git add options)
-gitpt add .
+gitpt setup     # pick a model
 ```
 
-### Creating Commits
-
-Generate an AI-powered commit message based on your staged changes:
-
-```bash
-gitpt commit
-
-# Or supply -m argument, if you want to avoid gitpt generating the message
-gitpt commit -m "feat: file hash validation"
-
-# Pass any other git commit options
-gitpt commit --amend
-```
-
-The tool will:
-1. Analyze your staged changes
-2. Generate a commit message using the configured AI model
-3. Validate against commitlint rules (if configured)
-4. Regenerate the message if it fails validation
-5. Show you the suggested message
-6. Let you edit the message before committing
-7. Create the commit with your approved message
-
-### Changing Models
-
-You can change the AI model at any time:
+Optional: alias git so GitPT runs everywhere you already type git.
 
 ```bash
-# Select model interactively (either OpenRouter or a local LLM)
-gitpt model
+alias git=gitpt
 ```
 
-_It's recommended using small models, such as `openai/gpt-4.1-mini` as your model choice. Mainly due to its large context window, fast response times & cost-effective pricing._
-
-#### Using a Local LLM
-
-GitPT works with any local LLM that provides an OpenAI-compatible API endpoint, such as:
-- [Ollama](https://ollama.ai/)
-- [LM Studio](https://lmstudio.ai/)
-- [LocalAI](https://localai.io/)
-- Custom setups with tools like llama.cpp
-
-#### Using Apple Foundation Models
-
-On macOS 27 and later, GitPT can use Apple's on-device Foundation Models through the built-in `fm` CLI — no API key or network connection required. Select **Apple Foundation Models** when running `gitpt setup` or `gitpt model`.
-
-> Note: the on-device model has a small context window (~4096 tokens), so very large diffs may not fit.
-
-## GitHub Usage
+## Use
 
-If you have GitHub CLI (`gh`) installed, you can use GitPT to interact with GitHub (e.g. generate full pull requests).
-
-### Creating Pull Requests
-
-Generate AI-powered pull request titles and descriptions based on your changes:
+With plain git, you write the message yourself:
 
 ```bash
-gitpt pr create
+git add .
+git commit -m "fix: handle empty staged diff"   # you write the message
 ```
 
-The tool will:
-1. Analyze the commits and files changed since branching from the base branch
-2. Generate a suitable PR title and detailed description
-3. Show you the suggested content
-4. Let you edit the title and description before submission
-5. Create the pull request with your approved content
-
-#### Pull Request Options
+With GitPT, you don't:
 
 ```bash
-# Create a draft PR
-gitpt pr create --draft
-
-# Specify a custom base branch
-gitpt pr create --base develop
-
-# Skip editing the PR details
-gitpt pr create --no-edit
-
-# Provide your own title instead of generating one
-gitpt pr create --title "Your PR title here"
+gitpt add .
+gitpt commit                                    # GitPT writes it from the diff
 ```
 
-## How It Works
-
-GitPT leverages AI to enhance your Git workflow while acting as a complete git wrapper:
-
-- **Command Handling:** GitPT intelligently routes commands - enhanced commands (commit, pr) use AI capabilities while all other git commands are passed directly to git.
-
-- **For commits:** Sends a diff of your staged changes to the AI, which generates a contextual commit message following best practices.
-
-- **Commitlint Integration:** Automatically detects commitlint configuration files and validates generated commit messages against your project's commit conventions. If validation fails, it regenerates a compliant message.
-
-- **For pull requests:** Analyzes the commits and file changes between your branch and the base branch, then generates a suitable title and detailed description for your PR.
-
-- **For other git commands:** Passes them through directly to git with all arguments and options preserved, ensuring complete compatibility with your existing git workflow.
+`gitpt commit` reads your staged diff, writes the message, and opens it in your editor. Save and close to commit.
 
-- **Local LLM Support:** Can use locally running LLM servers with OpenAI-compatible APIs instead of cloud-based services, providing privacy and offline capabilities.
+### Through plain `git commit`
 
-## Development
-
-```bash
-# Clone the repository
-git clone https://github.com/bartaxyz/GitPT.git
-cd GitPT
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Link for local development
-npm link
-```
+Prefer typing `git commit`? Two ways:
 
-## Commitlint Integration
+- **Shell alias** — add `alias git=gitpt` to your shell rc, then `git commit` runs GitPT.
+- **Git hook** — run `gitpt hook install` once. A normal `git commit` (without `-m`) then opens your editor prefilled with an AI-generated message. It steps aside for `-m`, merges, squashes, and amends, and never blocks a commit if generation fails. Remove it with `gitpt hook uninstall`.
 
-GitPT automatically detects and integrates with [commitlint](https://commitlint.js.org/) if it's configured in your repository:
+## Commands
 
-- **Automatic Detection:** GitPT checks for common commitlint configuration files (commitlint.config.js, .commitlintrc.*, etc.)
+- `gitpt commit`: write a commit message from staged changes. Respects `-m` and your commitlint rules.
+- `gitpt model`: pick or switch the model. Each provider keeps its own key.
+- `gitpt setup` / `gitpt config` / `gitpt reset`: configure, show, or clear settings.
+- `gitpt pr create`: draft a pull request title and description with the `gh` CLI (experimental).
+- `gitpt hook install` / `gitpt hook uninstall`: use GitPT through a plain `git commit` via a `prepare-commit-msg` hook.
 
-- **Rule-Aware Generation:** When commitlint is detected, GitPT instructs the AI to generate messages that follow your specific commit conventions
+## Models
 
-- **Validation & Regeneration:** Generated messages are validated against your commitlint rules before committing. If validation fails, GitPT automatically regenerates a compliant message
+- **On-device**: Apple's Foundation Models on macOS 27 or later (no API key), or any OpenAI-compatible local server such as Ollama or LM Studio.
+- **Remote**: OpenAI, Anthropic, OpenRouter. Bring an API key.
 
-- **Error Feedback:** Validation errors are sent to the AI to help it understand how to fix the message
+## Requests and bugs
 
-This integration ensures that all AI-generated commit messages follow your team's established commit conventions without requiring manual corrections.
+Want a feature or hit a bug? [Open an issue](https://github.com/bartaxyz/GitPT/issues).
 
 ## License
 
-MIT
+MIT

package/dist/commands/commit/commitFlags.js

@@ -0,0 +1,7 @@
+//#region src/commands/commit/commitFlags.ts
+var hasFlag = (args, flag) => args.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
+var isAmend = (args) => hasFlag(args, "--amend");
+var isAllowEmpty = (args) => hasFlag(args, "--allow-empty");
+var skipsStagedGuard = (args) => isAmend(args) || isAllowEmpty(args);
+//#endregion
+export { isAmend, skipsStagedGuard };

package/dist/commands/commit/context/buildPrompt.js

@@ -1,13 +1,16 @@
-import { getCommitlintRules, hasCommitlintConfig, } from "../../../utils/commitlint.js";
+import { getCommitlintRules, hasCommitlintConfig } from "../../../utils/commitlint.js";
 import { systemPrompt } from "./systemPrompt.js";
 import { userPrompt } from "./userPrompt.js";
-export const buildCommitPrompt = (diff, validationErrors) => {
-    const baseRules = hasCommitlintConfig() ? getCommitlintRules() : "";
-    const errorInfo = validationErrors
-        ? `\n\nYOUR PREVIOUS MESSAGE FAILED VALIDATION WITH THESE ERRORS:\n${validationErrors}\n\nFIX THESE ISSUES IN YOUR NEW MESSAGE.`
-        : "";
-    return {
-        system: [systemPrompt, baseRules, errorInfo].join("\n\n"),
-        user: userPrompt(diff),
-    };
+//#region src/commands/commit/context/buildPrompt.ts
+var buildCommitPrompt = (diff, validationErrors) => {
+	return {
+		system: [
+			systemPrompt,
+			hasCommitlintConfig() ? getCommitlintRules() : "",
+			validationErrors ? `\n\nYOUR PREVIOUS MESSAGE FAILED VALIDATION WITH THESE ERRORS:\n${validationErrors}\n\nFIX THESE ISSUES IN YOUR NEW MESSAGE.` : ""
+		].join("\n\n"),
+		user: userPrompt(diff)
+	};
 };
+//#endregion
+export { buildCommitPrompt };

package/dist/commands/commit/context/summaryPrompt.js

@@ -1,4 +1,5 @@
-export const summarySystemPrompt = `
+//#region src/commands/commit/context/summaryPrompt.ts
+var summarySystemPrompt = `
 You are condensing a fragment of a git diff so a commit message can be written afterwards.
 
 Output exactly one line per changed file, in this format:
@@ -10,8 +11,10 @@ Rules:
 - Describe the functional change (what was added, removed, refactored, or fixed), not file mechanics.
 - Output ONLY these lines. No preamble, no commentary, no code fences, no headings, no blank lines.
 `;
-export const summaryUserPrompt = (diffChunk) => `
+var summaryUserPrompt = (diffChunk) => `
 Summarize the changes in this git diff fragment:
 
 ${diffChunk}
 `;
+//#endregion
+export { summarySystemPrompt, summaryUserPrompt };

package/dist/commands/commit/context/systemPrompt.js

@@ -1,4 +1,5 @@
-export const systemPrompt = `
+//#region src/commands/commit/context/systemPrompt.ts
+var systemPrompt = `
 You are a helpful assistant that generates concise, informative Git commit messages.
 
 Follow these strict rules:
@@ -36,3 +37,5 @@ Examples of Bad Commit Messages:
   This implements the login page...     ❌ (contains multiple lines)
 - "fix: update styling"                 ❌ (includes quotes)
 `;
+//#endregion
+export { systemPrompt };

package/dist/commands/commit/context/userPrompt.js

@@ -1,5 +1,8 @@
-export const userPrompt = (diff) => `
+//#region src/commands/commit/context/userPrompt.ts
+var userPrompt = (diff) => `
 Generate a single-line commit message for the following git diff:
 
 ${diff}
 `;
+//#endregion
+export { userPrompt };

package/dist/commands/commit/generateCommitMessage.js

@@ -1,21 +1,18 @@
 import { getConfig } from "../../config.js";
 import { getProvider } from "../../llm/registry.js";
 import { buildCommitPrompt } from "./context/buildPrompt.js";
-export const generateCommitMessage = async (diff, validationErrors) => {
-    const config = getConfig();
-    // Check if we have a configured model
-    if (!config.model) {
-        throw new Error('GitPT is not configured properly. Please run "gitpt setup" first.');
-    }
-    const { system, user } = buildCommitPrompt(diff, validationErrors);
-    const provider = getProvider();
-    const message = await provider.complete({
-        system,
-        user,
-        maxTokens: provider.maxOutputTokens,
-    });
-    if (!message) {
-        throw new Error("No message returned from LLM");
-    }
-    return message;
+//#region src/commands/commit/generateCommitMessage.ts
+var generateCommitMessage = async (diff, validationErrors) => {
+	if (!getConfig().model) throw new Error("GitPT is not configured properly. Please run \"gitpt setup\" first.");
+	const { system, user } = buildCommitPrompt(diff, validationErrors);
+	const provider = getProvider();
+	const message = await provider.complete({
+		system,
+		user,
+		maxTokens: provider.maxOutputTokens
+	});
+	if (!message) throw new Error("No message returned from LLM");
+	return message;
 };
+//#endregion
+export { generateCommitMessage };