giv Documentation - Complete Reference Guide

giv Documentation

Complete reference guide for AI-powered Git workflows
Master giv's features for generating commit messages, changelogs, release notes, and announcements with multiple AI backends and advanced Git integration.
📋 CLI Reference AI Providers

Command Line Reference

Complete guide to all giv commands and options

Core Commands

giv message [<revision-range>] [OPTIONS]

Generate commit messages from Git diffs (default command)

# Generate message for staged changes giv message # Generate message for specific commits giv message HEAD~3..HEAD # Generate message with custom model giv message --model gpt-4
giv summary [<revision-range>] [OPTIONS]

Create summaries of changes over time periods

# Summarize last week's changes giv summary --since="1 week ago" # Summarize between releases giv summary v1.0.0..v1.1.0 # Detailed summary with stats giv summary --verbose
giv changelog [<version>] [OPTIONS]

Generate or update CHANGELOG.md with version management

# Generate changelog for current version giv changelog # Generate changelog for specific version giv changelog v1.2.0 # Update changelog with new entry giv changelog --update
giv release-notes [<version>] [OPTIONS]

Generate release notes for tagged releases

# Generate release notes for latest tag giv release-notes # Generate release notes for specific release giv release-notes v1.2.0 # Format for GitHub releases giv release-notes --format github
giv announcement [<version>] [OPTIONS]

Create marketing-style announcements for releases

# Generate announcement for latest release giv announcement # Generate announcement with specific tone giv announcement --tone professional # Social media announcement giv announcement --format twitter

Configuration Commands

giv config <action> [<key>] [<value>]

Manage configuration values with Git-style syntax

# Set API configuration giv config set api.url https://api.openai.com/v1/chat/completions giv config set api.model gpt-4 # Get configuration values giv config get api.model # List all configuration giv config list
giv init [OPTIONS]

Initialize giv in a project with templates and configuration

# Initialize with default templates giv init # Initialize with specific provider giv init --provider anthropic # Force reinitialize giv init --force

Global Options

--model <model>

Specify AI model to use (overrides configuration)

giv message --model claude-3-sonnet
--provider <provider>

Specify AI provider (openai, anthropic, ollama, custom)

giv message --provider anthropic
--output <file>

Write output to file instead of stdout

giv changelog --output CHANGELOG.md
--format <format>

Output format (markdown, conventional, github, plain)

giv message --format conventional
--verbose, -v

Enable verbose output with detailed information

giv summary --verbose

AI Provider Configuration

Complete guide to configuring and using different AI backends

🤖 OpenAI

Configuration

# Environment variables (recommended) export OPENAI_API_KEY="your-api-key" export GIV_API_MODEL="gpt-4" # Or via giv config giv config set api.key "your-api-key" giv config set api.url "https://api.openai.com/v1/chat/completions" giv config set api.model "gpt-4"

Supported Models

gpt-4 gpt-4-turbo gpt-3.5-turbo gpt-4o

Usage Examples

# Use specific OpenAI model giv message --provider openai --model gpt-4 # Generate changelog with GPT-4 Turbo giv changelog --model gpt-4-turbo

🧠 Anthropic (Claude)

Configuration

# Environment variables export ANTHROPIC_API_KEY="your-api-key" export GIV_API_MODEL="claude-3-sonnet-20240229" # Or via giv config giv config set api.key "your-api-key" giv config set api.url "https://api.anthropic.com/v1/messages" giv config set api.model "claude-3-sonnet-20240229"

Supported Models

claude-3-sonnet-20240229 claude-3-opus-20240229 claude-3-haiku-20240307 claude-3-5-sonnet-20241022

Usage Examples

# Use Anthropic Claude giv message --provider anthropic # Use specific Claude model giv summary --provider anthropic --model claude-3-opus-20240229

🏠 Ollama (Local Models)

Configuration

# Install and run Ollama curl -fsSL https://ollama.ai/install.sh | sh ollama serve # Pull models ollama pull llama3.2 ollama pull codellama # Configure giv for Ollama giv config set api.url "http://localhost:11434/api/chat" giv config set api.model "llama3.2"

Popular Models

llama3.2 codellama mistral deepseek-coder

Usage Examples

# Use local Ollama model giv message --provider ollama --model llama3.2 # Generate commit with code-specialized model giv message --provider ollama --model codellama

🔧 Custom API Endpoints

Configuration

# Configure custom OpenAI-compatible endpoint giv config set api.url "https://your-custom-api.com/v1/chat/completions" giv config set api.key "your-api-key" giv config set api.model "your-custom-model" # Custom headers (if needed) giv config set api.headers.Authorization "Bearer your-token" giv config set api.headers.Custom-Header "value"

Compatible Services

Azure OpenAI
giv config set api.url "https://your-resource.openai.azure.com/openai/deployments/your-deployment/chat/completions?api-version=2023-12-01-preview"
Together AI
giv config set api.url "https://api.together.xyz/v1/chat/completions"
LM Studio
giv config set api.url "http://localhost:1234/v1/chat/completions"

Template System and Customization

Advanced template system for customizing AI prompts and output

📝 Built-in Templates

giv includes optimized templates for different output types:

commit_message_prompt.md

Generates concise, actionable commit messages following conventional commit format

Generate a concise commit message for these changes: {DIFF} Requirements: - Follow conventional commit format (type: description) - Use present tense ("add" not "added") - Keep under 72 characters - Focus on what the change accomplishes

changelog_prompt.md

Creates structured changelog entries with categorized changes

Generate a changelog entry for version {VERSION}: {HISTORY} Format as: ## [{VERSION}] - {DATE} ### Added - New features ### Changed - Enhancements to existing features ### Fixed - Bug fixes

release_notes_prompt.md

Generates comprehensive release notes with highlights and breaking changes

Create release notes for {PROJECT_TITLE} version {VERSION}: {HISTORY} Include: - Key highlights and new features - Breaking changes (if any) - Migration instructions - Acknowledgments

🛠️ Template Variables

Available variables for template customization:

Git Content

{DIFF} Current Git diff or staged changes
{HISTORY} Git commit history for specified range
{SUMMARY} Summary of changes

Project Metadata

{PROJECT_TITLE} Project name from package.json, pyproject.toml, etc.
{VERSION} Current or specified version
{DESCRIPTION} Project description

Git Metadata

{COMMIT_ID} Current commit hash
{BRANCH} Current Git branch
{DATE} Current date in ISO format
{AUTHOR} Git author information

✏️ Custom Templates

Create and use custom templates for specialized workflows:

Creating Custom Templates

# Initialize project templates giv init # Edit templates nano .giv/templates/commit_message_prompt.md nano .giv/templates/changelog_prompt.md # Create custom template cat > custom-commit.md << 'EOF' You are a senior software engineer writing a commit message. Changes made: {DIFF} Write a commit message that: - Follows our team's conventional commit format - Explains the business value - Mentions any breaking changes - Stays under 100 characters for the subject line EOF

Using Custom Templates

# Use custom template file giv message --prompt-file custom-commit.md # Use inline template giv message --prompt "Generate a commit message in our team style: {DIFF}" # Override specific templates giv changelog --prompt-file team-changelog-template.md

Template Inheritance

# Project-level templates (highest priority) .giv/templates/commit_message_prompt.md # User-level templates ~/.giv/templates/commit_message_prompt.md # System defaults (lowest priority) Built-in templates

Advanced Git Integration

Leverage Git's full power with revision ranges, pathspecs, and advanced targeting

🎯 Revision Ranges and Targeting

Revision Ranges

# Generate summary for last 3 commits giv summary HEAD~3..HEAD # Changes between specific commits giv summary abc123..def456 # Changes between tags giv changelog v1.0.0..v1.1.0 # Changes since yesterday giv summary --since="yesterday" # Changes in last week giv summary --since="1 week ago"

Pathspec Filtering

# Changes to specific files giv message -- src/api.py src/utils.py # Changes to directory giv summary HEAD~5..HEAD -- docs/ # Changes to file pattern giv message -- "*.py" # Exclude specific files giv summary -- . ":(exclude)*.log"

Staged and Working Changes

# Generate message for staged changes (default) giv message # Include unstaged changes giv message --include-unstaged # Only unstaged changes giv message --unstaged-only # Specific files from staging giv message -- src/main.py

🔧 Git Workflow Integration

Feature Branch Workflow

# Generate commit for current feature work git add . giv message # Summarize entire feature branch giv summary main..feature-branch # Generate changelog entry for feature giv changelog --format feature-summary

Release Workflow

# Tag new release git tag v1.2.0 # Generate release notes giv release-notes v1.1.0..v1.2.0 # Update changelog giv changelog v1.2.0 --update # Generate announcement giv announcement v1.2.0

Code Review Workflow

# Summarize PR changes giv summary origin/main..HEAD # Generate commit messages for fixup commits git add -A giv message --format conventional # Squash commit message giv summary --format single-line

📊 Version Intelligence

Automatic Version Detection

giv automatically detects project versions from:

package.json pyproject.toml Cargo.toml pom.xml Git tags

SemVer Management

# Auto-detect next version giv changelog --next-version # Specify version explicitly giv changelog v1.2.0 # Generate version-specific content giv release-notes --version 2.0.0

Changelog Management

# Update existing CHANGELOG.md giv changelog --update # Prepend to changelog giv changelog --mode prepend # Append to specific section giv changelog --mode append --section "Unreleased"

Configuration Reference

Complete configuration system with inheritance and environment variables

⚙️ Configuration Hierarchy

Configuration values are resolved in this order (highest to lowest priority):

1

Command Line Arguments

Options passed directly to commands

giv message --model gpt-4 --provider openai
2

Environment Variables

Environment variables with GIV_ prefix

export GIV_API_MODEL="claude-3-sonnet" export OPENAI_API_KEY="your-key"
3

Project Configuration

Project-specific config in .giv/config

[api] model = gpt-4 provider = openai
4

User Configuration

User-wide config in ~/.giv/config

[api] key = your-global-api-key
5

Default Values

Built-in defaults and fallbacks

api.model = gpt-3.5-turbo output.format = markdown

📋 Configuration Reference

API Configuration

api.key API key for authentication
api.url API endpoint URL
api.model Model name to use
api.provider Provider type (openai, anthropic, ollama)
api.timeout Request timeout in seconds

Output Configuration

output.format Default output format
output.mode Output mode (stdout, append, prepend)
output.file Default output file

Template Configuration

template.path Custom template directory
template.variables Custom template variables

🔧 Configuration Management

Common Configuration Tasks

# View current configuration giv config list # Set API provider giv config set api.provider anthropic giv config set api.model claude-3-sonnet-20240229 # Set output preferences giv config set output.format conventional giv config set output.mode append # Remove configuration giv config unset api.key # Get specific value giv config get api.model

Environment Variable Mapping

# Common environment variables export GIV_API_KEY="your-api-key" export GIV_API_MODEL="gpt-4" export GIV_API_PROVIDER="openai" export GIV_OUTPUT_FORMAT="conventional" # Provider-specific variables export OPENAI_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..." export OLLAMA_API_URL="http://localhost:11434"

Continue Learning

Explore more giv capabilities and related tools

🎯

Real-World Examples

See giv in action with practical workflows, team collaboration patterns, and automation scripts

→
🔄

Ecosystem Integration

Learn how giv works with inform, catalog, and unify for complete development workflows

→
📂

Source Code

View the source code, contribute improvements, or report issues on GitHub

→