Skip to content

CLAUDE.md

Latest commit

 

History

History
232 lines (156 loc) · 7.7 KB

CLAUDE.md

File metadata and controls

232 lines (156 loc) · 7.7 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Git AI is a Rust-based CLI tool that seamlessly integrates with git hooks to automate commit message generation based on staged changes. It leverages OpenAI's API to analyze git diffs and create contextually relevant commit messages. The tool uses a sophisticated multi-step analysis process to generate meaningful commit messages by analyzing individual files, calculating impact scores, and selecting the best message from multiple candidates.

Development Commands

Building and Installation

# Build the project
cargo build

# Run tests
cargo test

# Install locally from source (for development)
cargo install --path .

# Install the git hook in the current repository
git-ai hook install

# Quick local installation for development with hook setup
just local-install

Configuration

# Set OpenAI API key
git-ai config set openai-api-key <your-key>

# Set the model to use
git-ai config set model gpt-4.1     # Default model (latest version)
git-ai config set model gpt-4o      # Optimized GPT-4, better quality but slower
git-ai config set model gpt-4o-mini # Mini version, faster processing
git-ai config set model gpt-4       # Original GPT-4

# Set max tokens for API requests
git-ai config set max-tokens <number>

# Set maximum commit message length
git-ai config set max-commit-length <number>

# Reset configuration to defaults
git-ai config reset

Hook Management

# Install the git hook
git-ai hook install

# Uninstall the git hook
git-ai hook uninstall

# Reinstall the git hook
git-ai hook reinstall

Alternative Installation

# Install precompiled binary with cargo-binstall
cargo install cargo-binstall
cargo binstall git-ai

Using the Justfile

The project includes a Justfile with useful commands:

# Install locally with debug symbols and setup hooks
just local-install

# Run integration tests in Docker
just integration-test

# Build Docker image
just docker-build

# Run GitHub Actions locally
just local-github-actions

Architecture

The project is structured into several core components:

  1. CLI Interface (src/main.rs): Provides the command-line interface for configuring the tool and managing hooks.

  2. Git Hook (src/bin/hook.rs): The actual Git hook that's invoked during the commit process to generate commit messages.

  3. Diff Processing (src/hook.rs): Handles parsing and processing Git diffs, with performance optimizations for handling large diffs through parallel processing and token management.

  4. API Integration:

    • OpenAI (src/openai.rs): Manages communication with the OpenAI API, handling request creation, error handling, and response parsing.
    • Ollama (src/ollama.rs): Provides integration with local Ollama models as an alternative to OpenAI.

  5. Model Management (src/model.rs): Defines supported AI models (GPT-4, GPT-4o, GPT-4o-mini, GPT-4.1) and handles token counting/management with optimization strategies for different text lengths.

  6. Configuration (src/config.rs): Manages user configuration including API keys, model preferences, and token limits.

  7. Commit Generation (src/commit.rs): Coordinates the process of generating commit messages from diffs.

  8. Function Calling (src/function_calling.rs): Implements OpenAI function calling for structured commit message generation with reasoning and file change summaries.

  9. Multi-Step Analysis (src/multi_step_analysis.rs and src/multi_step_integration.rs): Implements the sophisticated divide-and-conquer approach that analyzes files individually, calculates impact scores, and generates multiple commit message candidates. The integration module uses parallel processing via join_all to analyze multiple files concurrently.

  10. Profiling (src/profiling.rs): Performance profiling utilities to measure execution time of various operations.

  11. Debug Output (src/debug_output.rs): Provides debugging session tracking for multi-step analysis, including file analysis results, timings, and payloads.

Key Workflows

  1. Hook Installation: When git-ai hook install is run, the tool symlinks its executable to the repository's .git/hooks/prepare-commit-msg hook.

  2. Commit Message Generation:

    • When a user runs git commit without specifying a message
    • The hook intercepts the commit process
    • Retrieves the staged changes (diff)
    • Processes the diff to fit within token limits
    • Sends the processed diff to OpenAI
    • Uses the AI response as the commit message

  3. Multi-Step Analysis Process:

    • Parse: Splits the git diff into individual files
    • Analyze: Examines each file for lines added/removed, file type, and change significance
    • Score: Calculates impact scores based on operation type, file category, and lines changed
    • Generate: Creates multiple commit message candidates
    • Select: Chooses the best message based on highest impact

  4. Performance Optimization:

    • Parallel processing for large diffs
    • Token management to ensure API limits aren't exceeded
    • String pooling to reduce memory allocations
    • Smart truncation to prioritize more relevant parts of large diffs
    • Tiered token counting approaches based on text length for better performance

  5. Intelligent Fallback Strategy:

    • First attempts multi-step analysis with API
    • Falls back to local multi-step if API fails
    • Falls back to single-step API as a last resort

Testing

The project uses integration tests to verify core functionality:

# Run all tests
cargo test

# Run specific tests
cargo test test_empty_diff

# Run specific test with debugging output
RUST_LOG=debug cargo test --lib -- multi_step_integration::tests::test_parse_diff_with_c_i_prefixes --exact --nocapture

# Run all multi-step integration tests
RUST_LOG=debug cargo test --lib multi_step_integration::tests --no-fail-fast

# Run comprehensive tests
./scripts/comprehensive-tests

# Run integration tests
./scripts/integration-tests

# Test hook functionality
./scripts/hook-stress-test

Test files are located in the tests/ directory and include utilities for creating test repositories and verifying diff operations.

Example Usage

After installation and configuration:

# Make changes to your code
# Stage changes
git add .

# Commit without a message - Git AI will generate one
git commit --all --no-edit

The commit message will be automatically generated based on the staged changes.

Code Style and Conventions

Based on the project's Cursor rules:

Formatting

  • Use rustfmt.toml with edition = "2021" and max_width = 100
  • Keep imports grouped: std → external → internal, then alphabetized
  • Run cargo fmt before committing

Naming

  • snake_case for items and functions
  • SCREAMING_SNAKE_CASE for constants
  • PascalCase for types and traits
  • crate names use kebab-case

Error Handling

  • Use thiserror for typed errors; anyhow::Result<T> for binaries
  • Prefer ? operator over unwrap/expect in library code

Module Organization

  • Files with underscores should be nested directories (e.g., foo_bar.rs → foo/bar.rs)
  • Public re-exports go in lib.rs for clean API surface
  • Avoid deep module trees (>3 levels)

Testing

  • Each module should have #[cfg(test)] mod tests { use super::*; ... }
  • Integration tests in tests/ directory use only public API
  • Run tests with debugging: RUST_LOG=debug cargo test

Performance

  • Use parallel processing for large operations (see multi_step_integration.rs using join_all)
  • Token management and smart truncation for API limits
  • Profile with profiling.rs utilities