git

package module
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 3, 2024 License: Apache-2.0 Imports: 22 Imported by: 3

README

gg-scm.io/pkg/git

Reference Contributor Covenant

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 = os.WriteFile("foo.txt", []byte("Hello, World!\n"), 0o666)
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/git
  • gg-scm.io/pkg/git/githash

The following packages are relatively new and may still make breaking changes:

  • gg-scm.io/pkg/git/object
  • gg-scm.io/pkg/git/packfile
  • gg-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.

License

Apache 2.0

Documentation

Overview

Package git provides a high-level interface for interacting with a Git subprocess.

Index

Examples

Constants

View Source 
const (
	// Head names the commit on which the changes in the working tree
	// are based.
	Head = githash.Head

	// FetchHead records the branch which was fetched from a remote
	// repository with the last git fetch invocation.
	FetchHead = githash.FetchHead
)

Top-level refs.

Variables

This section is empty.

Functions

func ParseURL added in v0.3.0 

func ParseURL(urlstr string) (*url.URL, error)

ParseURL parses a Git remote URL, including the alternative SCP syntax. See git-fetch(1) for details.

Example 
package main

import (
	"fmt"

	"gg-scm.io/pkg/git"
)

func main() {
	u, err := git.ParseURL("https://github.com/octocat/example")
	if err != nil {
		// handle error
	}
	fmt.Printf("HTTP URL: scheme=%s host=%s path=%s\n", u.Scheme, u.Host, u.Path)

	u, err = git.ParseURL("ssh://git@github.com/octocat/example.git")
	if err != nil {
		// handle error
	}
	fmt.Printf("SSH URL: scheme=%s host=%s user=%s path=%s\n", u.Scheme, u.Host, u.User.Username(), u.Path)

	u, err = git.ParseURL("git@github.com:octocat/example.git")
	if err != nil {
		// handle error
	}
	fmt.Printf("SCP URL: scheme=%s host=%s user=%s path=%s\n", u.Scheme, u.Host, u.User.Username(), u.Path)

}

Output:

HTTP URL: scheme=https host=github.com path=/octocat/example
SSH URL: scheme=ssh host=github.com user=git path=/octocat/example.git
SCP URL: scheme=ssh host=github.com user=git path=/octocat/example.git

func StartPipe added in v0.6.0 

func StartPipe(ctx context.Context, s Runner, invoke *Invocation) (io.ReadCloser, error)

StartPipe starts a piped Git command on r. If r implements Piper, then r.PipeGit is used. Otherwise, StartPipe uses a fallback implementation that calls r.RunGit. invoke.Stdout is ignored.

func URLFromPath added in v0.9.0 

func URLFromPath(path string) *url.URL

URLFromPath converts a filesystem path into a URL. If it's a relative path, then it returns a path-only URL.

Types

type AddOptions 

type AddOptions struct {
	// IncludeIgnored specifies whether to add ignored files.
	// If this is false and an ignored file is explicitly named, then Add
	// will return an error while other matched files are still added.
	IncludeIgnored bool
	// If IntentToAdd is true, then contents of files in the index will
	// not be changed, but any untracked files will have entries added
	// into the index with empty content.
	IntentToAdd bool
}

AddOptions specifies the command-line options for `git add`.

type AmendOptions 

type AmendOptions struct {
	// If Message is not empty, it is the commit message that will be used.
	// Otherwise, the previous commit's message will be used.
	Message string
	// If Author is filled out, then it will be used as the commit author.
	// If Author is blank, then the previous commit's author will be used.
	Author object.User
	// If AuthorTime is not zero, then it will be used as the author time.
	// Otherwise, the previous commit's author time will be used.
	AuthorTime time.Time

	// If Committer is not empty, then it will override the default committer
	// information from Git configuration.
	Committer object.User
	// If CommitTime is not zero, then it will be used as the commit time
	// instead of now.
	CommitTime time.Time

	// If SkipHooks is true, pre-commit and commit-msg hooks will be skipped.
	SkipHooks bool
}

AmendOptions overrides the previous commit's fields.

type BranchOptions 

type BranchOptions struct {
	// StartPoint is a revision to start from. If empty, then HEAD is used.
	StartPoint string
	// If Checkout is true, then HEAD and the working copy will be
	// switched to the new branch.
	Checkout bool
	// If Overwrite is true and a branch with the given name already
	// exists, then it will be reset to the start point. No other branch
	// information is modified, like the upstream.
	Overwrite bool
	// If Track is true and StartPoint names a ref, then the upstream of
	// the branch will be set to the ref named by StartPoint.
	Track bool
}

BranchOptions specifies options for a new branch.

type CheckoutConflictBehavior 

type CheckoutConflictBehavior int

CheckoutConflictBehavior specifies the behavior of checkout with local modifications. 

const (
	// AbortOnFileChange stops the checkout if a file that is modified
	// locally differs between the current HEAD and the target commit.
	// This is the default behavior.
	AbortOnFileChange CheckoutConflictBehavior = iota
	// MergeLocal performs a three-way merge on any differing files.
	MergeLocal
	// DiscardLocal uses the target commit's content regardless of local
	// modifications.
	DiscardLocal
)

Possible checkout behaviors when encountering locally modified files.

func (CheckoutConflictBehavior) String 

func (ccb CheckoutConflictBehavior) String() string

String returns the Go constant name of the behavior.

type CheckoutOptions 

type CheckoutOptions struct {
	// ConflictBehavior specifies the behavior when encountering locally
	// modified files.
	ConflictBehavior CheckoutConflictBehavior
}

CheckoutOptions specifies the command-line options for `git checkout`.

type CloneOptions added in v0.9.0 

type CloneOptions struct {
	// Dir is the path to a directory to clone into. If empty, the final path
	// component of the URL is used, removing any ".git" suffix.
	Dir string

	// Progress receives the stderr of the `git clone` subprocess if not nil.
	Progress io.Writer

	// HeadBranch sets the branch that the new repository's HEAD will point to.
	// If empty, uses the same HEAD as the remote repository.
	HeadBranch string
	// RemoteName sets the name of the new remote. Defaults to "origin" if empty.
	RemoteName string

	// If Depth is greater than zero, it limits the depth of the commits cloned.
	// It is mutually exclusive with Since.
	Depth int
	// Since requests that the shallow clone should be cut at a specific time.
	// It is mutually exclusive with Depth.
	Since time.Time
	// ShallowExclude is a set of revisions that the remote will exclude from
	// the packfile. Unlike Have, the remote will send any needed trees and
	// blobs even if they are shared with the revisions in ShallowExclude.
	// It is mutually exclusive with Depth, but not Since. This is only supported
	// by the remote if it has PullCapShallowExclude.
	ShallowExclude []string
}

CloneOptions specifies the command-line options for `git clone`.

type CommitOptions 

type CommitOptions struct {
	Author     object.User
	AuthorTime time.Time
	Committer  object.User
	CommitTime time.Time

	// If SkipHooks is true, pre-commit and commit-msg hooks will be skipped.
	SkipHooks bool
}

CommitOptions overrides the default metadata for a commit. Any fields with zero values will use the value inferred from Git's environment.

type Config 

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

Config is a collection of configuration settings.

Example 
package main

import (
	"context"
	"fmt"

	"gg-scm.io/pkg/git"
)

func main() {
	ctx := context.Background()

	// Find the Git executable.
	g, err := git.New(git.Options{})
	if err != nil {
		// handle error
	}

	// Read the repository configuration.
	cfg, err := g.ReadConfig(ctx)
	if err != nil {
		// handle error
	}

	// Read a particular configuration value.
	fmt.Println("Hello,", cfg.Value("user.name"))
}

Output:

func (*Config) Bool 

func (cfg *Config) Bool(name string) (bool, error)

Bool returns the boolean configuration setting with the given name.

func (*Config) Color 

func (cfg *Config) Color(name string, default_ string) ([]byte, error)

Color returns the ANSI escape sequence for the given configuration setting.

func (*Config) ColorBool 

func (cfg *Config) ColorBool(name string, isTerm bool) (bool, error)

ColorBool finds the color configuration setting is true or false. isTerm indicates whether the eventual output will be a terminal.

func (*Config) CommentChar 

func (cfg *Config) CommentChar() (string, error)

CommentChar returns the value of the `core.commentChar` setting.

func (*Config) ListRemotes 

func (cfg *Config) ListRemotes() map[string]*Remote

ListRemotes returns the names of all remotes specified in the configuration.

func (*Config) Value 

func (cfg *Config) Value(name string) string

Value returns the string value of the configuration setting with the given name.

type DeleteBranchOptions added in v0.10.0 

type DeleteBranchOptions struct {
	// If Force is true, then the branch will be deleted
	// even if the branch has not been merged
	// or if the branch does not point to a valid commit.
	Force bool
}

DeleteBranchOptions specifies options for a new branch.

type DiffStatusCode 

type DiffStatusCode byte

DiffStatusCode is a single-letter code from the `git diff --name-status` format.

See https://git-scm.com/docs/git-diff#git-diff---diff-filterACDMRTUXB82308203 for a description of each of the codes. 

const (
	DiffStatusAdded       DiffStatusCode = 'A'
	DiffStatusCopied      DiffStatusCode = 'C'
	DiffStatusDeleted     DiffStatusCode = 'D'
	DiffStatusModified    DiffStatusCode = 'M'
	DiffStatusRenamed     DiffStatusCode = 'R'
	DiffStatusChangedMode DiffStatusCode = 'T'
	DiffStatusUnmerged    DiffStatusCode = 'U'
	DiffStatusUnknown     DiffStatusCode = 'X'
	DiffStatusBroken      DiffStatusCode = 'B'
)

Diff status codes.

func (DiffStatusCode) String 

func (code DiffStatusCode) String() string

String returns the code letter as a string.

type DiffStatusEntry 

type DiffStatusEntry struct {
	Code DiffStatusCode
	Name TopPath
}

A DiffStatusEntry describes the state of a single file in a diff.

type DiffStatusOptions 

type DiffStatusOptions struct {
	// Commit1 specifies the earlier commit to compare with. If empty,
	// then DiffStatus compares against the index.
	Commit1 string
	// Commit2 specifies the later commit to compare with. If empty, then
	// DiffStatus compares against the working tree. Callers must not set
	// Commit2 if Commit1 is empty.
	Commit2 string
	// Pathspecs filters the output to the given pathspecs.
	Pathspecs []Pathspec
	// DisableRenames will force Git to disable rename/copy detection.
	DisableRenames bool
}

DiffStatusOptions specifies the command-line arguments for `git diff --status`.

type FetchRefspec 

type FetchRefspec string

A FetchRefspec specifies a mapping from remote refs to local refs.

func (FetchRefspec) Map 

func (spec FetchRefspec) Map(remote Ref) Ref

Map maps a remote ref into a local ref. If there is no mapping, then Map returns an empty Ref.

func (FetchRefspec) Parse 

func (spec FetchRefspec) Parse() (src, dst RefPattern, plus bool)

Parse parses the refspec into its parts.

func (FetchRefspec) String 

func (spec FetchRefspec) String() string

String returns the refspec as a string.

type FileSystem added in v0.6.0 

type FileSystem interface {
	// Join joins any number of path elements into a single path.
	// Empty elements are ignored. The result must be Cleaned.
	// However, if the argument list is empty or all its elements are
	// empty, Join returns an empty string.
	Join(elem ...string) string

	// Clean returns the shortest path name equivalent to path by purely
	// lexical processing.
	Clean(path string) string

	// IsAbs reports whether the path is absolute.
	IsAbs(path string) bool

	// EvalSymlinks returns the path name after the evaluation of any
	// symbolic links. The path argument will always be absolute.
	EvalSymlinks(path string) (string, error)
}

A FileSystem manipulates paths for a possibly remote filesystem. The methods of a FileSystem must be safe to call concurrently.

type Git 

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

Git is a context for performing Git version control operations.

func Custom added in v0.6.0 

func Custom(dir string, s Runner, fs FileSystem) *Git

Custom creates a new Git context from the given Runner and FileSystem. It panics if the Runner is nil, the FileSystem is nil, or dir is not absolute. If the Runner also implements Piper, then its GitPipe method will be used for any large streaming operations.

func New 

func New(opts Options) (*Git, error)

New creates a new Git context that communicates with a local Git subprocess. It is equivalent to passing the result of NewLocal to Custom.

func (*Git) AbortMerge 

func (g *Git) AbortMerge(ctx context.Context) error

AbortMerge aborts the current conflict resolution process and tries to reconstruct pre-merge state.

func (*Git) Add 

func (g *Git) Add(ctx context.Context, pathspecs []Pathspec, opts AddOptions) error

Add adds file contents to the index. If len(pathspecs) == 0, then Add returns nil.

func (*Git) Amend 

func (g *Git) Amend(ctx context.Context, opts AmendOptions) error

Amend replaces the tip of the current branch with a new commit with the content of the index.

func (*Git) AmendAll 

func (g *Git) AmendAll(ctx context.Context, opts AmendOptions) error

AmendAll replaces the tip of the current branch with a new commit with the content of the working copy for all tracked files.

func (*Git) AmendFiles 

func (g *Git) AmendFiles(ctx context.Context, pathspecs []Pathspec, opts AmendOptions) error

AmendFiles replaces the tip of the current branch with a new commit with the content of the named files from the working copy. Files not named will get their content from the previous commit.

Notably, AmendFiles with no paths will not change the file content of the commit, just the options specified.

func (*Git) Cat 

func (g *Git) Cat(ctx context.Context, rev string, path TopPath) (io.ReadCloser, error)

Cat reads the content of a file at a particular revision. It is the caller's responsibility to close the returned io.ReadCloser if the returned error is nil.

func (*Git) CheckoutBranch 

func (g *Git) CheckoutBranch(ctx context.Context, branch string, opts CheckoutOptions) error

CheckoutBranch switches HEAD to another branch and updates the working copy to match. If the branch does not exist, then CheckoutBranch returns an error.

func (*Git) CheckoutRev 

func (g *Git) CheckoutRev(ctx context.Context, rev string, opts CheckoutOptions) error

CheckoutRev switches HEAD to a specific commit and updates the working copy to match. It will always put the worktree in "detached HEAD" state.

func (*Git) Clone added in v0.9.0 

func (g *Git) Clone(ctx context.Context, u *url.URL, opts CloneOptions) error

Clone clones the repository at the given URL and checks out HEAD.

func (*Git) CloneBare added in v0.9.0 

func (g *Git) CloneBare(ctx context.Context, u *url.URL, opts CloneOptions) error

CloneBare clones the repository at the given URL without creating a working copy.

func (*Git) Commit 

func (g *Git) Commit(ctx context.Context, message string, opts CommitOptions) error

Commit creates a new commit on HEAD with the staged content. The message will be used exactly as given.

Example 
package main

import (
	"context"

	"os"

	"gg-scm.io/pkg/git"
)

func main() {
	ctx := context.Background()

	// Find the Git executable.
	g, err := git.New(git.Options{})
	if err != nil {
		// handle error
	}

	// Write a file and track it with `git add`.
	err = os.WriteFile("foo.txt", []byte("Hello, World!\n"), 0o666)
	if err != nil {
		// handle error
	}
	err = g.Add(ctx, []git.Pathspec{git.LiteralPath("foo.txt")}, git.AddOptions{})
	if err != nil {
		// handle error
	}

	// Create a new commit.
	err = g.Commit(ctx, "Added foo.txt with a greeting", git.CommitOptions{})
	if err != nil {
		// handle error
	}
}

Output:

func (*Git) CommitAll 

func (g *Git) CommitAll(ctx context.Context, message string, opts CommitOptions) error

CommitAll creates a new commit on HEAD with all of the tracked files. The message will be used exactly as given.

func (*Git) CommitFiles 

func (g *Git) CommitFiles(ctx context.Context, message string, pathspecs []Pathspec, opts CommitOptions) error

CommitFiles creates a new commit on HEAD that updates the given files to the content in the working copy. The message will be used exactly as given.

func (*Git) CommitInfo 

func (g *Git) CommitInfo(ctx context.Context, rev string) (*object.Commit, error)

CommitInfo obtains information about a single commit.

func (*Git) CommonDir 

func (g *Git) CommonDir(ctx context.Context) (string, error)

CommonDir determines the absolute path of the Git directory, possibly shared among different working trees, given the configuration. Any symlinks are resolved.

func (*Git) DeleteBranches added in v0.10.0 

func (g *Git) DeleteBranches(ctx context.Context, names []string, opts DeleteBranchOptions) error

DeleteBranches deletes zero or more branches. If names is empty, then DeleteBranches returns nil without running Git.

func (*Git) DiffStatus 

func (g *Git) DiffStatus(ctx context.Context, opts DiffStatusOptions) ([]DiffStatusEntry, error)

DiffStatus compares the working copy with a commit using `git diff --name-status`.

See https://git-scm.com/docs/git-diff#git-diff---name-status for more details.

func (*Git) Exe deprecated added in v0.4.0 

func (g *Git) Exe() string

Exe returns the absolute path to the Git executable. This method will panic if g's Runner is not of type *Local.

Deprecated: Call *Local.Exe() before calling Custom.

func (*Git) FileSystem added in v0.6.0 

func (g *Git) FileSystem() FileSystem

FileSystem returns the context's filesystem.

func (*Git) GitDir 

func (g *Git) GitDir(ctx context.Context) (string, error)

GitDir determines the absolute path of the Git directory for this working tree given the configuration. Any symlinks are resolved.

func (*Git) Head 

func (g *Git) Head(ctx context.Context) (*Rev, error)

Head returns the working copy's branch revision. If the branch does not point to a valid commit (such as when the repository is first created), then Head returns an error.

Example 
package main

import (
	"context"
	"fmt"

	"gg-scm.io/pkg/git"
)

func main() {
	ctx := context.Background()

	// Find the Git executable.
	g, err := git.New(git.Options{})
	if err != nil {
		// handle error
	}

	// Print currently checked out revision.
	rev, err := g.Head(ctx)
	if err != nil {
		// handle error
	}
	fmt.Println(rev.Commit.Short())
}

Output:

func (*Git) HeadRef 

func (g *Git) HeadRef(ctx context.Context) (Ref, error)

HeadRef returns the working copy's branch. If the working copy is in detached HEAD state, then HeadRef returns an empty string and no error. The ref may not point to a valid commit.

Example 
package main

import (
	"context"
	"fmt"

	"gg-scm.io/pkg/git"
)

func main() {
	ctx := context.Background()

	// Find the Git executable.
	g, err := git.New(git.Options{})
	if err != nil {
		// handle error
	}

	// Print currently checked out branch.
	ref, err := g.HeadRef(ctx)
	if err != nil {
		// handle error
	}
	if ref == "" {
		fmt.Println("detached HEAD")
	} else {
		fmt.Println(ref.Branch())
	}
}

Output:

func (*Git) Init 

func (g *Git) Init(ctx context.Context, dir string) error

Init ensures a repository exists at the given path. Any relative paths are interpreted relative to the Git process's working directory. If any of the repository's parent directories don't exist, they will be created.

func (*Git) InitBare 

func (g *Git) InitBare(ctx context.Context, dir string) error

InitBare ensures a bare repository exists at the given path. Any relative paths are interpreted relative to the Git process's working directory. If any of the repository's parent directories don't exist, they will be created.

func (*Git) IsAncestor 

func (g *Git) IsAncestor(ctx context.Context, rev1, rev2 string) (bool, error)

IsAncestor reports whether rev1 is an ancestor of rev2. If rev1 == rev2, then IsAncestor returns true.

func (*Git) IsMerging 

func (g *Git) IsMerging(ctx context.Context) (bool, error)

IsMerging reports whether the index has a pending merge commit.

func (*Git) IterateRefs added in v0.11.0 

func (g *Git) IterateRefs(ctx context.Context, opts IterateRefsOptions) *RefIterator

IterateRefs starts listing all of the refs in the repository.

func (*Git) IterateRemoteRefs added in v0.11.0 

func (g *Git) IterateRemoteRefs(ctx context.Context, remote string, opts IterateRemoteRefsOptions) *RefIterator

IterateRemoteRefs starts listing all of the refs in a remote repository. remote may be a URL or the name of a remote.

The iterator may block on user input if the remote requires credentials.

func (*Git) ListRefs deprecated 

func (g *Git) ListRefs(ctx context.Context) (map[Ref]Hash, error)

ListRefs lists all of the refs in the repository with tags dereferenced.

Deprecated: This method will return an error on repositories with many branches (>100K). Use Git.IterateRefs instead.

func (*Git) ListRefsVerbatim deprecated 

func (g *Git) ListRefsVerbatim(ctx context.Context) (map[Ref]Hash, error)

ListRefsVerbatim lists all of the refs in the repository. Tags will not be dereferenced.

Deprecated: This method will return an error on repositories with many branches (>100K). Use Git.IterateRefs instead.

func (*Git) ListRemoteRefs deprecated 

func (g *Git) ListRemoteRefs(ctx context.Context, remote string) (map[Ref]Hash, error)

ListRemoteRefs lists all of the refs in a remote repository. remote may be a URL or the name of a remote.

This function may block on user input if the remote requires credentials.

Deprecated: This method will return an error on repositories with many branches (>100K). Use Git.IterateRemoteRefs instead.

func (*Git) ListSubmodules added in v0.2.0 

func (g *Git) ListSubmodules(ctx context.Context) (map[string]*SubmoduleConfig, error)

ListSubmodules lists the submodules of the repository based on the configuration in the working copy.

func (*Git) ListTree 

func (g *Git) ListTree(ctx context.Context, rev string, opts ListTreeOptions) (map[TopPath]*TreeEntry, error)

ListTree returns the list of files at a given revision.

func (*Git) Log 

func (g *Git) Log(ctx context.Context, opts LogOptions) (_ *Log, err error)

Log starts fetching information about a set of commits. The context's deadline and cancelation will apply to the entire read from the Log.

func (*Git) Merge 

func (g *Git) Merge(ctx context.Context, revs []string) error

Merge merges changes from the named revisions into the index and the working copy. It updates MERGE_HEAD but does not create a commit. Merge will never perform a fast-forward merge.

In case of conflict, Merge will return an error but still update MERGE_HEAD. To check for this condition, call IsMerging after receiving an error from Merge (verifying that IsMerging returned false before calling Merge).

func (*Git) MergeBase 

func (g *Git) MergeBase(ctx context.Context, rev1, rev2 string) (Hash, error)

MergeBase returns the best common ancestor between two commits to use in a three-way merge.

func (*Git) MutateRefs 

func (g *Git) MutateRefs(ctx context.Context, muts map[Ref]RefMutation) error

MutateRefs atomically modifies zero or more refs. If there are no non-zero mutations, then MutateRefs returns nil without running Git.

func (*Git) NewBranch 

func (g *Git) NewBranch(ctx context.Context, name string, opts BranchOptions) error

NewBranch creates a new branch, a ref of the form "refs/heads/NAME", where NAME is the name argument.

func (*Git) NullTreeHash 

func (g *Git) NullTreeHash(ctx context.Context) (Hash, error)

NullTreeHash computes the hash of an empty tree and adds it to the repository. This is sometimes useful as a diff comparison target.

func (*Git) Output 

func (g *Git) Output(ctx context.Context, args ...string) (string, error)

Output runs Git with the given arguments and returns its stdout.

func (*Git) ParseRev 

func (g *Git) ParseRev(ctx context.Context, refspec string) (*Rev, error)

ParseRev parses a revision.

Example 
package main

import (
	"context"
	"fmt"

	"gg-scm.io/pkg/git"
)

func main() {
	ctx := context.Background()

	// Find the Git executable.
	g, err := git.New(git.Options{})
	if err != nil {
		// handle error
	}

	// Convert a revision reference into a commit hash.
	rev, err := g.ParseRev(ctx, "v0.1.0")
	if err != nil {
		// handle error
	}
	// Print something like: refs/tags/v0.1.0 - 09f2632a
	fmt.Printf("%s - %s\n", rev.Ref, rev.Commit.Short())
}

Output:

func (*Git) ReadConfig 

func (g *Git) ReadConfig(ctx context.Context) (*Config, error)

ReadConfig reads all the configuration settings from Git.

func (*Git) Remove 

func (g *Git) Remove(ctx context.Context, pathspecs []Pathspec, opts RemoveOptions) error

Remove removes file contents from the index.

func (*Git) Run 

func (g *Git) Run(ctx context.Context, args ...string) error

Run runs Git with the given arguments. If an error occurs, the combined stdout and stderr will be returned in the error.

func (*Git) Runner added in v0.6.0 

func (g *Git) Runner() Runner

Runner returns the context's Git runner.

func (*Git) StageTracked 

func (g *Git) StageTracked(ctx context.Context) error

StageTracked updates the index to match the tracked files in the working copy.

func (*Git) Status 

func (g *Git) Status(ctx context.Context, opts StatusOptions) ([]StatusEntry, error)

Status returns any differences the working copy has from the files at HEAD.

func (*Git) WithDir 

func (g *Git) WithDir(dir string) *Git

WithDir returns a new instance that is changed to use dir as its working directory. Any relative paths will be interpreted relative to g's working directory.

func (*Git) WorkTree 

func (g *Git) WorkTree(ctx context.Context) (string, error)

WorkTree determines the absolute path of the root of the current working tree given the configuration. Any symlinks are resolved.

type Hash 

type Hash = githash.SHA1

A Hash is the SHA-1 hash of a Git object.

func ParseHash 

func ParseHash(s string) (Hash, error)

ParseHash parses a hex-encoded hash. It is the same as calling UnmarshalText on a new Hash.

type Invocation added in v0.6.0 

type Invocation struct {
	// Args is the list of arguments to Git. It does not include a leading "git"
	// argument.
	Args []string

	// Dir is an absolute directory. It's the only required field in the struct.
	Dir string

	// Env specifies additional environment variables to the Git process.
	// Each entry is of the form "key=value".
	// If Env contains duplicate environment keys, only the last
	// value in the slice for each duplicate key is used.
	// The Runner may send additional environment variables to the
	// Git process.
	Env []string

	// Stdin specifies the Git process's standard input.
	//
	// If Stdin is nil, the process reads from the null device.
	//
	// The io.Closer returned from the Runner must not return until the
	// end of Stdin is reached (any read error).
	Stdin io.Reader

	// Stdout and Stderr specify the Git process's standard output and error.
	//
	// If either is nil, Run connects the corresponding file descriptor
	// to the null device.
	//
	// The io.Closer returned from the Runner must not return until the
	// all the data is written to the respective Writers.
	//
	// If Stdout and Stderr are the same writer, and have a type that can
	// be compared with ==, at most one goroutine at a time will call Write.
	Stdout io.Writer
	Stderr io.Writer
}

Invocation holds the parameters for a Git process.

type IterateRefsOptions added in v0.11.0 

type IterateRefsOptions struct {
	// If IncludeHead is true, the HEAD ref is included
	// regardless of the other options.
	IncludeHead bool
	// LimitToBranches limits the refs to those starting with "refs/heads/".
	// This is additive with IncludeHead and LimitToTags.
	LimitToBranches bool
	// LimitToTags limits the refs to those starting with "refs/tags/".
	// This is additive with IncludeHead and LimitToBranches.
	LimitToTags bool
	// If DereferenceTags is true,
	// then the iterator will also produce refs for which [RefIterator.IsDereference] reports true
	// that have the object hash of the tag object refers to.
	DereferenceTags bool
}

IterateRefsOptions specifies filters for Git.IterateRefs.

type IterateRemoteRefsOptions added in v0.11.0 

type IterateRemoteRefsOptions struct {
	// If IncludeHead is true, the HEAD ref is included,
	// regardless of the other options.
	IncludeHead bool
	// LimitToBranches limits the refs to those starting with "refs/heads/".
	// This is additive with IncludeHead and LimitToTags.
	LimitToBranches bool
	// LimitToTags limits the refs to those starting with "refs/tags/".
	// This is additive with IncludeHead and LimitToBranches.
	LimitToTags bool
	// If DereferenceTags is true,
	// then the iterator will also produce refs for which [RefIterator.IsDereference] reports true
	// that have the object hash of the tag object refers to.
	DereferenceTags bool
}

IterateRemoteRefsOptions specifies filters for Git.IterateRemoteRefs.

type ListTreeOptions added in v0.2.0 

type ListTreeOptions struct {
	// If Pathspecs is not empty, then it is used to filter the paths.
	Pathspecs []Pathspec
	// If Recursive is true, then the command will recurse into sub-trees.
	Recursive bool
	// If NameOnly is true, then only the keys of the map returned from ListTree
	// will be populated (the values will be nil). This can be more efficient if
	// information beyond the name is not needed.
	NameOnly bool
}

ListTreeOptions specifies the command-line options for `git ls-tree`.

type Local added in v0.6.0 

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

Local implements Runner by starting Git subprocesses.

func NewLocal added in v0.6.0 

func NewLocal(opts Options) (*Local, error)

NewLocal returns a new local runner with the given options. Dir is ignored.

func (*Local) Clean added in v0.6.0 

func (l *Local) Clean(path string) string

Clean calls path/filepath.Clean. 

func (l *Local) EvalSymlinks(path string) (string, error)

EvalSymlinks calls path/filepath.EvalSymlinks.

func (*Local) Exe added in v0.6.0 

func (l *Local) Exe() string

Exe returns the absolute path to the Git executable.

func (*Local) IsAbs added in v0.6.0 

func (l *Local) IsAbs(path string) bool

IsAbs calls path/filepath.IsAbs.

func (*Local) Join added in v0.6.0 

func (l *Local) Join(elem ...string) string

Join calls path/filepath.Join.

func (*Local) PipeGit added in v0.6.0 

func (l *Local) PipeGit(ctx context.Context, invoke *Invocation) (io.ReadCloser, error)

PipeGit starts a Git subprocess with its standard output connected to an OS pipe. If the Context is cancelled or its deadline is exceeded, PipeGit will send SIGTERM to the subprocess.

func (*Local) RunGit added in v0.6.0 

func (l *Local) RunGit(ctx context.Context, invoke *Invocation) error

RunGit runs Git in a subprocess. If the Context is cancelled or its deadline is exceeded, RunGit will send SIGTERM to the subprocess.

type Log 

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

Log is an open handle to a `git cat-file --batch` subprocess. Closing the Log stops the subprocess.

func (*Log) Close 

func (l *Log) Close() error

Close ends the log subprocess and waits for it to finish. Close returns an error if Log.Next returned false due to a parse failure. Subsequent calls to Close will no-op and return the same error.

func (*Log) CommitInfo 

func (l *Log) CommitInfo() *object.Commit

CommitInfo returns the most recently scanned log entry. Next must be called at least once before calling CommitInfo.

func (*Log) Next 

func (l *Log) Next() bool

Next attempts to scan the next log entry and returns whether there is a new entry.

type LogOptions 

type LogOptions struct {
	// Revs specifies the set of commits to list. When empty, it defaults
	// to all commits reachable from HEAD.
	Revs []string

	// MaxParents sets an inclusive upper limit on the number of parents
	// on revisions to return from Log. If MaxParents is zero, then it is
	// treated as no limit unless AllowZeroMaxParents is true.
	MaxParents          int
	AllowZeroMaxParents bool

	// If FirstParent is true, then follow only the first parent commit
	// upon seeing a merge commit.
	FirstParent bool

	// Limit specifies the upper bound on the number of revisions to return from Log.
	// Zero means no limit.
	Limit int

	// If Reverse is true, then commits will be returned in reverse order.
	Reverse bool

	// If NoWalk is true, then ancestor commits are not traversed. Does not have
	// an effect if Revs contains a range.
	NoWalk bool
}

LogOptions specifies filters and ordering on a log listing.

type Options 

type Options struct {
	// Dir is the working directory to run the Git subprocess from.
	// If empty, uses this process's working directory.
	// NewLocal ignores this field.
	Dir string

	// Env specifies the environment of the subprocess.
	// If Env == nil, then the process's environment will be used.
	Env []string

	// GitExe is the name of or a path to a Git executable.
	// It is treated in the same manner as the argument to exec.LookPath.
	// An empty string is treated the same as "git".
	GitExe string

	// LogHook is a function that will be called at the start of every Git
	// subprocess.
	LogHook func(ctx context.Context, args []string)
}

Options holds the parameters for New and NewLocal.

type Pathspec 

type Pathspec string

A Pathspec is a Git path pattern. It will be passed through literally to Git. 

const NoPathspec Pathspec = ":"

NoPathspec is the special "there is no pathspec" form. If present, it should be the only pathspec in a list of pathspecs.

func JoinPathspecMagic 

func JoinPathspecMagic(magic PathspecMagic, pattern string) Pathspec

JoinPathspecMagic combines a set of magic options and a pattern into a pathspec.

func LiteralPath 

func LiteralPath(p string) Pathspec

LiteralPath escapes a string from any special characters.

func (Pathspec) SplitMagic 

func (p Pathspec) SplitMagic() (PathspecMagic, string)

SplitMagic splits the pathspec into the magic signature and the pattern. Unrecognized options are ignored, so this is a lossy operation.

func (Pathspec) String 

func (p Pathspec) String() string

String returns the pathspec as a string.

type PathspecMagic 

type PathspecMagic struct {
	Top                   bool
	Literal               bool
	CaseInsensitive       bool
	Glob                  bool
	AttributeRequirements []string
	Exclude               bool
}

PathspecMagic specifies all the "magic" pathspec options. See pathspec under gitglossary(7) for more details.

func (PathspecMagic) IsZero 

func (magic PathspecMagic) IsZero() bool

IsZero reports whether all the fields are unset.

func (PathspecMagic) String 

func (magic PathspecMagic) String() string

String returns the magic in long form like ":(top,literal)". The zero value returns ":()".

type Piper added in v0.6.0 

type Piper interface {
	Runner
	PipeGit(ctx context.Context, invoke *Invocation) (pipe io.ReadCloser, err error)
}

A Piper is an optional interface that a Runner can implement for more efficient streaming of long-running outputs.

PipeGit starts a Git process with its standard output connected to a pipe. It ignores the Stdout field of the Invocation. PipeGit must be safe to call concurrently with other calls to PipeGit and RunGit.

The returned pipe's Close method closes the pipe and then waits for the Git process to finish before returning. It is the caller's responsibility to call the Close method.

type Ref 

type Ref = githash.Ref

A Ref is a Git reference to a commit.

func BranchRef 

func BranchRef(b string) Ref

BranchRef returns a ref for the given branch name.

func TagRef 

func TagRef(t string) Ref

TagRef returns a ref for the given tag name.

type RefIterator added in v0.11.0 

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

RefIterator is an open handle to a Git subprocess that lists refs. Closing the iterator stops the subprocess.

func (*RefIterator) Close added in v0.11.0 

func (iter *RefIterator) Close() error

Close ends the Git subprocess and waits for it to finish. Close returns an error if RefIterator.Next returned false due to a parse failure. Subsequent calls to Close will no-op and return the same error.

func (*RefIterator) IsDereference added in v0.11.0 

func (iter *RefIterator) IsDereference() bool

IsDereference reports whether the value of RefIterator.ObjectSHA1 represents the target of a tag object.

func (*RefIterator) Next added in v0.11.0 

func (iter *RefIterator) Next() bool

Next attempts to scan the next ref and reports whether one exists.

func (*RefIterator) ObjectSHA1 added in v0.11.0 

func (iter *RefIterator) ObjectSHA1() githash.SHA1

ObjectSHA1 returns the SHA-1 hash of the Git object the current ref refers to. RefIterator.Next must be called at least once before calling ObjectSHA1.

func (*RefIterator) Ref added in v0.11.0 

func (iter *RefIterator) Ref() Ref

Ref returns the current ref. RefIterator.Next must be called at least once before calling Ref.

type RefMutation 

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

A RefMutation describes an operation to perform on a ref. The zero value is a no-op.

func CreateRef added in v0.10.0 

func CreateRef(newvalue string) RefMutation

CreateRef returns a RefMutation that creates a ref with the given value, failing if the ref already exists.

func DeleteRef 

func DeleteRef() RefMutation

DeleteRef returns a RefMutation that unconditionally deletes a ref.

func DeleteRefIfMatches 

func DeleteRefIfMatches(oldvalue string) RefMutation

DeleteRefIfMatches returns a RefMutation that attempts to delete a ref, but fails if it has the given value.

func SetRef added in v0.10.0 

func SetRef(newvalue string) RefMutation

SetRef returns a RefMutation that unconditionally sets a ref to the given value. The ref does not need to have previously existed.

func SetRefIfMatches added in v0.10.0 

func SetRefIfMatches(oldvalue, newvalue string) RefMutation

SetRefIfMatches returns a RefMutation that sets a ref to newvalue, failing if the ref does not have the given oldvalue.

func (RefMutation) IsNoop added in v0.10.0 

func (mut RefMutation) IsNoop() bool

IsNoop reports whether mut is a no-op.

func (RefMutation) String 

func (mut RefMutation) String() string

String returns the mutation in a form similar to a line of input to `git update-ref --stdin`.

type RefPattern 

type RefPattern string

A RefPattern is a part of a refspec. It may be either a literal suffix match (e.g. "main" matches "refs/head/main"), or the last component may be a wildcard ('*'), which indicates a prefix match.

func (RefPattern) Match 

func (pat RefPattern) Match(ref Ref) (suffix string, ok bool)

Match reports whether a ref matches the pattern. If the pattern is a prefix match, then suffix is the string matched by the wildcard.

func (RefPattern) Prefix 

func (pat RefPattern) Prefix() (_ string, ok bool)

Prefix returns the prefix before the wildcard if it's a wildcard pattern. Otherwise it returns "", false.

func (RefPattern) String 

func (pat RefPattern) String() string

String returns the pattern string.

type Remote 

type Remote struct {
	Name     string
	FetchURL string
	Fetch    []FetchRefspec
	PushURL  string
}

Remote stores the configuration for a remote repository.

Example 
package main

import (
	"context"
	"fmt"

	"gg-scm.io/pkg/git"
)

func main() {
	ctx := context.Background()

	// Find the Git executable.
	g, err := git.New(git.Options{})
	if err != nil {
		// handle error
	}

	// Read the repository configuration.
	cfg, err := g.ReadConfig(ctx)
	if err != nil {
		// handle error
	}

	// Get details about a particular remote.
	remotes := cfg.ListRemotes()
	origin := remotes["origin"]
	if origin == nil {
		fmt.Println("No origin remote")
	} else {
		fmt.Println("Fetching from", origin.FetchURL)
	}
}

Output:

func (*Remote) MapFetch 

func (r *Remote) MapFetch(remote Ref) Ref

MapFetch maps a remote fetch ref into a local ref. If there is no mapping, then MapFetch returns an empty Ref.

func (*Remote) String 

func (r *Remote) String() string

String returns the remote's name.

type RemoveOptions 

type RemoveOptions struct {
	// Recursive specifies whether to remove directories.
	Recursive bool
	// If Modified is true, then files will be deleted even if they've
	// been modified from their checked in state.
	Modified bool
	// If KeepWorkingCopy is true, then the file will only be removed in
	// the index, not the working copy.
	KeepWorkingCopy bool
}

RemoveOptions specifies the command-line options for `git add`.

type Rev 

type Rev struct {
	Commit Hash
	Ref    Ref
}

Rev is a parsed reference to a single commit.

func (*Rev) String 

func (r *Rev) String() string

String returns the shortest symbolic name if possible, falling back to the commit hash.

type Runner added in v0.6.0 

type Runner interface {
	RunGit(ctx context.Context, invoke *Invocation) error
}

A Runner executes Git processes.

RunGit starts a Git process with the given parameters and waits until the process is finished. It must not modify the Invocation. RunGit must be safe to call concurrently with other calls to RunGit.

If the Git process exited with a non-zero exit code, there should be an error in its Unwrap chain that has an `ExitCode() int` method.

type StatusCode 

type StatusCode [2]byte

A StatusCode is a two-letter code from the `git status` short format. For paths with no merge conflicts, the first letter is the status of the index and the second letter is the status of the work tree.

More details at https://git-scm.com/docs/git-status#_short_format

func (StatusCode) IsAdded 

func (code StatusCode) IsAdded() bool

IsAdded reports whether the file is new to the index (including copies, but not renames).

func (StatusCode) IsCopied 

func (code StatusCode) IsCopied() bool

IsCopied reports whether the file has been copied from elsewhere.

func (StatusCode) IsIgnored 

func (code StatusCode) IsIgnored() bool

IsIgnored returns true if the file is being ignored by Git.

func (StatusCode) IsMissing 

func (code StatusCode) IsMissing() bool

IsMissing reports whether the file has been deleted in the work tree.

func (StatusCode) IsModified 

func (code StatusCode) IsModified() bool

IsModified reports whether the file has been modified in either the index or the work tree.

func (StatusCode) IsOriginalMissing 

func (code StatusCode) IsOriginalMissing() bool

IsOriginalMissing reports whether the file has been detected as a rename in the work tree, but neither this file or its original have been updated in the index. If IsOriginalMissing is true, then IsAdded returns true.

func (StatusCode) IsRemoved 

func (code StatusCode) IsRemoved() bool

IsRemoved reports whether the file has been deleted in the index.

func (StatusCode) IsRenamed 

func (code StatusCode) IsRenamed() bool

IsRenamed reports whether the file is the result of a rename.

func (StatusCode) IsUnmerged 

func (code StatusCode) IsUnmerged() bool

IsUnmerged reports whether the file has unresolved merge conflicts.

func (StatusCode) IsUntracked 

func (code StatusCode) IsUntracked() bool

IsUntracked returns true if the file is not being tracked by Git.

func (StatusCode) String 

func (code StatusCode) String() string

String returns the code's bytes as a string.

type StatusEntry 

type StatusEntry struct {
	// Code is the two-letter code from the Git status short format.
	// More details in the Output section of git-status(1).
	Code StatusCode
	// Name is the path of the file.
	Name TopPath
	// From is the path of the file that this file was renamed or
	// copied from, otherwise an empty string.
	From TopPath
}

A StatusEntry describes the state of a single file in the working copy.

func (StatusEntry) String 

func (ent StatusEntry) String() string

String returns the entry in short format.

type StatusOptions 

type StatusOptions struct {
	// IncludeIgnored specifies whether to emit ignored files.
	IncludeIgnored bool
	// DisableRenames will force Git to disable rename/copy detection.
	DisableRenames bool
	// Pathspecs filters the output to the given pathspecs.
	Pathspecs []Pathspec
}

StatusOptions specifies the command-line arguments for `git status`.

type SubmoduleConfig added in v0.2.0 

type SubmoduleConfig struct {
	Path TopPath
	URL  string
}

A SubmoduleConfig represents a single section in a gitmodules file.

type TopPath 

type TopPath string

A TopPath is a slash-separated path relative to the top level of the repository.

func (TopPath) Pathspec 

func (tp TopPath) Pathspec() Pathspec

Pathspec converts a top-level path to a pathspec.

func (TopPath) String 

func (tp TopPath) String() string

String returns the path as a string.

type TreeEntry added in v0.2.0 

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

TreeEntry represents a single entry in a Git tree object. It implements fs.FileInfo.

func (*TreeEntry) IsDir added in v0.2.0 

func (ent *TreeEntry) IsDir() bool

IsDir reports whether the file mode indicates a directory.

func (*TreeEntry) ModTime added in v0.2.0 

func (ent *TreeEntry) ModTime() time.Time

ModTime returns the zero time. It exists purely to satisfy the fs.FileInfo interface.

func (*TreeEntry) Mode added in v0.2.0 

func (ent *TreeEntry) Mode() fs.FileMode

Mode returns the file mode bits.

func (*TreeEntry) Name added in v0.2.0 

func (ent *TreeEntry) Name() string

Name returns the base name of the file.

func (*TreeEntry) Object added in v0.2.0 

func (ent *TreeEntry) Object() Hash

Object returns the hash of the file's Git object.

func (*TreeEntry) ObjectType added in v0.2.0 

func (ent *TreeEntry) ObjectType() object.Type

ObjectType returns the file's Git object type.

func (*TreeEntry) Path added in v0.2.0 

func (ent *TreeEntry) Path() TopPath

Path returns the file's path relative to the root of the repository.

func (*TreeEntry) Size added in v0.2.0 

func (ent *TreeEntry) Size() int64

Size returns the length in bytes for blobs.

func (*TreeEntry) String added in v0.2.0 

func (ent *TreeEntry) String() string

String formats the entry similar to `git ls-tree` output.

func (*TreeEntry) Sys added in v0.2.0 

func (ent *TreeEntry) Sys() interface{}

Sys returns nil. It exists purely to satisfy the fs.FileInfo interface.

Source Files

View all Source files

Directories

Path Synopsis
Package githash provides types for Git object identifiers.
 Package githash provides types for Git object identifiers.
internal
filesystem
Package filesystem provides concise data structures for filesystem operations and functions to apply them to local files.
 Package filesystem provides concise data structures for filesystem operations and functions to apply them to local files.
giturl
pktline
Package pktline reads and writes the pkt-line format described in https://git-scm.com/docs/protocol-common#_pkt_line_format.
 Package pktline reads and writes the pkt-line format described in https://git-scm.com/docs/protocol-common#_pkt_line_format.
sigterm
Package sigterm provides graceful termination signal utilities.
 Package sigterm provides graceful termination signal utilities.
Package object provides types for Git objects and functions for parsing and serializing those objects.
 Package object provides types for Git objects and functions for parsing and serializing those objects.
Package packfile provides types for operating on Git packfiles.
 Package packfile provides types for operating on Git packfiles.
client
Package client provides a Git packfile protocol client for sending and receiving Git objects.
 Package client provides a Git packfile protocol client for sending and receiving Git objects.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.