gogit

Enhanced Git operations toolkit providing streamlined repo management with comprehensive commit and remote sync capabilities.

---

CHINESE README

中文说明

Core Features

🎯 Streamlined Git Operations: Intelligent staging, committing, and status checking with comprehensive API ⚡ Smart Commit Management: Auto staging with commit and amend support, prevents unsafe operations 🔄 Remote Push Detection: Automatic checking of commit push status across multiple remotes 🌍 Cross-Platform Support: Pure Go implementation without CLI dependencies using go-git foundation 📋 Fluent API Design: Builder pattern for convenient configuration and method chaining

Installation

go get github.com/go-xlan/gogit

Quick Start

Basic Usage

package main

import (
    "fmt"
    "log"

    "github.com/go-xlan/gogit"
)

func main() {
    // Initialize Git client
    client, err := gogit.New("/path/to/your/repo")
    if err != nil {
        log.Fatal(err)
    }

    // Stage all changes
    err = client.AddAll()
    if err != nil {
        log.Fatal(err)
    }

    // Create commit info with fluent API
    commitInfo := gogit.NewCommitInfo("Initial commit").
        WithName("Your Name").
        WithMailbox("[email protected]")

    // Commit changes
    hash, err := client.CommitAll(commitInfo)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Commit created: %s\n", hash)
}

Advanced Features

// Check repository status
status, err := client.Status()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Repository status: %+v\n", status)

// Amend last commit (with safety check)
amendConfig := &gogit.AmendConfig{
    CommitInfo: gogit.NewCommitInfo("Updated commit message").
        WithName("Updated Name").
        WithMailbox("[email protected]"),
    ForceAmend: false, // Prevents amending pushed commits
}

hash, err := client.AmendCommit(amendConfig)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Amended commit: %s\n", hash)

// Check if latest commit was pushed to remote
pushed, err := client.IsLatestCommitPushed()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Latest commit pushed: %t\n", pushed)

API Reference

Core Methods

• gogit.New(root string) (*Client, error) Creates a new Git client for the specified repo path with ignore file support

• client.AddAll() error Stages all changes including new files, modifications, and deletions

• client.Status() (git.Status, error) Returns current worktree status with comprehensive file change info

• client.CommitAll(info *CommitInfo) (string, error) Commits all staged changes with provided creator signature and message

• client.AmendCommit(cfg *AmendConfig) (string, error) Amends the last commit with safety checks for pushed commits

• client.IsLatestCommitPushed() (bool, error) Checks if current branch has been pushed to any configured remote

• client.IsLatestCommitPushedToRemote(name string) (bool, error) Checks push status against a specific remote repo

Configuration Types

// CommitInfo - Fluent commit configuration
type CommitInfo struct {
    Name    string // Creator name for Git commits
    Mailbox string // Creator mailbox for Git commits
    Message string // Commit message content
}

// AmendConfig - Amend operation configuration
type AmendConfig struct {
    CommitInfo *CommitInfo // New commit info for amend operation
    ForceAmend bool        // Allow amend even if commit was pushed
}

Fluent API Examples

// Create commit info with method chaining
commitInfo := gogit.NewCommitInfo("Feature implementation").
    WithName("Developer Name").
    WithMailbox("[email protected]")

// Use default message generation if no message provided
commitInfo := gogit.NewCommitInfo("").
    WithName("Auto User").
    WithMailbox("[email protected]")
// Generates timestamp-based message: "[gogit](github.com/go-xlan/gogit) 2024-01-15 14:30:45"

Safety Features

• Push Detection: Prevents amending commits that have been pushed to remote repos
• Ignore File Support: Respects .gitignore patterns during operations
• Empty Commit Handling: Returns empty string for no-change commits
• Error Context: Comprehensive error wrapping with context info
• Hash Verification: Validates commit integrity after operations

Best Practices

// Always check for errors
client, err := gogit.New("/path/to/repo")
if err != nil {
    return fmt.Errorf("failed to create client: %w", err)
}

// Use fluent API for clean configuration
info := gogit.NewCommitInfo("Fix critical bug").
    WithName("Bug Fixer").
    WithMailbox("[email protected]")

// Check push status before amending
if pushed, _ := client.IsLatestCommitPushed(); pushed {
    log.Println("Warning: Cannot amend pushed commit")
} else {
    // Safe to amend
    hash, err := client.AmendCommit(&gogit.AmendConfig{
        CommitInfo: info,
        ForceAmend: false,
    })
}

📄 License

MIT License. See LICENSE.

---

🤝 Contributing

Contributions are welcome! Report bugs, suggest features, and contribute code:

• 🐛 Found a mistake? Open an issue on GitHub with reproduction steps
• 💡 Have a feature idea? Create an issue to discuss the suggestion
• 📖 Documentation confusing? Report it so we can improve
• 🚀 Need new features? Share the use cases to help us understand requirements
• ⚡ Performance issue? Help us optimize through reporting slow operations
• 🔧 Configuration problem? Ask questions about complex setups
• 📢 Follow project progress? Watch the repo to get new releases and features
• 🌟 Success stories? Share how this package improved the workflow
• 💬 Feedback? We welcome suggestions and comments

---

🔧 Development

New code contributions, follow this process:

1. Fork: Fork the repo on GitHub (using the webpage UI).
2. Clone: Clone the forked project (git clone https://github.com/yourname/repo-name.git).
3. Navigate: Navigate to the cloned project (cd repo-name)
4. Branch: Create a feature branch (git checkout -b feature/xxx).
5. Code: Implement the changes with comprehensive tests
6. Testing: (Golang project) Ensure tests pass (go test ./...) and follow Go code style conventions
7. Documentation: Update documentation to support client-facing changes and use significant commit messages
8. Stage: Stage changes (git add .)
9. Commit: Commit changes (git commit -m "Add feature xxx") ensuring backward compatible code
10. Push: Push to the branch (git push origin feature/xxx).
11. PR: Open a merge request on GitHub (on the GitHub webpage) with detailed description.

Please ensure tests pass and include relevant documentation updates.

---

🌟 Support

Welcome to contribute to this project via submitting merge requests and reporting issues.

Project Support:

• ⭐ Give GitHub stars if this project helps you
• 🤝 Share with teammates and (golang) programming friends
• 📝 Write tech blogs about development tools and workflows - we provide content writing support
• 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene

Have Fun Coding with this package! 🎉🎉🎉

---

GitHub Stars