git

Documentation

Index

• Constants
• Variables
• func IsConcreteCommit(c Commit) bool
• func SecurePath(path string) (string, error)
• type AuthOptions
  • func NewAuthOptions(u url.URL, data map[string][]byte) (*AuthOptions, error)
  • func (o AuthOptions) Validate() error
• type CheckoutStrategy
• type CloneOptions
• type Commit
  • func (c *Commit) ShortMessage() string
  • func (c *Commit) String() string
  • func (c *Commit) Verify(keyRing ...string) (string, error)
• type CommitOption
  • func WithFiles(files map[string]io.Reader) CommitOption
  • func WithSigner(signer *openpgp.Entity) CommitOption
• type CommitOptions
• type DiscardRepositoryCloser
  • func (c *DiscardRepositoryCloser) Close()
• type ErrRepositoryNotFound
  • func (e ErrRepositoryNotFound) Error() string
• type Hash
  • func (h Hash) String() string
• type RepositoryClient
• type RepositoryCloser
• type RepositoryReader
• type RepositoryWriter
• type Signature
• type TransportType

Constants

const (
	DefaultRemote            = "origin"
	DefaultBranch            = "master"
	DefaultPublicKeyAuthUser = "git"
)

Variables

var (
	ErrNoGitRepository = errors.New("no git repository")
	ErrNoStagedFiles   = errors.New("no staged files")
)

var HostKeyAlgos []string

HostKeyAlgos holds the HostKey algorithms that the SSH client will advertise to the server. If empty, Go's default is used instead.

var KexAlgos []string

KexAlgos hosts the key exchange algorithms to be used for SSH connections. If empty, Go's default is used instead.

Functions

func IsConcreteCommit

func IsConcreteCommit(c Commit) bool

IsConcreteCommit returns if a given commit is a concrete commit. Concrete commits have most of commit metadata and commit content. In contrast, a partial commit may only have some metadata and no commit content.

func SecurePath

func SecurePath(path string) (string, error)

SecurePath accepts an absolute or relative path and returns a path that is safe for use. If the path is absolute, it's `filepath.Clean`ed and returned. If the path is relative, it's securely joined against the working directory to ensure that the resultant path is a child of the working directory.

Types

type AuthOptions

type AuthOptions struct {
	Transport  TransportType
	Host       string
	Username   string
	Password   string
	Identity   []byte
	KnownHosts []byte
	CAFile     []byte
}

AuthOptions are the authentication options for the Transport of communication with a remote origin.

func NewAuthOptions

func NewAuthOptions(u url.URL, data map[string][]byte) (*AuthOptions, error)

NewAuthOptions constructs an AuthOptions object from the given map and URL. If the map is empty, it returns a minimal AuthOptions object after validating the result.

func (AuthOptions) Validate

func (o AuthOptions) Validate() error

Validate the AuthOptions against the defined Transport.

type CheckoutStrategy

type CheckoutStrategy struct {
	// Branch to checkout. If supported by the client, it can be combined
	// with Commit.
	Branch string

	// Tag to checkout, takes precedence over Branch.
	Tag string

	// SemVer tag expression to checkout, takes precedence over Tag.
	SemVer string `json:"semver,omitempty"`

	// Commit SHA1 to checkout, takes precedence over Tag and SemVer.
	// If supported by the client, it can be combined with Branch.
	Commit string
}

CheckoutStrategy provides options to checkout a repository to a target.

type CloneOptions

type CloneOptions struct {
	// CheckoutStrategy defines a strategy to use while checking out
	// the cloned repository to a specific target.
	CheckoutStrategy

	// RecurseSubmodules defines if submodules should be checked out,
	// not supported by all Implementations.
	RecurseSubmodules bool

	// LastObservedCommit holds the last observed commit hash of a
	// Git repository.
	// If provided, the clone operation will compare it with the HEAD commit
	// of the branch or tag (as configured via CheckoutStrategy) in the remote
	// repository. If they match, cloning will be skipped and a "non-concrete"
	// commit will be returned, which can be verified using `IsConcreteCommit()`.
	// This functionality is not supported when using a semver range or a commit
	// to checkout.
	LastObservedCommit string

	// ShallowClone defines if the repository should be shallow cloned,
	// not supported by all implementations
	ShallowClone bool
}

CloneOptions are the options used for a Git clone.

type Commit

type Commit struct {
	// Hash is the SHA1 hash of the commit.
	Hash Hash
	// Reference is the original reference of the commit, for example:
	// 'refs/tags/foo'.
	Reference string
	// Author is the original author of the commit.
	Author Signature
	// Committer is the one performing the commit, might be different from
	// Author.
	Committer Signature
	// Signature is the PGP signature of the commit.
	Signature string
	// Encoded is the encoded commit, without any signature.
	Encoded []byte
	// Message is the commit message, contains arbitrary text.
	Message string
}

Commit contains all possible information about a Git commit.

func (*Commit) ShortMessage

func (c *Commit) ShortMessage() string

ShortMessage returns the first 50 characters of a commit subject.

func (*Commit) String

func (c *Commit) String() string

String returns a string representation of the Commit, composed out the last part of the Reference element, and/or Hash. For example: 'tag-1/a0c14dc8580a23f79bc654faa79c4f62b46c2c22', for a "tag-1" tag.

func (*Commit) Verify

func (c *Commit) Verify(keyRing ...string) (string, error)

Verify the Signature of the commit with the given key rings. It returns the fingerprint of the key the signature was verified with, or an error.

type CommitOption

type CommitOption func(*CommitOptions)

CommitOption defines an option for a commit operation.

func WithFiles

func WithFiles(files map[string]io.Reader) CommitOption

WithFiles instructs the Git client to write the provided files and include them in the commit. files contains file names as its key and the content of the file as the value. If the file already exists, its overwritten.

func WithSigner

func WithSigner(signer *openpgp.Entity) CommitOption

WithSigner allows for the commit to be signed using the provided OpenPGP signer.

type CommitOptions

type CommitOptions struct {
	// Signer can be used to sign a commit using OpenPGP.
	Signer *openpgp.Entity
	// Files contains file names mapped to the file's content.
	// Its used to write files which are then included in the commit.
	Files map[string]io.Reader
}

CommitOptions provides options to configure a Git commit operation.

type DiscardRepositoryCloser

type DiscardRepositoryCloser struct{}

DiscardRepositoryCloser is a RepositoryCloser which discards calls to Close().

func (*DiscardRepositoryCloser) Close

func (c *DiscardRepositoryCloser) Close()

type ErrRepositoryNotFound

type ErrRepositoryNotFound struct {
	Message string
	URL     string
}

ErrRepositoryNotFound indicates that the repository (or the ref in question) does not exist at the given URL.

func (ErrRepositoryNotFound) Error

func (e ErrRepositoryNotFound) Error() string

type Hash

type Hash []byte

func (Hash) String

func (h Hash) String() string

String returns the Hash as a string.

type RepositoryClient

type RepositoryClient interface {
	RepositoryReader
	RepositoryWriter
}

RepositoryClient knows how to perform local and remote operations on a Git repository.

type RepositoryCloser

type RepositoryCloser interface {
	// Close closes any resources that need to be closed at the end of
	// a Git repository client's lifecycle.
	Close()
}

RepositoryCloser knows how to perform any operations that need to happen at the end of the lifecycle of a RepositoryWriter/RepositoryReader. When this is not required by the implementation, it can simply embed an anonymous pointer to DiscardRepositoryCloser.

type RepositoryReader

type RepositoryReader interface {
	// Clone clones a repository from the provided url using the options provided.
	Clone(ctx context.Context, url string, cloneOpts CloneOptions) (*Commit, error)
	// IsClean returns whether the working tree is clean.
	IsClean() (bool, error)
	// Head returns the hash of the current HEAD of the repo.
	Head() (string, error)
	// Path returns the path of the repository.
	Path() string
	RepositoryCloser
}

RepositoryReader knows how to perform local and remote read operations on a Git repository.

type RepositoryWriter

type RepositoryWriter interface {
	// Init initializes a repository at the configured path with the remote
	// origin set to url on the provided branch.
	Init(ctx context.Context, url, branch string) error
	// Push pushes the current branch of the repository to origin.
	Push(ctx context.Context) error
	// SwitchBranch switches from the current branch of the repository to the
	// provided branch. If the branch doesn't exist, it is created.
	SwitchBranch(ctx context.Context, branch string) error
	// Commit commits any changes made to the repository. commitOpts is an
	// optional argument which can be provided to configure the commit.
	Commit(info Commit, commitOpts ...CommitOption) (string, error)
	RepositoryCloser
}

RepositoryWriter knows how to perform local and remote write operations on a Git repository.

type Signature

type Signature struct {
	Name  string
	Email string
	When  time.Time
}

Signature represents an entity which associates a person and a time with a commit.

type TransportType

type TransportType string

const (
	SSH   TransportType = "ssh"
	HTTPS TransportType = "https"
	HTTP  TransportType = "http"
)