git

Documentation

Overview

Package git provides a wrapper for the git command line program. The helper methods avoids porcelain commands as much as possible and return a parsed output whenever possible.

Users of this package have access to the low-level Exec() function for the methods not yet implemented.

Index

• func NewCmdError(cmd string, stdout, stderr []byte) error
• type CmdError
  • func (e *CmdError) Command() string
  • func (e *CmdError) Error() string
  • func (e *CmdError) Is(err error) bool
  • func (e *CmdError) Stderr() []byte
  • func (e *CmdError) Stdout() []byte
• type CommitMetadata
• type Config
• type Error
  • func (e Error) Error() string
• type Git
  • func WithConfig(cfg Config) (*Git, error)
  • func (git *Git) Add(files ...string) error
  • func (git *Git) AddSubmodule(name string, url string) (string, error)
  • func (git *Git) Checkout(rev string, create bool) error
  • func (git *Git) Clone(repoURL, dir string) error
  • func (git *Git) Commit(msg string, args ...string) error
  • func (git *Git) CurrentBranch() (string, error)
  • func (git *Git) DeleteBranch(name string) error
  • func (git *Git) DiffNames(from, to string) ([]string, error)
  • func (git *Git) DiffTree(from, to string, relative, nameOnly, recurse bool) (string, error)
  • func (git *Git) Exec(command string, args ...string) (string, error)
  • func (git *Git) FetchRemoteRev(remote, ref string) (Ref, error)
  • func (git *Git) GetConfigValue(key string) (string, error)
  • func (git *Git) HasRemotes() (bool, error)
  • func (git *Git) Init(dir string, defaultBranch string, bare bool) error
  • func (git *Git) IsRepository() bool
  • func (git *Git) ListUncommitted(dirs ...string) ([]string, error)
  • func (git *Git) ListUntracked(dirs ...string) ([]string, error)
  • func (git *Git) LogSummary(revs ...string) ([]LogLine, error)
  • func (git *Git) Merge(branch string) error
  • func (git *Git) MergeBase(commit1, commit2 string) (string, error)
  • func (git *Git) NewBranch(name string) error
  • func (git *Git) Pull(remote, branch string) error
  • func (git *Git) Push(remote, branch string) error
  • func (git *Git) RemoteAdd(name string, url string) error
  • func (git *Git) Remotes() ([]Remote, error)
  • func (git *Git) RevParse(rev string) (string, error)
  • func (git *Git) Root() (string, error)
  • func (git *Git) SetRemoteURL(remote, url string) error
  • func (git *Git) ShowCommitMetadata(objectName string) (*CommitMetadata, error)
  • func (git *Git) Status() (string, error)
  • func (git *Git) URL(remote string) (string, error)
  • func (git *Git) Version() (string, error)
  • func (git *Git) With() *Options
• type LogLine
• type Options
  • func (opt *Options) WorkingDir(wd string) *Options
  • func (opt Options) Wrapper() *Git
• type Ref
  • func (r Ref) ShortCommitID() string
• type Remote

Functions

func NewCmdError

func NewCmdError(cmd string, stdout, stderr []byte) error

NewCmdError returns a new command line error.

Types

type CmdError

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

CmdError is the error for failed commands.

func (*CmdError) Command

func (e *CmdError) Command() string

Command is the failed command.

func (*CmdError) Error

func (e *CmdError) Error() string

Error string representation.

func (*CmdError) Is

func (e *CmdError) Is(err error) bool

Is tells if err is of the type CmdError.

func (*CmdError) Stderr

func (e *CmdError) Stderr() []byte

Stderr of the failed command.

func (*CmdError) Stdout

func (e *CmdError) Stdout() []byte

Stdout of the failed command.

type CommitMetadata

type CommitMetadata struct {
	Author  string
	Email   string
	Time    *time.Time
	Subject string
	Body    string
}

CommitMetadata is metadata associated with a Git commit.

type Config

type Config struct {
	Username    string // Username used in commits.
	Email       string // Email used in commits.
	ProgramPath string

	// WorkingDir sets the directory where the commands will be applied.
	WorkingDir string

	// Env is the environment variables to be passed over to git.
	// If it is nil it means no environment variables should be passed.
	// To inherit all env vars from the parent process os.Getenv() needs
	// to be passed explicitly.
	Env []string

	// Isolated tells if the wrapper should run with isolated
	// configurations, which means setting it to true will make the wrapper
	// not rely on the global/system configuration. It's useful for
	// reproducibility of scripts.
	Isolated bool

	// AllowPorcelain tells if the wrapper is allowed to execute porcelain
	// commands. It's useful if the user is not sure if all commands used by
	// their program are plumbing.
	AllowPorcelain bool

	// Global arguments that are automatically added when executing git commands.
	// This is useful for setting config overrides or other common flags.
	GlobalArgs []string
}

Config configures the wrapper.

type Error

type Error string

Error is the sentinel error type.

const (
	// ErrGitNotFound is the error that tells if git was not found.
	ErrGitNotFound Error = "git program not found"

	// ErrInvalidConfig is the error that tells if the configuration is invalid.
	ErrInvalidConfig Error = "invalid configuration"

	// ErrDenyPorcelain is the error that tells if a porcelain method was called
	// when AllowPorcelain is false.
	ErrDenyPorcelain Error = "porcelain commands are not allowed by the configuration"
)

func (Error) Error

func (e Error) Error() string

Error string representation.

type Git

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

Git is the wrapper object.

func WithConfig

func WithConfig(cfg Config) (*Git, error)

WithConfig creates a new git wrapper by providing the config.

func (*Git) Add

func (git *Git) Add(files ...string) error

Add files to current staged index. Beware: Add is a porcelain method.

func (*Git) AddSubmodule

func (git *Git) AddSubmodule(name string, url string) (string, error)

AddSubmodule adds the submodule name from url into this repository. For security reasons, this method should only be used in tests.

func (*Git) Checkout

func (git *Git) Checkout(rev string, create bool) error

Checkout switches branches or change to specific revisions in the tree. When switching branches, the create flag can be set to automatically create the new branch before changing into it. Beware: Checkout is a porcelain method.

func (*Git) Clone

func (git *Git) Clone(repoURL, dir string) error

Clone will clone the given repo inside the given dir. Beware: Clone is a porcelain method.

func (*Git) Commit

func (git *Git) Commit(msg string, args ...string) error

Commit the current staged changes. The args are extra flags and/or arguments to git commit command line. Beware: Commit is a porcelain method.

func (*Git) CurrentBranch

func (git *Git) CurrentBranch() (string, error)

CurrentBranch returns the short branch name that HEAD points to.

func (*Git) DeleteBranch

func (git *Git) DeleteBranch(name string) error

DeleteBranch deletes the branch.

func (*Git) DiffNames

func (git *Git) DiffNames(from, to string) ([]string, error)

DiffNames recursively walks the git tree objects computing the from and to commit ids differences and return all the file names containing differences relative to configuration WorkingDir.

func (*Git) DiffTree

func (git *Git) DiffTree(from, to string, relative, nameOnly, recurse bool) (string, error)

DiffTree compares the from and to commit ids and returns the differences. If nameOnly is set then only the file names of changed files are show. If recurse is set, then it walks into child trees as well. If relative is set, then only show local changes of current dir.

func (*Git) Exec

func (git *Git) Exec(command string, args ...string) (string, error)

Exec executes any provided git command. We don't allow Exec if AllowPorcelain is set to false.

func (*Git) FetchRemoteRev

func (git *Git) FetchRemoteRev(remote, ref string) (Ref, error)

FetchRemoteRev will fetch from the remote repo the commit id and ref name for the given remote and reference. This will make use of the network to fetch data from the remote configured on the git repo.

func (*Git) GetConfigValue

func (git *Git) GetConfigValue(key string) (string, error)

GetConfigValue returns the value mapped to given config key, or an error if they doesn't exist.

func (*Git) HasRemotes

func (git *Git) HasRemotes() (bool, error)

HasRemotes returns if a there are any remotes configured.

func (*Git) Init

func (git *Git) Init(dir string, defaultBranch string, bare bool) error

Init initializes a git repository. If bare is true, it initializes a "bare repository", in other words, a repository not intended for work but just store revisions. Beware: Init is a porcelain method.

func (*Git) IsRepository

func (git *Git) IsRepository() bool

IsRepository tell if the git wrapper setup is operating in a valid git repository.

func (*Git) ListUncommitted

func (git *Git) ListUncommitted(dirs ...string) ([]string, error)

ListUncommitted lists uncommitted files in the directories provided in dirs.

func (*Git) ListUntracked

func (git *Git) ListUntracked(dirs ...string) ([]string, error)

ListUntracked lists untracked files in the directories provided in dirs.

func (*Git) LogSummary

func (git *Git) LogSummary(revs ...string) ([]LogLine, error)

LogSummary returns a list of commit log summary in reverse chronological order from the revs set operation. It expects the same revision list as the `git rev-list` command.

It returns only the first line of the commit message.

func (*Git) Merge

func (git *Git) Merge(branch string) error

Merge branch into current branch using the non fast-forward strategy. Beware: Merge is a porcelain method.

func (*Git) MergeBase

func (git *Git) MergeBase(commit1, commit2 string) (string, error)

MergeBase finds the common commit ancestor of commit1 and commit2.

func (*Git) NewBranch

func (git *Git) NewBranch(name string) error

NewBranch creates a new branch reference pointing to current HEAD.

func (*Git) Pull

func (git *Git) Pull(remote, branch string) error

Pull changes from remote into branch

func (*Git) Push

func (git *Git) Push(remote, branch string) error

Push changes from branch onto remote.

func (*Git) RemoteAdd

func (git *Git) RemoteAdd(name string, url string) error

RemoteAdd adds a new remote name.

func (*Git) Remotes

func (git *Git) Remotes() ([]Remote, error)

Remotes returns a list of all configured remotes and their respective branches. The result slice is ordered lexicographically by the remote name.

Returns an empty list if no remote is found.

func (*Git) RevParse

func (git *Git) RevParse(rev string) (string, error)

RevParse parses the rev name and returns the commit id it points to. The rev name follows the [git revisions](https://git-scm.com/docs/gitrevisions) documentation.

func (*Git) Root

func (git *Git) Root() (string, error)

Root returns the git root directory.

func (*Git) SetRemoteURL

func (git *Git) SetRemoteURL(remote, url string) error

SetRemoteURL sets the remote url.

func (*Git) ShowCommitMetadata

func (git *Git) ShowCommitMetadata(objectName string) (*CommitMetadata, error)

ShowCommitMetadata returns common metadata associated with the given object. An object name can be a commit SHA or a symbolic name, i.e. HEAD, branch-name, etc.

func (*Git) Status

func (git *Git) Status() (string, error)

Status returns the git status of the current branch. Beware: Status is a porcelain method.

func (*Git) URL

func (git *Git) URL(remote string) (string, error)

URL returns the remote URL.

func (*Git) Version

func (git *Git) Version() (string, error)

Version of the git program.

func (*Git) With

func (git *Git) With() *Options

With returns a copy of the wrapper options. Use opt.Wrapper() to get a new Git wrapper with the new options applied.

type LogLine

type LogLine struct {
	CommitID string
	Message  string
}

LogLine is a log summary.

type Options

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

Options is a customizable options object to be used with the Git wrapper.

func (*Options) WorkingDir

func (opt *Options) WorkingDir(wd string) *Options

WorkingDir sets the wrapper working directory.

func (Options) Wrapper

func (opt Options) Wrapper() *Git

Wrapper returns a new wrapper with the given options.

type Ref

type Ref struct {
	Name     string
	CommitID string
}

Ref is a git reference.

func (Ref) ShortCommitID

func (r Ref) ShortCommitID() string

ShortCommitID returns the short version of the commit ID. If the reference doesn't have a valid commit id it returns empty.

type Remote

type Remote struct {
	// Name of the remote reference
	Name string
	// Branches are all the branches the remote reference has
	Branches []string
}

Remote is a git remote.