vcs

Documentation

Overview

Package vcs provides access to operations on the version control systems supported by the source field in module.cue.

Index

• func TestEnv() []string
• type Status
• type VCS
  • func New(vcsType string, dir string) (VCS, error)

Functions

func TestEnv

func TestEnv() []string

TestEnv builds an environment so that any executed VCS command with it won't be affected by the outer level environment.

Note that this function is exposed so we can reuse it from other test packages which also need to use Go tests with VCS systems. Exposing a test helper is fine for now, given this is an internal package.

Types

type Status

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

Status is the current state of a local repository.

type VCS

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)
}

VCS provides the operations on a particular instance of a VCS.

func New

func New(vcsType string, dir string) (VCS, error)

New returns a new VCS value representing the version control system of the given type that controls the given directory dir.

It returns an error if a VCS of the specified type cannot be found.