vcs

type Status struct {
	Revision    string    // Optional.
	CommitTime  time.Time // Optional.
	Uncommitted bool      // Required.
}

type VCS interface {
	// Root returns the root of the directory controlled by
	// the VCS (e.g. the directory containing .git).
	Root() string

	// ListFiles returns a list of files tracked by VCS, rooted at dir. The
	// optional paths determine what should be listed. If no paths are provided,
	// then all of the files under VCS control under dir are returned. An empty
	// dir is interpretted as [VCS.Root]. A non-empty relative dir is
	// interpretted relative to [VCS.Root]. It us up to the caller to ensure
	// that dir and paths are contained by the VCS root Filepaths are relative
	// to dir and returned in lexical order.
	//
	// Note that ListFiles is generally silent in the case an arg is provided
	// that does correspond to a VCS-controlled file. For example, calling
	// with an arg of "BANANA" where no such file is controlled by VCS will
	// result in no filepaths being returned.
	ListFiles(ctx context.Context, dir string, paths ...string) ([]string, error)

	// Status returns the current state of the repository holding the given paths.
	// If paths is not provided it implies the state of
	// the VCS repository in its entirety, including untracked files. paths are
	// interpretted relative to the [VCS.Root].
	Status(ctx context.Context, paths ...string) (Status, error)
}