git

Documentation

Index

• Variables
• func CheckDirectoryIsValidGitCheckout(ctx context.Context, envContainer app.EnvContainer, dir string) error
• func CheckForUncommittedGitChanges(ctx context.Context, envContainer app.EnvContainer, dir string) ([]string, error)
• func GetCurrentHEADGitCommit(ctx context.Context, envContainer app.EnvContainer, dir string) (string, error)
• func GetRefsForGitCommitAndRemote(ctx context.Context, envContainer app.EnvContainer, dir string, remote string, ...) ([]string, error)
• func IsValidRef(ctx context.Context, envContainer app.EnvContainer, dir, ref string) error
• func ReadFileAtRef(ctx context.Context, envContainer app.EnvContainer, path, ref string) ([]byte, error)
• type CloneToBucketOptions
• type Cloner
  • func NewCloner(logger *slog.Logger, storageosProvider storageos.Provider, ...) Cloner
• type ClonerOptions
• type ListFilesAndUnstagedFilesOptions
• type Lister
  • func NewLister() Lister
• type Name
  • func NewBranchName(branch string) Name
  • func NewRefName(ref string) Name
  • func NewRefNameWithBranch(ref string, branch string) Name
  • func NewTagName(tag string) Name
• type Remote
  • func GetRemote(ctx context.Context, envContainer app.EnvContainer, dir string, name string) (Remote, error)

Variables

var (
	// ErrRemoteNotFound is returned from GetRemote when the specified remote name is not
	// found in the current git checkout.
	ErrRemoteNotFound = errors.New("git remote not found")

	// ErrInvalidGitCheckout is returned from CheckDirectoryIsValidGitCheckout when the
	// specified directory is not a valid git checkout.
	ErrInvalidGitCheckout = errors.New("invalid git checkout")

	// ErrInvalidRef is returned from IsValidRef if the ref does not exist in the
	// repository containing the given directory (or, if the directory is not
	// a valid git checkout).
	ErrInvalidRef = errors.New("invalid git ref")
)

Functions

func CheckDirectoryIsValidGitCheckout

func CheckDirectoryIsValidGitCheckout(
	ctx context.Context,
	envContainer app.EnvContainer,
	dir string,
) error

CheckDirectoryIsValidGitCheckout runs a simple git rev-parse. In the case where the directory is not a valid git checkout (e.g. the directory is not a git repository or the directory does not exist), this will return a 128. We handle that and return an ErrInvalidGitCheckout to the user.

func CheckForUncommittedGitChanges

func CheckForUncommittedGitChanges(
	ctx context.Context,
	envContainer app.EnvContainer,
	dir string,
) ([]string, error)

CheckForUncommittedGitChanges checks if there are any uncommitted and/or unchecked changes from git based on the given directory.

func GetCurrentHEADGitCommit

func GetCurrentHEADGitCommit(
	ctx context.Context,
	envContainer app.EnvContainer,
	dir string,
) (string, error)

GetCurrentHEADGitCommit returns the current HEAD commit based on the given directory.

func GetRefsForGitCommitAndRemote

func GetRefsForGitCommitAndRemote(
	ctx context.Context,
	envContainer app.EnvContainer,
	dir string,
	remote string,
	gitCommitSha string,
) ([]string, error)

GetRefsForGitCommitAndRemote returns all refs pointing to a given commit based on the given remote for the given directory. Querying the remote for refs information requires passing the environment for permissions.

func IsValidRef

func IsValidRef(
	ctx context.Context,
	envContainer app.EnvContainer,
	dir, ref string,
) error

IsValidRef returns whether or not ref is a valid git ref for the git repository that contains dir. Returns nil if the ref is valid.

func ReadFileAtRef

func ReadFileAtRef(
	ctx context.Context,
	envContainer app.EnvContainer,
	path, ref string,
) ([]byte, error)

ReadFileAtRef will read the file at path rolled back to the given ref, if it exists at that ref.

Specifically, this will take path, and find the associated .git directory (and thus, repository root) associated with that path, if any. It will then look up the commit corresponding to ref in that git directory, and within that commit, the blob corresponding to that path (relative to the repository root).

Types

type CloneToBucketOptions

type CloneToBucketOptions struct {
	Matcher           storage.Matcher
	Name              Name
	RecurseSubmodules bool
	SubDir            string
	Filter            string
}

CloneToBucketOptions are options for Clone.

type Cloner

type Cloner interface {
	// CloneToBucket clones the repository to the bucket.
	//
	// The url must contain the scheme, including file:// if necessary.
	// depth must be > 0.
	CloneToBucket(
		ctx context.Context,
		envContainer app.EnvContainer,
		url string,
		depth uint32,
		writeBucket storage.WriteBucket,
		options CloneToBucketOptions,
	) error
}

Cloner clones git repositories to buckets.

func NewCloner

func NewCloner(
	logger *slog.Logger,
	storageosProvider storageos.Provider,
	options ClonerOptions,
) Cloner

NewCloner returns a new Cloner.

type ClonerOptions

type ClonerOptions struct {
	HTTPSUsernameEnvKey      string
	HTTPSPasswordEnvKey      string
	SSHKeyFileEnvKey         string
	SSHKnownHostsFilesEnvKey string
}

ClonerOptions are options for a new Cloner.

type ListFilesAndUnstagedFilesOptions

type ListFilesAndUnstagedFilesOptions struct {
	// IgnorePathRegexps are regexes of paths to ignore.
	//
	// These must be unnormalized in the manner of the local OS that the Lister
	// is being applied to.
	IgnorePathRegexps []*regexp.Regexp
}

ListFilesAndUnstagedFilesOptions are options for ListFilesAndUnstagedFiles.

type Lister

type Lister interface {
	// ListFilesAndUnstagedFiles lists all files checked into git except those that
	// were deleted, and also lists unstaged files.
	//
	// This does not list unstaged deleted files
	// This does not list unignored files that were not added.
	// This ignores regular files.
	//
	// This is used for situations like license headers where we want all the
	// potential git files during development.
	//
	// The returned paths will be unnormalized.
	//
	// This is the equivalent of doing:
	//
	//	comm -23 \
	//		<(git ls-files --cached --modified --others --no-empty-directory --exclude-standard | sort -u | grep -v -e IGNORE_PATH1 -e IGNORE_PATH2) \
	//		<(git ls-files --deleted | sort -u)
	ListFilesAndUnstagedFiles(
		ctx context.Context,
		envContainer app.EnvStdioContainer,
		options ListFilesAndUnstagedFilesOptions,
	) ([]string, error)
}

Lister lists files in git repositories.

func NewLister

func NewLister() Lister

NewLister returns a new Lister.

type Name

type Name interface {
	// contains filtered or unexported methods
}

Name is a name identifiable by git.

func NewBranchName

func NewBranchName(branch string) Name

NewBranchName returns a new Name for the branch.

func NewRefName

func NewRefName(ref string) Name

NewRefName returns a new Name for the ref.

func NewRefNameWithBranch

func NewRefNameWithBranch(ref string, branch string) Name

NewRefNameWithBranch returns a new Name for the ref while setting branch as the clone target.

func NewTagName

func NewTagName(tag string) Name

NewTagName returns a new Name for the tag.

type Remote

type Remote interface {
	// Name of the remote (e.g. "origin")
	Name() string
	// HEADBranch is the name of the HEAD branch of the remote.
	HEADBranch() string
	// Hostname is the host name parsed from the remote URL. If the remote is an unknown
	// kind, then this may be an empty string.
	Hostname() string
	// RepositoryPath is the path to the repository based on the remote URL. If the remote
	// is an unknown kind, then this may be an empty string.
	RepositoryPath() string
	// SourceControlURL makes the best effort to construct a user-facing source control url
	// given a commit sha string based on the remote source, and available hostname and
	// repository path information.
	//
	// If the remote hostname contains bitbucket (e.g. bitbucket.mycompany.com or bitbucket.org),
	// we construct the source control URL as:
	//
	//   https://<hostname>/<repository-path>/commits/<git-commit-sha>
	//
	// If the remote hostname contains github (e.g. github.mycompany.com or github.com), we
	// construct the source control URL as:
	//   https://<hostname>/repository-path>/commit/git-commit-sha>
	//
	// If the remote hostname contains gitlab (e.g. gitlab.mycompany.com or gitlab.com), we
	// construct the source control URL as:
	//   https://<hostname>/repository-path>/commit/git-commit-sha>
	//
	// If the remote is unknown and/or no hostname/repository path information is available,
	// this will return an empty string.
	//
	// This does not do any validation against the gitCommitSha provided.
	SourceControlURL(gitCommitSha string) string
	// contains filtered or unexported methods
}

Remote represents a Git remote and provides associated metadata.

func GetRemote

func GetRemote(
	ctx context.Context,
	envContainer app.EnvContainer,
	dir string,
	name string,
) (Remote, error)

GetRemote gets the Git remote based on the given remote name. In order to query the remote information, we need to pass in the env with appropriate permissions.