git

Documentation

Index

• Constants
• type ClientOptions
• type CloneOptions
• type CommitMetadata
• type CommitOptions
• type Repo
  • func Clone(repoURL string, clientOpts *ClientOptions, cloneOpts *CloneOptions) (Repo, error)
• type RepoCredentials
• type SigningKeyType
• type TagMetadata
• type User

Constants

const (
	// FilterBlobless is a filter that excludes blobs from the clone.
	// When using this filter, the initial Git clone will download all
	// reachable commits and trees, and only download the blobs for commits
	// when you do a Git checkout (including the first checkout during the
	// clone).
	//
	// When using a blobless clone, you can still explore the commits of the
	// repository without downloading additional data. This means that you can
	// perform commands like `git log`, or even `git log -- <path>` with the
	// same performance as a full clone.
	//
	// Commands like `git diff` or `git blame <path>` require the contents of
	// the paths to compute diffs, so these will trigger blob downloads the
	// first time they are run.
	FilterBlobless = "blob:none"
)

Types

type ClientOptions

type ClientOptions struct {
	// User represents the actor that performs operations against the git
	// repository. This has no effect on authentication, see Credentials for
	// specifying authentication configuration.
	User *User
	// Credentials represents the authentication information.
	Credentials *RepoCredentials
}

ClientOptions represents options for the git client. Commonly, the repository credentials are required to authenticate with a remote repository.

type CloneOptions

type CloneOptions struct {
	// Branch is the name of the branch to clone. If not specified, the default
	// branch will be cloned.
	Branch string
	// SingleBranch indicates whether the clone should be a single-branch clone.
	SingleBranch bool
	// Depth is the number of commits to fetch from the remote repository. If
	// zero, all commits will be fetched.
	Depth uint
	// Filter allows for partially cloning the repository by specifying a
	// filter. When a filter is specified, the server will only send a
	// subset of reachable objects according to a given object filter.
	//
	// For more information, see:
	// - https://git-scm.com/docs/git-clone#Documentation/git-clone.txt-code--filtercodeemltfilter-specgtem
	// - https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt
	// - https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/
	// - https://docs.gitlab.com/ee/topics/git/partial_clone.html
	Filter string
	// InsecureSkipTLSVerify specifies whether certificate verification errors
	// should be ignored when cloning the repository. The setting will be
	// remembered for subsequent interactions with the remote repository.
	InsecureSkipTLSVerify bool
}

CloneOptions represents options for cloning a git repository.

type CommitMetadata

type CommitMetadata struct {
	// CommitID is the ID (sha) of the commit.
	ID string
	// CommitDate is the date of the commit.
	CommitDate time.Time
	// Author is the author of the commit, in the format "Name <email>".
	Author string
	// Committer is the person who committed the commit, in the format
	// "Name <email>".
	Committer string
	// Subject is the subject (first line) of the commit message.
	Subject string
}

type CommitOptions

type CommitOptions struct {
	// AllowEmpty indicates whether an empty commit should be allowed.
	AllowEmpty bool
}

CommitOptions represents options for committing changes to a git repository.

type Repo

type Repo interface {
	// AddAll stages pending changes for commit.
	AddAll() error
	// AddAllAndCommit is a convenience function that stages pending changes for
	// commit to the current branch and then commits them using the provided
	// commit message.
	AddAllAndCommit(message string) error
	// Clean cleans the working directory.
	Clean() error
	// Close cleans up file system resources used by this repository. This should
	// always be called before a repository goes out of scope.
	Close() error
	// Checkout checks out the specified branch.
	Checkout(branch string) error
	// Commit commits staged changes to the current branch.
	Commit(message string, opts *CommitOptions) error
	// CreateChildBranch creates a new branch that is a child of the current
	// branch.
	CreateChildBranch(branch string) error
	// CreateOrphanedBranch creates a new branch that shares no commit history
	// with any other branch.
	CreateOrphanedBranch(branch string) error
	// CurrentBranch returns the current branch
	CurrentBranch() string
	// DeleteBranch deletes the specified branch
	DeleteBranch(branch string) error
	// HasDiffs returns a bool indicating whether the working directory currently
	// contains any differences from what's already at the head of the current
	// branch.
	HasDiffs() (bool, error)
	// GetDiffPathsForCommitID returns a string slice indicating the paths,
	// relative to the root of the repository, of any files that are new or
	// modified in the commit with the given ID.
	GetDiffPathsForCommitID(commitID string) ([]string, error)
	// IsAncestor returns true if parent branch is an ancestor of child
	IsAncestor(parent string, child string) (bool, error)
	// LastCommitID returns the ID (sha) of the most recent commit to the current
	// branch.
	LastCommitID() (string, error)
	// ListTags returns a slice of tags in the repository with metadata such as
	// commit ID, creator date, and subject.
	ListTags() ([]TagMetadata, error)
	// ListCommits returns a slice of commits in the current branch with
	// metadata such as commit ID, commit date, and subject.
	ListCommits(limit, skip uint) ([]CommitMetadata, error)
	// CommitMessage returns the text of the most recent commit message associated
	// with the specified commit ID.
	CommitMessage(id string) (string, error)
	// Push pushes from the current branch to a remote branch by the same name.
	Push(force bool) error
	// RefsHaveDiffs returns whether there is a diff between two commits/branches
	RefsHaveDiffs(commit1 string, commit2 string) (bool, error)
	// RemoteBranchExists returns a bool indicating if the specified branch exists
	// in the remote repository.
	RemoteBranchExists(branch string) (bool, error)
	// ResetHard performs a hard reset.
	ResetHard() error
	// URL returns the remote URL of the repository.
	URL() string
	// WorkingDir returns an absolute path to the repository's working tree.
	WorkingDir() string
	// HomeDir returns an absolute path to the home directory of the system user
	// who has cloned this repo.
	HomeDir() string
}

Repo is an interface for interacting with a git repository.

func Clone

func Clone(
	repoURL string,
	clientOpts *ClientOptions,
	cloneOpts *CloneOptions,
) (Repo, error)

Clone produces a local clone of the remote git repository at the specified URL and returns an implementation of the Repo interface that is stateful and NOT suitable for use across multiple goroutines. This function will also perform any setup that is required for successfully authenticating to the remote repository.

type RepoCredentials

type RepoCredentials struct {
	// SSHPrivateKey is a private key that can be used for both reading from and
	// writing to some remote repository.
	SSHPrivateKey string `json:"sshPrivateKey,omitempty"`
	// Username identifies a principal, which combined with the value of the
	// Password field, can be used for both reading from and writing to some
	// remote repository.
	Username string `json:"username,omitempty"`
	// Password, when combined with the principal identified by the Username
	// field, can be used for both reading from and writing to some remote
	// repository.
	Password string `json:"password,omitempty"`
}

RepoCredentials represents the credentials for connecting to a private git repository.

type SigningKeyType

type SigningKeyType string

const (
	SigningKeyTypeGPG SigningKeyType = "gpg"
)

type TagMetadata

type TagMetadata struct {
	// Tag is the name of the tag.
	Tag string
	// CommitID is the ID (sha) of the commit associated with the tag.
	CommitID string
	// CreatorDate is the creation date of an annotated tag, or the commit date
	// of a lightweight tag.
	CreatorDate time.Time
	// Author is the author of the commit message associated with the tag, in
	// the format "Name <email>".
	Author string
	// Committer is the person who committed the commit associated with the tag,
	// in the format "Name <email>".
	Committer string
	// Subject is the subject (first line) of the commit message associated
	// with the tag.
	Subject string
}

TagMetadata represents metadata associated with a Git tag.

type User

type User struct {
	// Name is the user's full name.
	Name string
	// Email is the user's email address.
	Email string
	// SigningKeyType indicates the type of signing key.
	SigningKeyType SigningKeyType
	// SigningKeyPath is an optional path referencing a signing key for
	// signing git objects.
	SigningKeyPath string
}

User represents the user contributing to a git repository.