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. This library is tested against Git 2.17.1 and newer. Older versions may work, but are not supported.

If you find this package useful, consider sponsoring @zombiezen, the author and maintainer.

Installation

go get gg-scm.io/pkg/git

License

Apache 2.0

Expand ▾ Collapse ▴

Documentation

Overview

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

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func ParseURL

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

Code:

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)

}
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

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.

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 the zero value, then the previous commit's author will
	// be used. If Author is partially filled out, the Amend methods will
	// return an error.
	Author 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

	// Committer fields set to non-zero values will override the default
	// committer information from Git configuration.
	Committer User
	// If CommitTime is not zero, then it will be used as the commit time
	// instead of now.
	CommitTime time.Time
}

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 CommitInfo

type CommitInfo struct {
	Hash       Hash
	Parents    []Hash
	Author     User
	Committer  User
	AuthorTime time.Time
	CommitTime time.Time
	Message    string
}

CommitInfo stores information about a single commit.

func (*CommitInfo) Summary

func (c *CommitInfo) Summary() string

Summary returns the first line of the message.

type CommitOptions

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

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

Code:

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"))
}

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 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

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

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.

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) 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

Code:

package main

import (
	"context"
	"gg-scm.io/pkg/git"
	"io/ioutil"
)

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 = ioutil.WriteFile("foo.txt", []byte("Hello, World!\n"), 0666)
	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
	}
}

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) (*CommitInfo, 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) 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

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

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

Code:

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())
}

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

Code:

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())
	}
}

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) ListRefs

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

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

func (*Git) ListRefsVerbatim

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.

func (*Git) ListRemoteRefs

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.

func (*Git) ListSubmodules

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, 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

Code:

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())
}

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

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 [hashSize]byte

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.

func (Hash) MarshalBinary

func (h Hash) MarshalBinary() ([]byte, error)

MarshalBinary returns the hash as a byte slice.

func (Hash) MarshalText

func (h Hash) MarshalText() ([]byte, error)

MarshalText returns the hex-encoded hash.

func (Hash) Short

func (h Hash) Short() string

Short returns the first 4 hex-encoded bytes of the hash.

func (Hash) String

func (h Hash) String() string

String returns the hex-encoded hash.

func (*Hash) UnmarshalBinary

func (h *Hash) UnmarshalBinary(b []byte) error

UnmarshalBinary copies the bytes from b into h. It returns an error if len(b) != len(*h).

func (*Hash) UnmarshalText

func (h *Hash) UnmarshalText(s []byte) error

UnmarshalText decodes a hex-encoded hash into h.

type Invocation

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 ListTreeOptions

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

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

Local implements Runner by starting Git subprocesses.

func NewLocal

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

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

func (*Local) Clean

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

func (l *Local) Exe() string

Exe returns the absolute path to the Git executable.

func (*Local) IsAbs

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

IsAbs calls path/filepath.IsAbs.

func (*Local) Join

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

Join calls path/filepath.Join.

func (*Local) PipeGit

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

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 log` 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 Next returned false due to a parse failure.

func (*Log) CommitInfo

func (l *Log) CommitInfo() *CommitInfo

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

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 string

A Ref is a Git reference to a commit.

const (
	// Head names the commit on which the changes in the working tree
	// are based.
	Head Ref = "HEAD"

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

Top-level refs.

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.

func (Ref) Branch

func (r Ref) Branch() string

Branch returns the string after "refs/heads/" or an empty string if the ref does not start with "refs/heads/".

func (Ref) IsBranch

func (r Ref) IsBranch() bool

IsBranch reports whether r starts with "refs/heads/".

func (Ref) IsTag

func (r Ref) IsTag() bool

IsTag reports whether r starts with "refs/tags/".

func (Ref) IsValid

func (r Ref) IsValid() bool

IsValid reports whether r is a valid reference.

func (Ref) String

func (r Ref) String() string

String returns the ref as a string.

func (Ref) Tag

func (r Ref) Tag() string

Tag returns the string after "refs/tags/" or an empty string if the ref does not start with "refs/tags/".

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 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 (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

Code:

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)
	}
}

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

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

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

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

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

func (*TreeEntry) IsDir

func (ent *TreeEntry) IsDir() bool

IsDir reports whether the file mode indicates a directory.

func (*TreeEntry) ModTime

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

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

func (*TreeEntry) Mode

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

Mode returns the file mode bits.

func (*TreeEntry) Name

func (ent *TreeEntry) Name() string

Name returns the base name of the file.

func (*TreeEntry) Object

func (ent *TreeEntry) Object() Hash

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

func (*TreeEntry) ObjectType

func (ent *TreeEntry) ObjectType() string

ObjectType returns the file's Git object type. Possible values are "blob", "tree", or "commit".

func (*TreeEntry) Path

func (ent *TreeEntry) Path() TopPath

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

func (*TreeEntry) Size

func (ent *TreeEntry) Size() int64

Size returns the length in bytes for blobs.

func (*TreeEntry) String

func (ent *TreeEntry) String() string

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

func (*TreeEntry) Sys

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

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

type User

type User struct {
	// Name is the user's full name.
	Name string
	// Email is the user's email address.
	Email string
}

User identifies an author or committer.

func (User) String

func (u User) String() string

String returns the user information as a string in the form "User Name <foo@example.com>".

Directories

Path Synopsis
internal/filesystem Package filesystem provides concise data structures for filesystem operations and functions to apply them to local files.
internal/sigterm Package sigterm provides graceful termination signal utilities.