vcsstate

type NotFoundError struct {
	Err error // Underlying error with more details.
}

type RemoteVCS interface {
	// RemoteBranchAndRevision returns the name and latest revision of the default branch
	// from the remote. If the remote repository is not found, NotFoundError is returned.
	RemoteBranchAndRevision(remoteURL string) (branch string, revision string, err error)
}

type VCS interface {
	// Status returns the status of working directory.
	// It returns empty string if no outstanding status.
	Status(dir string) (string, error)

	// Branch returns the name of the locally checked out branch.
	Branch(dir string) (string, error)

	// LocalRevision returns current local revision of default branch.
	LocalRevision(dir string, defaultBranch string) (string, error)

	// Stash returns a non-empty string if the repository has a stash.
	Stash(dir string) (string, error)

	// Contains reports whether the local default branch contains
	// the commit specified by revision.
	Contains(dir string, revision string, defaultBranch string) (bool, error)

	// RemoteContains reports whether the remote default branch contains
	// the commit specified by revision.
	RemoteContains(dir string, revision string, defaultBranch string) (bool, error)

	// RemoteURL returns primary remote URL, as set in the local repository.
	// If there's no remote, then ErrNoRemote is returned.
	RemoteURL(dir string) (string, error)

	// RemoteBranchAndRevision returns the name and latest revision of the default branch
	// from the remote. If there's no remote, then ErrNoRemote is returned, and the
	// default branch can be queried with NoRemoteDefaultBranch.
	// If the remote repository is not found, NotFoundError is returned,
	// and the default branch can be queried with NoRemoteDefaultBranch.
	// This operation requires the use of network, and will fail if offline.
	// When offline, CachedRemoteDefaultBranch can be used as a fallback.
	RemoteBranchAndRevision(dir string) (branch string, revision string, err error)

	// CachedRemoteDefaultBranch returns a locally cached remote default branch,
	// if it can do so successfully. It can be used to make a best effort guess
	// of the remote default branch when offline. If it fails, the only viable
	// next best fallback before online again is to use NoRemoteDefaultBranch.
	CachedRemoteDefaultBranch() (string, error)

	// NoRemoteDefaultBranch returns the default value of default branch for this vcs.
	// It can only be relied on when there's no remote, since remote can have a custom
	// value of default branch.
	NoRemoteDefaultBranch() string
}