repository

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 Branch and Tag.
	SemVer string `json:"semver,omitempty"`

	// RefName is the reference to checkout to. It must conform to the
	// Git reference format: https://git-scm.com/book/en/v2/Git-Internals-Git-References
	// Examples: "refs/heads/main", "refs/pull/420/head", "refs/tags/v0.1.0"
	// It takes precedence over Branch, Tag and SemVer.
	RefName string

	// Commit SHA1 to checkout, takes precedence over all the other options.
	// If supported by the client, it can be combined with Branch.
	Commit string
}

type Client interface {
	Reader
	Writer
}

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
}

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

type CommitOption func(*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
}

type DiscardCloser struct{}

type Reader interface {
	// Clone clones a repository from the provided url using the options provided.
	// It returns a Commit object describing the Git commit that the repository
	// HEAD points to. If the repository is empty, it returns a nil Commit.
	Clone(ctx context.Context, url string, cloneOpts CloneOptions) (*git.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
	Closer
}

type Writer 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 git.Commit, commitOpts ...CommitOption) (string, error)
	Closer
}