git

package module
v0.7.1 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2020 License: Apache-2.0 Imports: 17 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. 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

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

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 added in v0.7.0 

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

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

import (
	"context"
	"io/ioutil"

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

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) (*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 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) 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 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, 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 [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 added in v0.5.0 

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

MarshalBinary returns the hash as a byte slice.

func (Hash) MarshalText added in v0.5.0 

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 added in v0.5.0 

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 added in v0.5.0 

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

UnmarshalText decodes a hex-encoded hash into h.

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 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 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 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 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 
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 os.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 os.FileInfo interface.

func (*TreeEntry) Mode added in v0.2.0 

func (ent *TreeEntry) Mode() os.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() string

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

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

Source Files

View all Source files

Directories

Path Synopsis
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.
sigterm
Package sigterm provides graceful termination signal utilities.
 Package sigterm provides graceful termination signal utilities.

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.