git

Git Operations Module

This package provides comprehensive Git repository operations for the Hitch workflow management system. The module has been refactored from a monolithic 551-line file into focused, single-responsibility modules with proper error handling and security validation.

Overview

The git operations module consists of:

• Repository Management - Core repository operations and state management
• Branch Operations - Branch creation, deletion, and validation
• Merge Operations - Advanced merge capabilities with conflict handling
• Remote Operations - Push/pull operations with safety checks
• Security - Input sanitization and command injection prevention
• Error Handling - Structured error types for all git operations

Architecture

Module Structure

internal/git/
├── README.md              # This documentation
├── repo.go               # Core repository management and initialization
├── repo_branches.go      # Branch operations (create, delete, validate)
├── repo_merges.go        # Merge operations with conflict detection
├── repo_remotes.go       Remote operations (push, pull with safety)
├── repo_state.go         # Repository state and status queries
├── repo_info.go          # Repository information and metadata
├── repo_user.go          # User-related git operations
├── operations.go         # Low-level git command execution
├── sanitizer.go          # Input security and validation
├── validator.go          // Git-specific validation logic
├── conflict_handler.go   // Merge conflict resolution
├── command_helpers.go    // Command execution utilities
└── git_test.go           // Comprehensive test suite

Core Components

Repository Management

The Repo struct is the central interface for all git operations:

type Repo struct {
    *git.Repository        // go-git repository instance
    workdir             string // Working directory path
    mutex               sync.RWMutex // Thread safety
}

Key Functions

// Repository initialization
func OpenRepo(path string) (*Repo, error)
func (r *Repo) IsBare() bool
func (r *Repo) IsEmpty() bool
func (r *Repo) WorkingTree() string

// Repository state
func (r *Repo) HasUncommittedChanges() (bool, error)
func (r *Repo) HasStagedChanges() (bool, error)
func (r *Repo) GetCurrentBranch() (string, error)
func (r *Repo) IsCleanWorkingTree() (bool, error)

Branch Operations

Comprehensive branch management with security validation:

// Branch existence and validation
func (r *Repo) BranchExists(name string) bool
func (r *Repo) CreateBranch(name string, fromRef string) error
func (r *Repo) DeleteBranch(name string, force bool) error
func (r *Repo) DeleteRemoteBranch(remoteName, branchName string) error

// Branch listing and information
func (r *Repo) GetBranches() ([]string, error)
func (r *Repo) GetRemoteBranches() ([]string, error)
func (r *Repo) GetLocalBranches() ([]string, error)

Security Features

All branch operations include:

• Input Sanitization - Prevents command injection attacks
• Name Validation - Ensures git-safe branch names
• Permission Checks - Validates branch operation permissions
• Error Handling - Structured error types for better debugging

Merge Operations

Advanced merge capabilities with conflict detection and resolution:

// Merge operations
func (r *Repo) Merge(branch string, message string) error
func (r *Repo) MergeSquash(branch string, message string) error
func (r *Repo) MergeAbort() error
func (r *Repo) IsMergeInProgress() bool

// Merge validation
func (r *Repo) CanMerge(branch string) (bool, error)

// Conflict handling
func (r *Repo) GetConflictingFiles() ([]string, error)
func (r *Repo) HasConflicts() (bool, error)

Conflict Detection

The system automatically detects and reports merge conflicts:

type MergeConflictError struct {
    Branch       string   // Source branch
    ConflictFiles []string // Files with conflicts
    Message      string   // Detailed conflict information
}

Remote Operations

Safe push/pull operations with force-with-lease protection:

// Push and pull operations
func (r *Repo) Pull(remoteName, branchName string) error
func (r *Repo) Push(remoteName, branchName string, force bool) error

// Remote management
func (r *Repo) AddRemote(name, url string) error
func (r *Repo) RemoveRemote(name string) error
func (r *Repo) GetRemotes() ([]string, error)
func (r *Repo) GetRemoteURL(name string) (string, error)

Safety Features

• Force-with-Lease - Safe force pushes that respect remote changes
• Connection Validation - Validates remote URLs and connections
• Operation Safety - Prevents destructive operations without confirmation

Security and Validation

Input Sanitization

type InputSanitizer struct{}

func (s *InputSanitizer) SanitizeBranchName(branch string) error
func (s *InputSanitizer) SanitizeCommitMessage(message string) error
func (s *InputSanitizer) SanitizeRemoteName(remote string) error
func (s *InputSanitizer) ValidateRef(ref string) error

Security Features

• Command Injection Prevention - Blocks dangerous shell metacharacters
• Path Traversal Protection - Prevents ../ attacks
• Length Validation - Prevents DoS attacks with long inputs
• Character Validation - Ensures only safe characters are used
• Pattern Detection - Identifies suspicious command patterns

Usage Examples

Basic Repository Operations

// Open a repository
repo, err := git.OpenRepo("/path/to/repo")
if err != nil {
    return fmt.Errorf("failed to open repository: %w", err)
}
defer repo.Close()

// Check repository state
isClean, err := repo.IsCleanWorkingTree()
if err != nil {
    return fmt.Errorf("failed to check repository state: %w", err)
}

if !isClean {
    fmt.Println("Repository has uncommitted changes")
}

Branch Operations

// Create a new branch
err := repo.CreateBranch("feature/new-feature", "main")
if err != nil {
    // Returns structured GitBranchError
    return fmt.Errorf("failed to create branch: %w", err)
}

// Check if branch exists
if repo.BranchExists("feature/new-feature") {
    fmt.Println("Branch already exists")
}

// Delete a branch (with force option)
err = repo.DeleteBranch("feature/old-feature", true)
if err != nil {
    return fmt.Errorf("failed to delete branch: %w", err)
}

Merge Operations

// Test if merge is possible
canMerge, err := repo.CanMerge("feature/branch")
if err != nil {
    return fmt.Errorf("failed to test merge: %w", err)
}

if canMerge {
    // Perform the merge
    err = repo.Merge("feature/branch", "Merge feature branch")
    if err != nil {
        // Handle merge conflicts
        if mergeErr, ok := err.(*MergeConflictError); ok {
            fmt.Printf("Merge conflicts in: %v\n", mergeErr.ConflictFiles)
            return handleConflicts(mergeErr)
        }
        return fmt.Errorf("merge failed: %w", err)
    }
    fmt.Println("Merge completed successfully")
}

Remote Operations

// Safe push with force-with-lease
err := repo.Push("origin", "feature-branch", false) // No force
if err != nil {
    return fmt.Errorf("push failed: %w", err)
}

// Pull latest changes
err = repo.Pull("origin", "main")
if err != nil {
    // Returns structured GitPullError
    return fmt.Errorf("pull failed: %w", err)
}

Security Validation

// Create input sanitizer
sanitizer := git.NewInputSanitizer()

// Validate user input
branchName := getUserInput()
if err := sanitizer.SanitizeBranchName(branchName); err != nil {
    return fmt.Errorf("invalid branch name: %w", err)
}

// Safe to use the validated branch name
err = repo.CreateBranch(branchName, "main")

Error Handling

All operations return structured error types:

// Category-based error handling
func handleGitError(err error) error {
    if err == nil {
        return nil
    }

    switch errors.GetCategory(err) {
    case errors.CategoryGitOperation:
        // Handle git-specific errors
        if gitErr, ok := err.(*errors.GitOperationError); ok {
            fmt.Printf("Git %s operation failed: %s\n", gitErr.Operation, gitErr.Reason)
        }
    case errors.CategoryValidation:
        // Handle validation errors
        return fmt.Errorf("input validation failed: %w", err)
    default:
        return fmt.Errorf("unexpected error: %w", err)
    }
}

Integration

With Validation Framework

import "github.com/DoomedRamen/hitch/internal/validation"

// Use validation framework with git operations
adapter := validation.BranchValidationAdapter()

func createValidBranch(name string) error {
    // Validate using common validation framework
    if err := adapter.ValidateWithErrors(name, name); err != nil {
        return err
    }

    // Safe to create branch
    return repo.CreateBranch(name, "main")
}

With Error Handling System

import hitcherrors "github.com/DoomedRamen/hitch/internal/errors"

func performSafeMerge(branch string) error {
    // Check merge compatibility
    canMerge, err := repo.CanMerge(branch)
    if err != nil {
        return hitcherrors.NewGitOperationError("merge-test", branch, "failed to test merge", err)
    }

    if !canMerge {
        return hitcherrors.NewValidationError("cannot merge", "branch has conflicts")
    }

    // Perform merge
    err = repo.Merge(branch, "Automated merge")
    if err != nil {
        return hitcherrors.NewGitMergeError(branch, "merge failed", err.Error())
    }

    return nil
}

Performance Considerations

• Repository Caching - Repository instances are cached for performance
• Command Efficiency - Git commands are optimized and batched when possible
• Concurrent Safety - Thread-safe operations with proper locking
• Memory Management - Proper cleanup of git resources

Testing

The module includes comprehensive test coverage:

# Run all git tests
go test ./internal/git

# Run specific test suites
go test ./internal/git -run TestRepo_BranchOperations
go test ./internal/git -run TestRepo_MergeOperations
go test ./internal/git -run TestRepo_SecurityValidation

Test Categories

• Unit Tests - Individual function testing
• Integration Tests - Multi-function workflow testing
• Security Tests - Input validation and injection prevention
• Error Handling Tests - Error type and message validation
• Performance Tests - Large repository handling

Migration Guide

From Monolithic git.go

The original 551-line git.go file has been split into focused modules:

1. Branch Operations → repo_branches.go
2. Merge Operations → repo_merges.go
3. Remote Operations → repo_remotes.go
4. State Management → repo_state.go
5. Security → sanitizer.go, validator.go

Usage Changes

Before:

// Monolithic approach
gitRepo, err := git.OpenRepository(path)
if err != nil {
    return err
}
// All operations in one massive file

After:

// Modular approach
repo, err := git.OpenRepo(path)
if err != nil {
    return err
}
// Operations split into focused modules with proper error handling

Best Practices

1. Always Validate Input - Use sanitizers before git operations
2. Handle Errors Properly - Use structured error types for better debugging
3. Check Repository State - Verify repository state before operations
4. Use Safe Operations - Prefer force-with-lease over force pushes
5. Test Thoroughly - Include edge cases and security scenarios
6. Document Operations - Add context to errors for better debugging

Future Enhancements

• Parallel Operations - Concurrent git operations where safe
• Advanced Conflict Resolution - More sophisticated conflict handling
• Performance Optimization - Further optimization for large repositories
• Enhanced Security - Additional security validation patterns
• Better Integration - Deeper integration with validation framework

This git operations module provides a solid, secure, and maintainable foundation for all git-related operations in the Hitch application.