Git Exec

Go library that wraps Git commands and returns structured output.

Features

Structured output via Go structs instead of string parsing
Standard Go error handling with context
Session management with persistent user configuration
Merge conflict detection and resolution
Mockery-compatible interfaces

Installation

go get github.com/instruqt/git-exec

Quick Start

package main

import (
    "fmt"
    "log"
    "os"
    
    "github.com/instruqt/git-exec/pkg/git"
)

func main() {
    // Create Git instance
    gitInstance, err := git.NewGit()
    if err != nil {
        log.Fatal(err)
    }
    
    // Initialize repository
    err = gitInstance.Init("/path/to/repo")
    if err != nil {
        log.Fatal(err)
    }
    
    gitInstance.SetWorkingDirectory("/path/to/repo")
    
    // Configure user
    err = gitInstance.SetConfig("user.name", "Your Name")
    if err != nil {
        log.Fatal(err)
    }
    
    err = gitInstance.SetConfig("user.email", "you@example.com")
    if err != nil {
        log.Fatal(err)
    }
    
    // Add and commit files
    err = gitInstance.Add([]string{"."})
    if err != nil {
        log.Fatal(err)
    }
    
    err = gitInstance.Commit("Initial commit")
    if err != nil {
        log.Fatal(err)
    }
    
    // Check status
    files, err := gitInstance.Status()
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Repository has %d files\n", len(files))
}

Usage Examples

Basic Operations

// Get commit history
logs, err := gitInstance.Log(git.LogWithMaxCount("5"))
if err != nil {
    log.Fatal(err)
}

for _, logEntry := range logs {
    fmt.Printf("%s: %s - %s\n", logEntry.Hash[:8], logEntry.Message, logEntry.Author)
}

// Check repository status
files, err := gitInstance.Status()
if err != nil {
    log.Fatal(err)
}

for _, file := range files {
    fmt.Printf("%s %s\n", file.Status, file.Name)
}

Session Management

Sessions maintain user configuration across operations:

// Create session with user configuration
session, err := git.NewSession("/path/to/project",
    git.SessionWithUser("Alice Developer", "alice@company.com"),
    git.SessionWithMetadata("user", "id", "user-123"),
    git.SessionWithMetadata("user", "role", "developer"), 
    git.SessionWithMetadata("project", "name", "web-app"),
    git.SessionWithMetadata("project", "version", "1.0.0"),
    git.SessionWithMetadata("team", "name", "frontend"),
)
if err != nil {
    log.Fatal(err)
}

// User context is automatically applied to all operations
err = session.Add([]string{"README.md"})
if err != nil {
    log.Fatal(err)
}

err = session.Commit("Initial project setup")
if err != nil {
    log.Fatal(err)
}

// Load existing session
loadedSession, err := git.LoadSession("/path/to/project")
if err != nil {
    log.Fatal(err)
}

Branch Management

// Create and switch to new branch
err = gitInstance.CreateBranch("feature/auth")
if err != nil {
    log.Fatal(err)
}

result, err := gitInstance.Checkout(git.CheckoutWithBranch("feature/auth"))
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Switched to branch: %s\n", result.Branch)

// List all branches
branches, err := gitInstance.ListBranches()
if err != nil {
    log.Fatal(err)
}

for _, branch := range branches {
    marker := " "
    if branch.Active {
        marker = "*"
    }
    fmt.Printf("  %s %s\n", marker, branch.Name)
}

Enhanced Checkout Operations

The checkout operation returns detailed information about the checkout result:

// Checkout existing branch
result, err := gitInstance.Checkout(git.CheckoutWithBranch("feature"))
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Success: %v\n", result.Success)
fmt.Printf("Branch: %s\n", result.Branch)
fmt.Printf("Previous HEAD: %s\n", result.PreviousHEAD)
fmt.Printf("New HEAD: %s\n", result.NewHEAD)

// Create and checkout new branch
result, err = gitInstance.Checkout(git.CheckoutWithCreate("new-feature"))
if err != nil {
    log.Fatal(err)
}

if result.NewBranch {
    fmt.Printf("Created new branch: %s\n", result.Branch)
}

// Checkout specific commit (detached HEAD)
result, err = gitInstance.Checkout(git.CheckoutWithCommit("abc123"))
if err != nil {
    log.Fatal(err)
}

if result.DetachedHEAD {
    fmt.Printf("Detached HEAD at commit: %s\n", result.Commit)
}

// Checkout with file modifications
result, err = gitInstance.Checkout(git.CheckoutWithBranch("main"))
if err != nil {
    log.Fatal(err)
}

if len(result.ModifiedFiles) > 0 {
    fmt.Printf("Modified files: %v\n", result.ModifiedFiles)
}

if result.Warning != "" {
    fmt.Printf("Warning: %s\n", result.Warning)
}

// Checkout specific files from HEAD or a commit
result, err = gitInstance.Checkout(git.CheckoutWithFiles([]string{"src/main.go", "README.md"}))
if err != nil {
    log.Fatal(err)
}

// Checkout files from a specific commit
result, err = gitInstance.Checkout(
    git.CheckoutWithCommit("abc123"),
    git.CheckoutWithFiles([]string{"config.json"}),
)
if err != nil {
    log.Fatal(err)
}

Merge Operations with Conflict Resolution

// Attempt merge
result, err := gitInstance.Merge(git.MergeWithBranch("feature/auth"))
if err != nil {
    log.Fatal(err)
}

if result.Success {
    fmt.Printf("Merge successful: %s\n", result.MergedBranch)
} else {
    fmt.Printf("Merge conflicts detected in %d files\n", len(result.ConflictedFiles))
    
    // Show conflict details
    for _, conflict := range result.Conflicts {
        fmt.Printf("Conflict in %s:\n", conflict.Path)
        for i, section := range conflict.Sections {
            fmt.Printf("  Section %d: Our=%q, Their=%q\n", 
                i+1, section.OurContent, section.TheirContent)
        }
    }
    
    // Option 1: Resolve conflicts programmatically
    resolutions := []types.ConflictResolution{
        {
            FilePath: "conflicted-file.txt",
            UseOurs:  true, // or provide custom Resolution content
        },
    }
    
    err = gitInstance.ResolveConflicts(resolutions)
    if err != nil {
        log.Fatal(err)
    }
    
    // Continue merge
    err = gitInstance.MergeContinue()
    if err != nil {
        log.Fatal(err)
    }
}

Manual Conflict Resolution

Alternatively, conflicts can be resolved by manually editing files:

// Attempt merge
result, err := gitInstance.Merge(git.MergeWithBranch("feature/auth"))
if err != nil {
    log.Fatal(err)
}

if !result.Success && len(result.Conflicts) > 0 {
    fmt.Printf("Merge conflicts detected in %d files:\n", len(result.ConflictedFiles))
    
    for _, conflictFile := range result.ConflictedFiles {
        fmt.Printf("  - %s\n", conflictFile)
    }
    
    fmt.Println("\nPlease resolve conflicts manually:")
    fmt.Println("1. Edit the conflicted files to resolve conflicts")
    fmt.Println("2. Remove conflict markers (<<<<<<, ======, >>>>>>)")
    fmt.Println("3. Stage resolved files and continue merge")
    
    // Wait for manual resolution...
    // User edits files externally in IDE/editor
    
    // After manual resolution, stage the resolved files
    err = gitInstance.Add(result.ConflictedFiles)
    if err != nil {
        log.Fatal(err)
    }
    
    // Continue the merge
    err = gitInstance.MergeContinue()
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Println("Merge completed successfully")
}

Configuration Management

Complete git configuration management with support for getting, setting, listing, and unsetting config values across different scopes.

// Set configuration values
err = gitInstance.SetConfig("user.name", "John Doe")
if err != nil {
    log.Fatal(err)
}

err = gitInstance.SetConfig("user.email", "john@example.com")
if err != nil {
    log.Fatal(err)
}

// Get configuration values
name, err := gitInstance.GetConfig("user.name")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("User name: %s\n", name)

// List all configuration entries
configs, err := gitInstance.ListConfig()
if err != nil {
    log.Fatal(err)
}

for _, config := range configs {
    fmt.Printf("%s=%s (scope: %s, source: %s)\n", 
        config.Key, config.Value, config.Scope, config.Source)
}

// Unset a configuration value
err = gitInstance.UnsetConfig("user.nickname")
if err != nil {
    log.Fatal(err)
}

Configuration Scopes

Work with different configuration scopes (local, global, system):

// Set local repository config
err = gitInstance.SetConfig("core.autocrlf", "false", git.ConfigWithLocalScope())
if err != nil {
    log.Fatal(err)
}

// Set global user config  
err = gitInstance.SetConfig("user.name", "John Doe", git.ConfigWithGlobalScope())
if err != nil {
    log.Fatal(err)
}

// Get config from specific scope
email, err := gitInstance.GetConfig("user.email", git.ConfigWithGlobalScope())
if err != nil {
    log.Fatal(err)
}

// List configs with scope and origin information
configs, err := gitInstance.ListConfig(git.ConfigWithAllScopes(), git.ConfigWithShowOrigin())
if err != nil {
    log.Fatal(err)
}

for _, config := range configs {
    fmt.Printf("[%s] %s=%s (from %s)\n", 
        config.Scope, config.Key, config.Value, config.Source)
}

Bare Repository Support

The library provides full support for bare repositories, commonly used for server-side Git operations:

// Create a bare repository
err := gitInstance.Init("/path/to/repo.git", git.InitWithBare())
if err != nil {
    log.Fatal(err)
}

// Clone as bare repository
err = gitInstance.Clone("https://github.com/user/repo.git", "local.git", 
    git.CloneWithBare())
if err != nil {
    log.Fatal(err)
}

// Check if repository is bare
isBare, err := gitInstance.IsBareRepository()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Repository is bare: %v\n", isBare)

// All standard operations work in bare repositories
// (branches, tags, commits, etc. - just no working directory operations)
branches, err := gitInstance.ListBranches()
tags, err := gitInstance.ListTags()
err = gitInstance.CreateBranch("feature")
err = gitInstance.Tag("v1.0.0")

Bare repositories are ideal for:

Git servers (GitHub, GitLab, etc.)
Centralized repositories
Deployment targets
Backup repositories

Testing

Run tests:

go test ./...

Generate mocks for testing:

go install github.com/vektra/mockery/v2@latest
mockery --dir=pkg/git --name=Git
mockery --dir=pkg/git --name=Session

Examples

See the /examples directory for complete working examples:

01_basic_operations.go - Basic Git operations
02_session_management.go - Session management with persistent context
03_merge_operations.go - Merge operations and conflict resolution
04_branch_management.go - Branch creation, switching, and management

Run examples:

go run examples/01_basic_operations.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Git Exec

Features

Installation

Quick Start

Usage Examples

Basic Operations

Session Management

Branch Management

Enhanced Checkout Operations

Merge Operations with Conflict Resolution

Manual Conflict Resolution

Configuration Management

Configuration Scopes

Bare Repository Support

Testing

Examples

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Git Exec

Features

Installation

Quick Start

Usage Examples

Basic Operations

Session Management

Branch Management

Enhanced Checkout Operations

Merge Operations with Conflict Resolution

Manual Conflict Resolution

Configuration Management

Configuration Scopes

Bare Repository Support

Testing

Examples