Skip to content

USAGE.md

Latest commit

 

History

History
515 lines (370 loc) · 9.65 KB

USAGE.md

File metadata and controls

515 lines (370 loc) · 9.65 KB

Diffron Usage Guide

This guide provides detailed usage examples for Diffron's CLI and Python API.

Table of Contents

  1. CLI Commands
  2. Python API
  3. Git Hooks Workflow
  4. PR Workflow
  5. Advanced Usage

CLI Commands

diffron-install-hooks

Install Git hooks to automatically generate commit messages.

# Install to current repository
diffron-install-hooks

# Install to specific repository
diffron-install-hooks --repo /path/to/repo

# Install globally (all repositories)
diffron-install-hooks --global

diffron-uninstall-hooks

Remove Git hooks from a repository.

# Uninstall from current repository
diffron-uninstall-hooks

# Uninstall from specific repository
diffron-uninstall-hooks --repo /path/to/repo

# Uninstall global hooks
diffron-uninstall-hooks --global

diffron-pr

Generate PR title and description.

# Generate for current branch
diffron-pr

# Generate for specific branch
diffron-pr --branch feature/my-feature

# Specify base branch
diffron-pr --base develop

# Generate and create PR on GitHub (requires gh CLI)
diffron-pr --create

diffron-status

Check Diffron status (Lemonade connection, hooks installation).

# Quick status
diffron-status

# Detailed status
diffron-status --verbose

# Check specific repository
diffron-status --repo /path/to/repo

Python API

Basic Usage

from diffron import DiffronClient

# Create client (auto-detects Lemonade)
client = DiffronClient()

# Generate commit message from staged diff
commit_msg = client.generate_commit_message()
print(commit_msg)  # "feat: add user authentication"

# Generate PR description
pr = client.generate_pr_description(branch="feature/my-feature")
print(f"TITLE: {pr.title}")
print(f"DESCRIPTION: {pr.description}")

# Install hooks
client.install_hooks(repo_path=".")

Lemonade Client

from diffron import LemonadeClient, detect_lemonade_port

# Detect Lemonade port
port = detect_lemonade_port()
print(f"Lemonade running on port: {port}")  # 8000

# Create client with specific settings
client = LemonadeClient(
    host="localhost",
    port=8000,
    model="your-model-name",
)

# Generate chat completion
response = client.chat_completion(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ],
    max_tokens=50,
    temperature=0.5,
)
print(response)

Commit Message Generation

from diffron import generate_commit_message

# Generate from staged diff (automatic)
msg = generate_commit_message()

# Generate from custom diff
custom_diff = """
diff --git a/src/main.py b/src/main.py
+def hello():
+    print("Hello, World!")
"""
msg = generate_commit_message(diff=custom_diff)

# With custom parameters
msg = generate_commit_message(
    diff=custom_diff,
    max_chars=2000,      # Limit diff size
    max_tokens=50,       # Limit response length
    temperature=0.1,     # More deterministic
)

PR Description Generation

from diffron import generate_pr_description, PRDescription

# Generate for current branch
pr = generate_pr_description()

# Generate for specific branch
pr = generate_pr_description(
    branch="feature/my-feature",
    base="main",
)

# Access properties
print(f"Title: {pr.title}")
print(f"Description: {pr.description}")

# Format output
print(pr.format_output())

# Get GitHub CLI format
title, body = pr.to_github_cli()

Git Hooks Management

from diffron import install_hooks, uninstall_hooks, is_hooks_installed

# Install hooks
install_hooks(repo_path=".")
install_hooks(repo_path="/path/to/repo")
install_hooks(global_install=True)  # Global installation

# Check if installed
if is_hooks_installed():
    print("Hooks are installed!")

# Uninstall hooks
uninstall_hooks(repo_path=".")
uninstall_hooks(global_install=True)  # Remove global hooks

# Get detailed status
from diffron import get_hooks_status
status = get_hooks_status()
print(status)
# {
#     'is_git_repo': True,
#     'local_hooks_installed': True,
#     'global_hooks_configured': False,
#     ...
# }

Git Hooks Workflow

Automatic Commit Messages

Once hooks are installed, commit messages are generated automatically:

# Make changes
echo "new feature" >> feature.py
git add feature.py

# Commit - hooks generate the message
git commit

# Result: "feat: add new feature" (auto-generated)

Skip Auto-Generation

Hooks automatically skip:

  • Merge commits
  • Rebase operations
  • Amend commits (git commit --amend)
  • Empty commits

To manually write a commit message when hooks are installed:

# Use -m flag to provide message directly
git commit -m "chore: manual commit message"

# Or edit the generated message
git commit  # Opens editor with generated message

Hook Behavior

The prepare-commit-msg hook:

  1. Checks Lemonade: Silently exits if Lemonade is not running
  2. Analyzes Diff: Gets staged changes (max 4000 chars)
  3. Generates Message: Calls Lemonade API
  4. Writes Message: Populates commit message file
  5. Opens Editor: Git opens editor with generated message (default behavior)

To skip the editor and commit directly:

git commit -m "auto"  # Hook replaces "auto" with generated message

PR Workflow

Standard Workflow

  1. Create feature branch:

    git checkout -b feature/my-feature

  2. Make commits:

    # Diffron auto-generates commit messages
git add .
git commit

  3. Generate PR description:

    diffron-pr

  4. Copy output and create PR:

    • Copy TITLE and DESCRIPTION
    • Go to GitHub
    • Create PR with copied content

Automated Workflow (with GitHub CLI)

  1. Install GitHub CLI:

    # Windows (winget)
winget install GitHub.cli

# Or download from https://cli.github.com/

  2. Authenticate:

    gh auth login

  3. Generate and create PR:

    diffron-pr --create

Manual PR Script

Use the standalone aipr.py script:

# From hooks directory
python hooks/aipr.py

# With branch arguments
python hooks/aipr.py feature/my-feature main

Advanced Usage

Custom Commit Types

Diffron uses Conventional Commits by default. To customize:

from diffron.commit_gen import COMMIT_TYPES, format_commit_message

# View available types
print(COMMIT_TYPES)
# ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert']

# Format with scope and breaking change
msg = format_commit_message(
    commit_type="feat",
    description="change API structure",
    scope="api",
    breaking=True,
)
print(msg)  # "feat(api)!: change API structure"

Batch Operations

from diffron import DiffronClient

client = DiffronClient()

# Process multiple repositories
repos = ["/path/to/repo1", "/path/to/repo2"]

for repo in repos:
    print(f"Processing {repo}...")
    client.install_hooks(repo_path=repo)

Integration with CI/CD

Use Diffron in CI pipelines:

# GitHub Actions example
name: PR Description
on:
  pull_request:
    types: [opened]

jobs:
  generate-pr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Diffron
        run: pip install diffron
      - name: Generate PR description
        run: diffron-pr
        env:
          DIFFRON_LEMONADE_HOST: ${{ secrets.LEMONADE_HOST }}

Custom Prompts

Modify the prompt for commit generation:

from diffron.lemonade import LemonadeClient

client = LemonadeClient()

custom_prompt = """
Analyze this git diff and write a commit message.
Focus on the user-facing changes.
Format: type(scope): description

Diff:
""" + diff

response = client.chat_completion(
    messages=[{"role": "user", "content": custom_prompt}],
    max_tokens=100,
    temperature=0.2,
)

Tips and Best Practices

1. Review Generated Messages

Always review auto-generated commit messages before committing:

git commit  # Opens editor with generated message
# Review and save, or modify as needed

2. Use Scopes for Large Projects

For projects with multiple components:

# Generated: "feat(api): add user endpoint"
# Generated: "fix(ui): resolve button alignment"

3. Keep Changes Focused

Smaller, focused commits generate better messages:

# Good: Single feature
git add src/auth.py
git commit  # "feat: add authentication"

# Better than: Multiple unrelated changes
git add .
git commit  # Generic message

4. Combine with Pre-commit Hooks

Use Diffron alongside pre-commit hooks:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
  # Diffron handles commit messages separately

Examples

Example 1: Feature Development

# Start feature branch
git checkout -b feat/user-auth

# Make changes and commit (auto-generated messages)
git add src/auth.py
git commit  # "feat: add user authentication"

git add tests/test_auth.py
git commit  # "test: add authentication tests"

# Generate PR description
diffron-pr --create

Example 2: Bug Fix

# Create fix branch
git checkout -b fix/login-bug

# Fix the bug
git add src/login.py
git commit  # "fix: resolve login redirect issue"

# Generate PR
diffron-pr --base main

Example 3: Documentation Update

# Update docs
git add docs/*.md
git commit  # "docs: update installation guide"

# No PR needed for docs-only changes
git push origin main

Last updated: 2026-03-28