git

Documentation

Index

• Variables
• type AnnotatedTag
• type CloneToBucketOptions
• type Cloner
  • func NewCloner(logger *zap.Logger, storageosProvider storageos.Provider, ...) Cloner
• type ClonerOptions
• type Commit
• type Hash
  • func NewHashFromHex(value string) (Hash, error)
• type Ident
• type ListFilesAndUnstagedFilesOptions
• type Lister
  • func NewLister(runner command.Runner) Lister
• type Name
  • func NewBranchName(branch string) Name
  • func NewRefName(ref string) Name
  • func NewRefNameWithBranch(ref string, branch string) Name
  • func NewTagName(tag string) Name
• type ObjectMode
• type ObjectReader
• type OpenRepositoryOption
  • func OpenRepositoryWithBaseBranch(name string) OpenRepositoryOption
• type Repository
  • func OpenRepository(gitDirPath string, runner command.Runner, options ...OpenRepositoryOption) (Repository, error)
• type Tree
• type TreeNode

Variables

var (
	// ErrTreeNodeNotFound is an error found in the error chain when
	// Tree#Descendant is unable to find the target tree node.
	ErrTreeNodeNotFound = errors.New("node not found")
	// ErrTreeNodeNotFound is an error found in the error chain when
	// ObjectReader is unable to find the target object.
	ErrObjectNotFound = errors.New("object not found")
)

Types

type AnnotatedTag

type AnnotatedTag interface {
	// Hash is the Hash for this tag.
	Hash() Hash
	// Commit is the ID to the git commit that this tag points to.
	Commit() Hash
	// Tagger is the user who tagged the commit.
	Tagger() Ident
	// Name is the value of the tag.
	Name() string
	// Message is the commit message.
	Message() string
}

AnnotatedTag represents an annotated tag object.

type CloneToBucketOptions

type CloneToBucketOptions struct {
	Mapper            storage.Mapper
	Name              Name
	RecurseSubmodules bool
}

CloneToBucketOptions are options for Clone.

type Cloner

type Cloner interface {
	// CloneToBucket clones the repository to the bucket.
	//
	// The url must contain the scheme, including file:// if necessary.
	// depth must be > 0.
	CloneToBucket(
		ctx context.Context,
		envContainer app.EnvContainer,
		url string,
		depth uint32,
		writeBucket storage.WriteBucket,
		options CloneToBucketOptions,
	) error
}

Cloner clones git repositories to buckets.

func NewCloner

func NewCloner(
	logger *zap.Logger,
	storageosProvider storageos.Provider,
	runner command.Runner,
	options ClonerOptions,
) Cloner

NewCloner returns a new Cloner.

type ClonerOptions

type ClonerOptions struct {
	HTTPSUsernameEnvKey      string
	HTTPSPasswordEnvKey      string
	SSHKeyFileEnvKey         string
	SSHKnownHostsFilesEnvKey string
}

ClonerOptions are options for a new Cloner.

type Commit

type Commit interface {
	// Hash is the Hash for this commit.
	Hash() Hash
	// Tree is the ID to the git tree for this commit.
	Tree() Hash
	// Parents is the set of parents for this commit. It may be empty.
	//
	// By convention, the first parent in a multi-parent commit is the merge target.
	Parents() []Hash
	// Author is the user who authored the commit.
	Author() Ident
	// Committer is the user who created the commit.
	Committer() Ident
	// Message is the commit message.
	Message() string
}

Commit represents a commit object.

All commits will have a non-nil Tree. All but the root commit will contain >0 parents.

type Hash

type Hash interface {
	// Hex is the hexadecimal representation of this ID.
	Hex() string
	// String returns the hexadecimal representation of this ID.
	String() string
}

Hash represents the hash of a Git object (tree, blob, or commit).

func NewHashFromHex

func NewHashFromHex(value string) (Hash, error)

NewHashFromHex creates a new hash that is validated.

type Ident

type Ident interface {
	// Name is the name of the user.
	Name() string
	// Email is the email of the user.
	Email() string
	// Timestamp is the time at which this identity was created. For authors it's the
	// commit's author time, and for committers it's the commit's commit time.
	Timestamp() time.Time
}

Ident is a git user identifier. These typically represent authors and committers.

type ListFilesAndUnstagedFilesOptions

type ListFilesAndUnstagedFilesOptions struct {
	// IgnorePathRegexps are regexes of paths to ignore.
	//
	// These must be unnormalized in the manner of the local OS that the Lister
	// is being applied to.
	IgnorePathRegexps []*regexp.Regexp
}

ListFilesAndUnstagedFilesOptions are options for ListFilesAndUnstagedFiles.

type Lister

type Lister interface {
	// ListFilesAndUnstagedFiles lists all files checked into git except those that
	// were deleted, and also lists unstaged files.
	//
	// This does not list unstaged deleted files
	// This does not list unignored files that were not added.
	// This ignores regular files.
	//
	// This is used for situations like license headers where we want all the
	// potential git files during development.
	//
	// The returned paths will be unnormalized.
	//
	// This is the equivalent of doing:
	//
	//	comm -23 \
	//		<(git ls-files --cached --modified --others --no-empty-directory --exclude-standard | sort -u | grep -v -e IGNORE_PATH1 -e IGNORE_PATH2) \
	//		<(git ls-files --deleted | sort -u)
	ListFilesAndUnstagedFiles(
		ctx context.Context,
		envContainer app.EnvStdioContainer,
		options ListFilesAndUnstagedFilesOptions,
	) ([]string, error)
}

Lister lists files in git repositories.

func NewLister

func NewLister(runner command.Runner) Lister

NewLister returns a new Lister.

type Name

type Name interface {
	// contains filtered or unexported methods
}

Name is a name identifiable by git.

func NewBranchName

func NewBranchName(branch string) Name

NewBranchName returns a new Name for the branch.

func NewRefName

func NewRefName(ref string) Name

NewRefName returns a new Name for the ref.

func NewRefNameWithBranch

func NewRefNameWithBranch(ref string, branch string) Name

NewRefNameWithBranch returns a new Name for the ref while setting branch as the clone target.

func NewTagName

func NewTagName(tag string) Name

NewTagName returns a new Name for the tag.

type ObjectMode

type ObjectMode uint32

ObjectMode is how to interpret a tree node's object. See the Mode* constants for how to interpret each mode value.

const (
	// DotGitDir is a relative path to the `.git` directory.
	DotGitDir = ".git"

	// ModeUnknown is a mode's zero value.
	ModeUnknown ObjectMode = 0
	// ModeFile is a blob that should be written as a plain file.
	ModeFile ObjectMode = 0o10_0644
	// ModeExec is a blob that should be written with the executable bit set.
	ModeExe ObjectMode = 0o10_0755
	// ModeDir is a tree to be unpacked as a subdirectory in the current
	// directory.
	ModeDir ObjectMode = 0o04_0000
	// ModeSymlink is a blob with its content being the path linked to.
	ModeSymlink ObjectMode = 0o12_0000
	// ModeSubmodule is a commit that the submodule is checked out at.
	ModeSubmodule ObjectMode = 0o16_0000
)

type ObjectReader

type ObjectReader interface {
	// Blob reads the blob identified by the hash.
	Blob(id Hash) ([]byte, error)
	// Commit reads the commit identified by the hash.
	Commit(id Hash) (Commit, error)
	// Tree reads the tree identified by the hash.
	Tree(id Hash) (Tree, error)
	// Tag reads the tag identified by the hash.
	Tag(id Hash) (AnnotatedTag, error)
}

ObjectReader reads objects (commits, trees, blobs, tags) from a `.git` directory.

type OpenRepositoryOption

type OpenRepositoryOption func(*openRepositoryOpts) error

OpenRepositoryOption configures the opening of a repository.

func OpenRepositoryWithBaseBranch

func OpenRepositoryWithBaseBranch(name string) OpenRepositoryOption

CommitIteratorWithBaseBranch configures the base branch for this iterator.

type Repository

type Repository interface {
	// BaseBranch is the base branch of the repository. This is either configured
	// via the `OpenRepositoryWithBaseBranch` option, or discovered via the remote
	// named `origin`. Therefore, discovery requires that the repository is pushed
	// to the remote.
	BaseBranch() string
	// ForEachBranch ranges over branches in the repository in an undefined order.
	//
	// Only pushed (i.e., remote) branches are visited.
	ForEachBranch(func(branch string, headHash Hash) error) error
	// ForEachCommit ranges over commits for the target branch in reverse topological order.
	//
	// Only commits pushed to the 'origin' remote are visited.
	//
	// Parents are visited before children, and only left parents are visited (i.e.,
	// commits from branches merged into the target branch are not visited).
	ForEachCommit(branch string, f func(commit Commit) error) error
	// ForEachTag ranges over tags in the repository in an undefined order.
	//
	// All tags are ranged, including local (unpushed) tags.
	ForEachTag(func(tag string, commitHash Hash) error) error
	// Objects exposes the underlying object reader to read objects directly from the
	// `.git` directory.
	Objects() ObjectReader
	// Close closes the repository.
	Close() error
}

Repository is a git repository that is backed by a `.git` directory.

func OpenRepository

func OpenRepository(gitDirPath string, runner command.Runner, options ...OpenRepositoryOption) (Repository, error)

OpenRepository opens a new Repository from a `.git` directory. The provided path to the `.git` dir need not be normalized or cleaned.

Internally, OpenRepository will spawns a new process to communicate with `git-cat-file`, so the caller must close the repository to clean up resources.

By default, OpenRepository will attempt to detect the base branch if the repository has been pushed. This may fail if the repository is not pushed. In this case, use the `OpenRepositoryWithBaseBranch` option.

type Tree

type Tree interface {
	// Hash is the Hash for this Tree.
	Hash() Hash
	// Nodes is the set of nodes in this Tree.
	Nodes() []TreeNode
	// Descendant walks down a tree, following the path specified,
	// and returns the terminal Node. If no node is found, it returns
	// ErrTreeNodeNotFound.
	Descendant(path string, objectReader ObjectReader) (TreeNode, error)
}

Tree is a git tree, which are a manifest of other git objects, including other trees.

type TreeNode

type TreeNode interface {
	// Hash is the Hash of the object referenced by this Node.
	Hash() Hash
	// Name is the name of the object referenced by this Node.
	Name() string
	// Mode is the file mode of the object referenced by this Node.
	Mode() ObjectMode
}

TreeNode is a reference to an object contained in a tree. These objects have a file mode associated with them, which hints at the type of object located at ID (tree or blob).