go-git: Git Implementation Library in Pure Go

go-git is a highly extensible Git implementation library written in pure Go. It provides both high-level porcelain operations and low-level plumbing operations for working with Git repositories programmatically.

Overview

Module: github.com/go-git/go-git/v5 Version: 5.16.4 License: Apache-2.0 Language: Go

go-git enables you to:

• Clone, init, and open Git repositories
• Read and write commits, trees, blobs, and tags
• Fetch, pull, and push changes to remotes
• Work with worktrees, staging areas, and checkout branches
• Access low-level Git object storage and references
• Support multiple storage backends (filesystem, memory)
• Use various transport protocols (HTTP, SSH, file, git)

Architecture

The library is organized into several major layers:

1. Porcelain API (High-Level)

The root package github.com/go-git/go-git/v5 provides high-level operations similar to Git command-line tools:

• Repository operations: Clone, Init, Open, PlainClone, PlainOpen
• Worktree operations: Checkout, Add, Commit, Status, Reset
• Remote operations: Fetch, Push, Pull
• Object access: Commits, Trees, Blobs, Tags with iteration

2. Plumbing API (Low-Level)

The plumbing packages provide low-level Git internals:

• Object model: Hash, ObjectType, EncodedObject, Reference
• Storage interfaces: EncodedObjectStorer, ReferenceStorer, Storer
• Object types: Commit, Tree, Blob, Tag (in plumbing/object)
• File formats: Packfile, Index (in plumbing/format)
• Transport protocols: HTTP, SSH, Git protocol (in plumbing/transport)

3. Storage Backends

• Filesystem storage: storage/filesystem - Standard .git directory
• Memory storage: storage/memory - Ephemeral in-memory storage
• Transactional storage: storage/transactional - Transaction support

4. Configuration

The config package handles Git configuration:

• Repository configuration (.git/config)
• Remote configuration
• Branch tracking
• Submodule configuration

Package Organization

The 47 public packages are organized into these major groups:

Core Imports

For most use cases, you'll need these imports:

import (
    "github.com/go-git/go-git/v5"
    "github.com/go-git/go-git/v5/plumbing"
    "github.com/go-git/go-git/v5/plumbing/object"
    "github.com/go-git/go-git/v5/config"
)

For storage backends:

import (
    "github.com/go-git/go-git/v5/storage/memory"
    "github.com/go-git/go-git/v5/storage/filesystem"
    "github.com/go-git/go-billy/v5/memfs"
    "github.com/go-git/go-billy/v5/osfs"
)

For authentication:

import (
    "github.com/go-git/go-git/v5/plumbing/transport/http"
    "github.com/go-git/go-git/v5/plumbing/transport/ssh"
)

Basic Usage Examples

Clone a Repository

package main

import (
    "fmt"
    "github.com/go-git/go-git/v5"
)

func main() {
    // Clone to a local directory
    r, err := git.PlainClone("/tmp/repo", false, &git.CloneOptions{
        URL:      "https://github.com/go-git/go-git",
        Progress: os.Stdout,
    })
    if err != nil {
        panic(err)
    }

    // Get HEAD reference
    ref, err := r.Head()
    if err != nil {
        panic(err)
    }

    // Get the commit object
    commit, err := r.CommitObject(ref.Hash())
    if err != nil {
        panic(err)
    }

    fmt.Println(commit)
}

Open an Existing Repository

package main

import (
    "fmt"
    "github.com/go-git/go-git/v5"
    "github.com/go-git/go-git/v5/plumbing/object"
)

func main() {
    // Open repository
    r, err := git.PlainOpen("/path/to/repo")
    if err != nil {
        panic(err)
    }

    // Get HEAD and commit history
    ref, err := r.Head()
    if err != nil {
        panic(err)
    }

    // Iterate commit history
    cIter, err := r.Log(&git.LogOptions{From: ref.Hash()})
    if err != nil {
        panic(err)
    }

    err = cIter.ForEach(func(c *object.Commit) error {
        fmt.Println(c.Message)
        return nil
    })
    if err != nil {
        panic(err)
    }
}

Make a Commit

package main

import (
    "time"
    "github.com/go-git/go-git/v5"
    "github.com/go-git/go-git/v5/plumbing/object"
)

func main() {
    // Open repository
    r, err := git.PlainOpen("/path/to/repo")
    if err != nil {
        panic(err)
    }

    // Get worktree
    w, err := r.Worktree()
    if err != nil {
        panic(err)
    }

    // Add file to staging area
    _, err = w.Add("README.md")
    if err != nil {
        panic(err)
    }

    // Create commit
    commit, err := w.Commit("Update README", &git.CommitOptions{
        Author: &object.Signature{
            Name:  "John Doe",
            Email: "john@doe.org",
            When:  time.Now(),
        },
    })
    if err != nil {
        panic(err)
    }

    obj, err := r.CommitObject(commit)
    if err != nil {
        panic(err)
    }

    fmt.Println(obj)
}

Clone with Authentication

package main

import (
    "github.com/go-git/go-git/v5"
    "github.com/go-git/go-git/v5/plumbing/transport/http"
)

func main() {
    // Clone with basic auth
    r, err := git.PlainClone("/tmp/repo", false, &git.CloneOptions{
        URL: "https://github.com/private/repo",
        Auth: &http.BasicAuth{
            Username: "username",
            Password: "password_or_token",
        },
    })
    if err != nil {
        panic(err)
    }

    _ = r
}

Capability Areas

The documentation is organized into the following capability areas:

Repository Operations

Learn how to create, open, and clone repositories. Covers:

• Creating new repositories with Init and PlainInit
• Opening existing repositories with Open and PlainOpen
• Cloning remote repositories with Clone and PlainClone
• Repository configuration and options
• Working with bare repositories

Worktree Operations

Work with the working directory and staging area. Covers:

• Getting worktree status
• Adding and removing files
• Creating commits
• Checking out branches and commits
• Resetting worktree state
• Cleaning untracked files

Remote Operations

Interact with remote repositories. Covers:

• Fetching from remotes
• Pushing to remotes
• Pulling changes
• Managing remotes
• Authentication methods
• Progress reporting

Objects

Access Git objects (commits, trees, blobs, tags). Covers:

• Reading and creating commit objects
• Traversing tree objects
• Accessing blob contents
• Working with tag objects
• Iterating through object collections
• Computing patches and diffs

References

Work with Git references (branches, tags, HEAD). Covers:

• Reference types and naming
• Reading and writing references
• Resolving symbolic references
• Listing branches and tags
• Reference iteration
• Hash computation

Storage

Understand storage backends and interfaces. Covers:

• Storage interface design
• Filesystem storage backend
• Memory storage backend
• Transactional storage
• Object and reference storage
• Custom storage implementations

Configuration

Manage repository and global configuration. Covers:

• Reading and writing configuration
• Remote configuration
• Branch configuration
• Submodule configuration
• URL rewriting
• Configuration scopes

Transport

Use different transport protocols and authentication. Covers:

• HTTP/HTTPS transport
• SSH transport
• Git protocol
• File protocol
• Authentication methods
• TLS and proxy configuration

Plumbing

Access low-level Git internals. Covers:

• Packfile reading and writing
• Index (staging area) format
• Object encoding and decoding
• Delta compression
• Protocol capabilities
• Low-level object storage

Common Types

Repository

type Repository struct {
    Storer storage.Storer
    // contains filtered or unexported fields
}

The main entry point for repository operations. Provides methods for accessing objects, references, remotes, and configuration.

Worktree

type Worktree struct {
    Filesystem billy.Filesystem
    Excludes   []gitignore.Pattern
    // contains filtered or unexported fields
}

Represents a working directory. Provides methods for checkout, add, commit, status, and other working directory operations.

Remote

type Remote struct {
    // contains filtered or unexported fields
}

func (r *Remote) Config() *config.RemoteConfig
func (r *Remote) Fetch(o *FetchOptions) error
func (r *Remote) Push(o *PushOptions) error

Represents a remote repository with fetch and push capabilities.

Hash

type Hash [20]byte

func NewHash(s string) Hash
func (h Hash) String() string
func (h Hash) IsZero() bool

Represents a Git object hash (SHA-1 or SHA-256).

Reference

type Reference struct {
    // contains filtered or unexported fields
}

func NewHashReference(name ReferenceName, h Hash) *Reference
func NewSymbolicReference(name, target ReferenceName) *Reference
func (r *Reference) Name() ReferenceName
func (r *Reference) Hash() Hash
func (r *Reference) Type() ReferenceType

Represents a Git reference (branch, tag, or symbolic reference like HEAD).

Error Handling

go-git uses standard Go error handling. Common errors include:

var (
    ErrRepositoryNotExists      = errors.New("repository does not exist")
    ErrRepositoryAlreadyExists  = errors.New("repository already exists")
    ErrRemoteNotFound           = errors.New("remote not found")
    ErrReferenceNotFound        = errors.New("reference not found")
    ErrObjectNotFound           = errors.New("object not found")
    ErrInvalidReference         = errors.New("invalid reference")
    ErrForceNeeded              = errors.New("some refs were not updated")
    NoErrAlreadyUpToDate        = errors.New("already up-to-date")
)

Special note: NoErrAlreadyUpToDate is returned when there's nothing to fetch/pull but is not considered an error condition.

Best Practices

Memory Management

• Use iterators' Close() method to free resources
• For large repositories, consider using filesystem storage with object caching
• Configure LargeObjectThreshold for repositories with large files

Concurrency

• Repository operations are generally not thread-safe
• Use separate Repository instances for concurrent operations
• Consider transactional storage for concurrent writes

Performance

• Use CheckoutOptions.SparseCheckoutDirectories for partial checkouts
• Enable CloneOptions.Depth for shallow clones
• Use LogOptions.PathFilter to filter commit history
• Cache objects with cache.NewObjectLRU()

Error Handling

• Always check errors from operations
• Use errors.Is() to check for specific errors
• Handle NoErrAlreadyUpToDate appropriately in fetch/pull operations

Version Compatibility

go-git v5 requires:

• Go 1.18 or higher
• go-billy v5 (virtual filesystem abstraction)

The library implements Git protocol version 2 and supports:

• Git wire protocol v2
• Pack protocol v2
• Shallow clones
• Reference deltas and OFS deltas
• Packfile index v2

Additional Resources

• GitHub Repository: https://github.com/go-git/go-git
• Go Package Documentation: https://pkg.go.dev/github.com/go-git/go-git/v5
• Examples: https://github.com/go-git/go-git/tree/master/_examples
• Git Internals: https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain

Next Steps

• Explore Repository Operations to learn about creating and opening repositories
• Review Worktree Operations for working with files and commits
• Check Remote Operations for networking and authentication
• Dive into Objects to understand Git's object model