# README
gg-scm.io/pkg/git
gg-scm.io/pkg/git provides a high-level interface for interacting with a
Git subprocess in Go. It was developed for gg, but this library is
useful for any program that wishes to interact with a Git repository.
gg-scm.io/pkg/git lets your Go program read information from commit history,
create new commits, and do anything else you can do from the Git CLI.
Installation
Inside your Go project, run:
go get gg-scm.io/pkg/git
Usage
// Find the Git executable.
g, err := git.New(git.Options{})
if err != nil {
return err
}
// Write a file and track it with `git add`.
err = ioutil.WriteFile("foo.txt", []byte("Hello, World!\n"), 0666)
if err != nil {
return err
}
err = g.Add(ctx, []git.Pathspec{git.LiteralPath("foo.txt")}, git.AddOptions{})
if err != nil {
return err
}
// Create a new commit.
err = g.Commit(ctx, "Added foo.txt with a greeting", git.CommitOptions{})
if err != nil {
return err
}
See more examples on pkg.go.dev.
This library is tested against Git 2.17.1 and newer. Older versions may work, but are not supported.
Support
If you've found an issue, file it on the issue tracker.
Motivation
As noted in the Git book, shelling out to Git has the benefit
of using the canonical implementation of Git and having all of its features.
However, as the book notes, trying to interact with a Git subprocess requires
"pars[ing] Git's occasionally-changing output format to read progress and result
information, which can be inefficient and error-prone." This package handles all
those details for you. Common operations like git commit or git rev-parse
are wrapped as functions that take in Go data structures as input and return
Go data structures as output. These are methods are tested to be robust over
many different versions of Git under different scenarios. For less common
operations, you can invoke Git with exactly the same command line arguments
you would use interactively and gg-scm.io/pkg/git will handle finding Git and
collecting error messages for you. All Git subprocess invocations can be
logged for easy debugging.
The goals of gg-scm.io/pkg/git are different from those of go-git. go-git
aims to be a reimplementation of Git in pure Go. go-git avoids the dependency
on the Git CLI, but as a result, go-git does not have the same feature set as
upstream Git and introduces the potential for discrepancies in
implementation. gg-scm.io/pkg/git is intended for scenarios where the
fidelity of interactions with Git matters.
Stability
The following packages are stable and we make a reasonable effort to avoid backward-incompatible changes:
gg-scm.io/pkg/gitgg-scm.io/pkg/git/githash
The following packages are relatively new and may still make breaking changes:
gg-scm.io/pkg/git/objectgg-scm.io/pkg/git/packfilegg-scm.io/pkg/git/packfile/client
Because we still have some packages in early development, we have kept the entire repository on major version 0. When all packages are stable, we will start using major version 1.
Contributing
We'd love to accept your patches and contributions to this project. See CONTRIBUTING.md for more details.
If you find this package useful, consider sponsoring @zombiezen, the author and maintainer.