git

type AddWorkTreeOptions struct {
	// Orphan specifies whether the working tree should be created from a new,
	// orphaned branch. If true, the Ref field will be ignored.
	Orphan bool
	// Ref specifies the branch or commit to check out in the working tree. Will
	// be ignored if Orphan is true.
	Ref string
	// Sparse specifies directory patterns for sparse checkout using cone mode.
	// When specified, only the listed directories (and their contents) will be
	// checked out. Patterns should be directory paths relative to the repository
	// root (e.g., "src/app", "configs/prod").
	Sparse []string
}

type BareCloneOptions struct {
	// BaseDir is an existing directory within which all other directories created
	// and managed by the BareRepo implementation will be created. If not
	// specified, the operating system's temporary directory will be used.
	// Overriding that default is useful under certain circumstances.
	BaseDir 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
	// Filter specifies a partial clone filter (e.g., "blob:none"). When combined
	// with sparse checkout, this avoids downloading blobs for directories that
	// won't be checked out, significantly reducing clone time and disk usage for
	// large repositories.
	Filter string
}

type BareRepo interface {
	// AddWorkTree adds a working tree to the repository.
	AddWorkTree(path string, opts *AddWorkTreeOptions) (WorkTree, 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
	// Dir returns an absolute path to the repository.
	Dir() string
	// HomeDir returns an absolute path to the home directory of the system user
	// who has cloned this repo.
	HomeDir() string
	// RemoteBranchExists returns a bool indicating if the specified branch exists
	// in the remote repository.
	RemoteBranchExists(branch string) (bool, error)
	// RemoveWorkTree removes a working tree from the repository. The working tree
	// will be removed from the file system.
	RemoveWorkTree(path string) error
	// URL returns the remote URL of the repository.
	URL() string
	// WorkTrees returns a list of working trees associated with the repository.
	WorkTrees() ([]WorkTree, error)
}

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
	// InsecureSkipTLSVerify indicates whether to ignore certificate verification
	// errors when interacting with the remote repository.
	InsecureSkipTLSVerify bool
}

type CloneOptions struct {
	// BaseDir is an existing directory within which all other directories created
	// and managed by the Repo implementation will be created. If not specified,
	// the operating system's temporary directory will be used. Overriding that
	// default is useful under certain circumstances.
	BaseDir string
	// Branch is the name of the branch to clone. If not specified, the default
	// branch will be cloned. This option is ignored if Bare is true.
	Branch string
	// Depth is the number of commits to fetch from the remote repository. If
	// zero, all commits will be fetched. This option is ignored if Bare is true.
	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
	// SingleBranch indicates whether the clone should be a single-branch clone.
	// This option is ignored if Bare is true.
	SingleBranch bool
}

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 struct {
	// AllowEmpty indicates whether an empty commit should be allowed.
	AllowEmpty bool
	// Author is the author of the commit. If nil, the default author already
	// configured in the git repository will be used.
	Author *User
}

type CommitSignatureInfo struct {
	// Trusted indicates whether the commit is signed by a key with
	// ultimate trust.
	Trusted bool
	// SignerName is the name from the signing key's UID. Empty if the
	// commit is unsigned.
	SignerName string
	// SignerEmail is the email from the signing key's UID. Empty if the
	// commit is unsigned.
	SignerEmail string
}

type FetchOptions struct {
	// Branch optionally specifies a single branch to fetch. If empty, all
	// branches are fetched.
	Branch string
	// Depth optionally limits fetching to the specified number of commits. A
	// value of 0 (the default) indicates no depth limit.
	Depth uint
}

type IntegrationOptions struct {
	// TargetBranch is the remote branch to integrate changes from. If empty, the
	// current branch is used.
	TargetBranch string
	// IntegrationPolicy controls how remote changes are integrated. If empty or
	// set to PushIntegrationPolicyNone, no integration is performed.
	IntegrationPolicy PushIntegrationPolicy
}

type ListCommitsOptions struct {
	// Limit is the maximum number of commits to return. 0 means no limit.
	Limit uint
	// Skip is the number of commits to skip before returning results.
	Skip uint
	// Since limits commits to those at or after this time.
	Since *time.Time
}

type LoadBareRepoOptions struct {
	Credentials *RepoCredentials
}

type LoadRepoOptions struct {
	Credentials *RepoCredentials
}

type LoadWorkTreeOptions struct {
	Credentials *RepoCredentials
}

type MockRepo struct {
	AddAllFn          func() error
	AddAllAndCommitFn func(
		message string,
		commitOpts *CommitOptions,
	) error
	CleanFn                   func() error
	ClearFn                   func() error
	CloseFn                   func() error
	CheckoutFn                func(branch string) error
	CommitFn                  func(message string, opts *CommitOptions) error
	CreateChildBranchFn       func(branch string) error
	CreateOrphanedBranchFn    func(branch string) error
	CreateTagFn               func(tag, msg string) error
	CurrentBranchFn           func() (string, error)
	DeleteBranchFn            func(branch string) error
	DirFn                     func() string
	FetchFn                   func(opts *FetchOptions) error
	HasDiffsFn                func() (bool, error)
	HomeDirFn                 func() string
	GetDiffPathsForCommitIDFn func(commitID string) ([]string, error)
	IsAncestorFn              func(parent string, child string) (bool, error)
	IsRebasingFn              func() (bool, error)
	LastCommitIDFn            func() (string, error)
	ListTagsFn                func() ([]TagMetadata, error)
	ListCommitsFn             func(opts *ListCommitsOptions) ([]CommitMetadata, error)
	CommitMessageFn           func(id string) (string, error)
	GetCommitSignatureInfoFn  func(string) (*CommitSignatureInfo, error)
	IntegrateRemoteChangesFn  func(*IntegrationOptions) error
	PullFn                    func(*PullOptions) error
	PushFn                    func(*PushOptions) error
	RefsHaveDiffsFn           func(commit1 string, commit2 string) (bool, error)
	RemoteBranchExistsFn      func(branch string) (bool, error)
	ResetHardFn               func() error
	URLFn                     func() string
	UpdateSubmodulesFn        func() error
}

type PullOptions struct {
	// Branch is the remote branch to pull from. If not specified, the current
	// branch will be pulled.
	Branch string
	// Force indicates whether the local branch should be reset to match
	// the remote exactly, discarding any local state.
	Force bool
}

type PushIntegrationPolicy string

type PushOptions struct {
	// Force indicates whether the push should be forced.
	Force bool
	// TargetBranch specifies the branch to push to. If empty, the current branch
	// TargetBranch specifies a remote branch to push to. If empty, the remote
	// branch's name will be assumed to be the same as the branch checked out
	// locally. Whether this field is empty or non-empty, if Tag is non-empty,
	// it takes precedence and the tag will be pushed -- the branch will not.
	TargetBranch string
	// IntegrationPolicy controls how remote changes are integrated before
	// pushing. If empty or set to PushIntegrationPolicyNone, no integration
	// is performed.
	IntegrationPolicy PushIntegrationPolicy
	// Tag specifies a tag to push to the remote repository. If this field and
	// TargetBranch are both non-empty, this field takes precedence and the tag
	// will be pushed -- the branch will not.
	Tag string
}

type Repo interface {
	// Close cleans up file system resources used by this repository. This should
	// always be called before a repository goes out of scope.
	Close() error
	// Dir returns an absolute path to the repository.
	Dir() string
	// HomeDir returns an absolute path to the home directory of the system user
	// who has cloned this repo.
	HomeDir() string
	// URL returns the remote URL of the repository as it was originally provided
	// when the repository was cloned.
	URL() string
	WorkTree
}

type RepoCredentials struct {
	// SSHPrivateKey is a private key that can be used for both reading from and
	// writing to some remote repository.
	//
	// TODO(v1.13.0): Remove this field when SSH support is removed.
	SSHPrivateKey string
	// 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
	// Password, when combined with the principal identified by the Username
	// field, can be used for both reading from and writing to some remote
	// repository.
	//
	// #nosec G117 -- This struct is never marshaled.
	Password string
}

type SigningKeyType string

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
	// Tagger is the person who created the tag, in the format "Name <email>".
	// This field is only populated for annotated tags.
	Tagger string
	// Annotation is the annotation of the tag, if it is an annotated tag.
	Annotation string
}

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
	// SigningKey is an optional string containing the raw signing key content.
	// If provided, it takes precedence over SigningKeyPath.
	SigningKey string
	// SigningKeyPath is an optional path referencing a signing key for
	// signing git objects. Ignored if SigningKey is provided.
	SigningKeyPath string
}

type WorkTree 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, commitOpts *CommitOptions) error
	// Clean cleans the working tree.
	Clean() error
	// Clear executes `git rm -rf .` to remove all files from the working tree.
	Clear() error
	// Close cleans up file system resources used by this working tree. This
	// should always be called before a WorkTree 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
	// CreateTag creates a new tag with the specified name.
	CreateTag(name, msg string) error
	// CurrentBranch returns the current branch
	CurrentBranch() (string, error)
	// DeleteBranch deletes the specified branch
	DeleteBranch(branch string) error
	// Dir returns an absolute path to the working tree.
	Dir() string
	// Fetch fetches updates from the remote repository.
	Fetch(opts *FetchOptions) error
	// HasDiffs returns a bool indicating whether the working tree currently
	// contains any differences from what's already at the head of the current
	// branch.
	HasDiffs() (bool, error)
	// HomeDir returns an absolute path to the home directory of the system user
	// who cloned the repo associated with this working tree.
	HomeDir() string
	// 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)
	// IsRebasing returns a bool indicating whether the working tree is currently
	// in the middle of a rebase operation.
	IsRebasing() (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(opts *ListCommitsOptions) ([]CommitMetadata, error)
	// CommitMessage returns the text of the most recent commit message associated
	// with the specified commit ID.
	CommitMessage(id string) (string, error)
	// GetCommitSignatureInfo returns signature information for the specified
	// commit, including whether it is signed by a trusted key and the
	// identity of the signer. If opts provides a SigningKey, a temporary
	// keyring is created with that key imported at ultimate trust and used
	// for verification.
	GetCommitSignatureInfo(commitID string) (*CommitSignatureInfo, error)
	// IntegrateRemoteChanges integrates remote changes into the local branch
	// before pushing. This fetches the target branch and applies the operator-
	// configured integration policy (rebase, merge, or fail). It is a no-op
	// if the remote branch does not exist or the policy is None.
	IntegrateRemoteChanges(*IntegrationOptions) error
	// Pull fetches and integrates changes from a remote branch
	// into the current local branch.
	Pull(*PullOptions) error
	// Push pushes from the local repository to the remote repository.
	Push(*PushOptions) 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 on the working tree.
	ResetHard() error
	// URL returns the remote URL of the repository.
	URL() string
	// UpdateSubmodules updates the submodules in the working tree.
	UpdateSubmodules() error
}