Git Operations

Forge provides intelligent git integration that helps with commit messages, branch management, pull requests, and conflict resolution. It understands your changes contextually and generates professional git operations automatically.

Overview

Forge’s git integration:

Generates commit messages from staged changes
Creates pull request descriptions with context
Resolves merge conflicts with AI assistance
Analyzes branch changes for comprehensive reviews
Follows conventions like Conventional Commits

Key Benefit

Never write another generic “fix stuff” commit message. Forge analyzes your changes and generates descriptive, conventional commit messages automatically.

Commit Message Generation

Basic Usage

ZSH Plugin
CLI Command
From Diff

# Stage your changes
git add .

# Generate and commit with AI message
: Generate a commit message and commit the changes

# Generate message only (preview)
forge git commit-message

# Generate and commit
forge git commit

# Generate from piped diff
git diff | forge git commit-message

# Specify max diff size (100KB)
git diff | forge git commit-message --max-diff-size 100000

How It Works

When you generate a commit message, Forge:

Captures context:
- Staged or unstaged changes (git diff)
- Current branch name
- Recent commit messages (last 20)
- Additional context if provided
Analyzes changes:
- Identifies modified files and functions
- Understands the nature of changes
- Recognizes patterns (feature, fix, refactor)
Generates message:
- Follows Conventional Commits format
- Summarizes changes concisely
- Focuses on “why” not just “what”
- Adapts to your project’s style
Commits properly:
- Sets you as the author (from git config)
- Sets ForgeCode as the committer
- Properly attributes the commit to both

Commit Format

Forge generates commits following Conventional Commits:

type(scope): brief description

- Detailed explanation of changes
- Why the changes were made
- Impact on the system

Examples:

feat(auth): add JWT token refresh mechanism

- Implement automatic token refresh before expiry
- Add refresh token rotation for security
- Handle refresh failures with user re-authentication

fix(api): resolve race condition in user session handling

- Add mutex lock for concurrent session access
- Prevent duplicate session creation
- Fixes issue where users occasionally logged out unexpectedly

refactor(database): optimize query performance for user lookups

- Replace N+1 queries with batch loading
- Add database indexes for email and username
- Reduces average lookup time from 200ms to 15ms

Configuration

Control commit message generation:

# Maximum diff size in bytes (default: unlimited)
export FORGE_MAX_COMMIT_DIFF=100000

# For shell plugin
export FORGE_MAX_COMMIT_DIFF=100000

Why limit diff size?

Large diffs can exceed model context limits
Truncation focuses on most important changes
Improves generation speed and quality

Adding Context

Provide additional context for better messages:

: Generate commit message for these auth changes
: Context: Implementing OAuth2 flow for third-party login

Pull Request Workflows

Creating Pull Requests

Forge integrates with GitHub CLI (gh) for PR creation:

# In your feature branch
: Create a pull request for this branch

Forge will:

Analyze all commits since branching from main/master
Review the full diff of changes
Generate comprehensive PR description
Create the PR using gh pr create

PR Description Format

## Summary

- Brief overview of changes
- Key features or fixes added
- Impact on existing functionality

## Motivation and Context

Explanation of why these changes were needed and the problem they solve.

## Testing Performed

- Unit tests added/updated
- Integration tests verified
- Manual testing scenarios

## Breaking Changes

List any breaking changes and migration steps (if applicable).

Updating PR Descriptions

Use custom commands to update PR descriptions:

# Using the github-pr-description command
forge -c commands/github-pr-description.md

This command:

Analyzes current PR changes
Generates updated description
Updates the PR using gh CLI

Merge Conflict Resolution

Get AI assistance with merge conflicts:

Interactive Resolution
Explain Conflicts

# After merge conflict occurs
git merge feature-branch
# CONFLICT in src/app.rs

# Get help from Forge
: Help me resolve git conflicts in @[src/app.rs]

Forge will:

Analyze both versions
Understand the conflicting changes
Suggest resolution strategy
Explain trade-offs

# Understand what's conflicting
: Explain the merge conflicts and differences

Get detailed explanation:

What changed in each branch
Why conflicts occurred
Which changes to keep
Potential side effects

Branch Analysis

Analyze branch changes before merging:

# Review all changes in current branch
: Review the current branch changes

# Compare with main branch
: Compare this branch with main and summarize differences

# Identify potential issues
: Check for any breaking changes in this branch

Git Workflow Patterns

Feature Development

# Start feature branch
git checkout -b feature/new-caching

# Make changes and stage
git add .

# Generate good commit message
: Generate commit message for these caching changes
forge git commit

# Continue development with context
: Add tests for the caching layer @[tests/cache_test.rs]

# Prepare for PR
: Create a pull request explaining the caching improvements

Bug Fixes

# Create fix branch
git checkout -b fix/auth-token-expiry

# Make changes
vim src/auth/token.rs

# Commit with proper format
git add src/auth/token.rs
forge git commit
# Generates: "fix(auth): resolve token expiry check bug"

# Create PR with details
: Create PR explaining this bug fix and its impact

Refactoring

# Stage refactored code
git add src/database/

# Generate refactor commit
forge git commit
# Generates: "refactor(database): improve query builder architecture"

# Review changes
: Review the refactoring changes and check for issues

Advanced Features

Commit Attribution

Forge properly sets git authorship:

# Author: Your Name <[email protected]>  (from git config)
# Committer: ForgeCode <[email protected]>

This gives credit to both you and Forge:

Author: Who wrote the changes (you)
Committer: Who created the commit (ForgeCode)

Co-authored Commits

For team workflows, include co-authors:

: Generate commit message
: Add co-author: Jane Doe <[email protected]m>

Working with Staged vs Unstaged

Forge intelligently handles both:

# Staged changes take priority
git add src/important.rs
forge git commit  # Only commits staged files

# Unstaged changes as fallback
# (no staged files)
forge git commit  # Analyzes unstaged, suggests staging

Diff Truncation

For large changes:

# Truncate to 50KB
forge git commit-message --max-diff-size 50000

# Forge will:
# 1. Truncate at character boundary
# 2. Focus on most important changes
# 3. Generate message from available context

Git Commands Reference

forge git commit-message
forge git commit-message --max-diff-size 100000
git diff | forge git commit-message

Best Practices

Atomic Commits

Stage related changes together:

# Good: Related changes
git add src/auth/*.rs tests/auth_test.rs
forge git commit

# Bad: Unrelated changes
git add .  # Everything including unrelated files
forge git commit

Review Generated Messages

Always review before committing:

# Preview first
forge git commit-message

# If good, commit
forge git commit

# Or edit manually
git commit -m "$(forge git commit-message | edit)"

Provide Context

Add context for better messages:

# Good
: Generate commit for this security fix
: Context: Addresses CVE-2024-1234

# Better
forge git commit --additional-context "Fixes CVE-2024-1234 by validating input"

Follow Project Conventions

Forge learns from your commit history:

# Your project uses specific prefixes
# Forge will adapt to patterns like:
# [JIRA-123] feat: description
# 🎨 style: description

Troubleshooting

No changes to commit error

# Ensure you have changes
git status

# Stage changes
git add <files>

# Or commit all tracked changes
git add -u
forge git commit

Generated message is too generic

Provide additional context with --additional-context
Make more focused, atomic commits
Check that meaningful changes are staged
Verify diff is not truncated too aggressively

Commit fails with git error

# Check git config
git config user.name
git config user.email

# Set if missing
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

PR creation fails

Install GitHub CLI: brew install gh
Authenticate: gh auth login
Verify you’re in a git repository with remote
Check you’re on a branch (not detached HEAD)

Integration Examples

With Custom Commands

Create a complete git workflow command:

---
name: prepare-pr
description: Prepare branch for pull request
---

1. Run tests and linting
2. Stage all changes: `git add .`
3. Generate and create commit with descriptive message
4. Push branch to remote
5. Create pull request with comprehensive description
6. Add reviewers based on CODEOWNERS

With Shell Integration

Streamlined git workflow:

# Make changes
vim src/feature.rs

# Quick commit
: Stage and commit these changes

# Push and create PR
: Push to remote and create pull request

# All in one conversation context

Shell Integration - Git operations via : commands
Custom Commands - Automate git workflows
Multi-Agent Workflows - Orchestrate complex git operations

Getting Started

Core Concepts

Configuration

Providers

Features

Advanced Usage

Guides

Git Operations

Overview

Key Benefit

Commit Message Generation

Basic Usage

How It Works

Commit Format

Configuration

Adding Context

Pull Request Workflows

Creating Pull Requests

PR Description Format

Updating PR Descriptions

Merge Conflict Resolution

Branch Analysis

Git Workflow Patterns

Feature Development

Bug Fixes

Refactoring

Advanced Features

Commit Attribution

Co-authored Commits

Working with Staged vs Unstaged

Diff Truncation

Git Commands Reference

Best Practices

Troubleshooting

Integration Examples

With Custom Commands

With Shell Integration

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Configuration

Providers

Features

Advanced Usage

Guides

​Overview

Key Benefit

​Commit Message Generation

​Basic Usage

​How It Works

​Commit Format

​Configuration

​Adding Context

​Pull Request Workflows

​Creating Pull Requests

​PR Description Format

​Updating PR Descriptions

​Merge Conflict Resolution

​Branch Analysis

​Git Workflow Patterns

​Feature Development

​Bug Fixes

​Refactoring

​Advanced Features

​Commit Attribution

​Co-authored Commits

​Working with Staged vs Unstaged

​Diff Truncation

​Git Commands Reference

​Best Practices

​Troubleshooting

​Integration Examples

​With Custom Commands

​With Shell Integration

​Related Features

Build docs developers (and LLMs) love

Overview

Commit Message Generation

Basic Usage

How It Works

Commit Format

Configuration

Adding Context

Pull Request Workflows

Creating Pull Requests

PR Description Format

Updating PR Descriptions

Merge Conflict Resolution

Branch Analysis

Git Workflow Patterns

Feature Development

Bug Fixes

Refactoring

Advanced Features

Commit Attribution

Co-authored Commits

Working with Staged vs Unstaged

Diff Truncation

Git Commands Reference

Best Practices

Troubleshooting

Integration Examples

With Custom Commands

With Shell Integration

Related Features