git

Documentation

Index

• Variables
• type AnnotatedTag
• type CheckedOutBranchOption
  • func CheckedOutBranchWithRemote(remoteName string) CheckedOutBranchOption
• type CloneToBucketOptions
• type Cloner
  • func NewCloner(logger *zap.Logger, storageosProvider storageos.Provider, ...) Cloner
• type ClonerOptions
• type Commit
• type ForEachBranchOption
  • func ForEachBranchWithRemote(remoteName string) ForEachBranchOption
• type ForEachCommitOption
  • func ForEachCommitWithBranchStartPoint(branchName string, options ...ForEachCommitWithBranchStartPointOption) ForEachCommitOption
  • func ForEachCommitWithHashStartPoint(hash string) ForEachCommitOption
• type ForEachCommitWithBranchStartPointOption
  • func ForEachCommitWithBranchStartPointWithRemote(remoteName string) ForEachCommitWithBranchStartPointOption
• type HEADCommitOption
  • func HEADCommitWithBranch(branchName string) HEADCommitOption
  • func HEADCommitWithRemote(remoteName string) HEADCommitOption
• 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 OpenRepositoryWithDefaultBranch(name string) OpenRepositoryOption
• type Repository
  • func OpenRepository(ctx context.Context, gitDirPath string, runner command.Runner, ...) (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")
	// ErrStopForEach is provided for callers to use it when they want to gracefully stop a ForEach*
	// function. It is not returned as an error by any function.
	ErrStopForEach = errors.New("stop for each loop")
)

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 CheckedOutBranchOption

type CheckedOutBranchOption func(*checkedOutBranchOpts)

CheckedOutBranchOption are options that can be passed to CheckedOutBranch.

func CheckedOutBranchWithRemote

func CheckedOutBranchWithRemote(remoteName string) CheckedOutBranchOption

CheckedOutBranchWithRemote sets the function to only loop over branches present in the passed remote at their respective HEADs.

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
	// String outputs the Author timestamp and Hex.
	String() string
}

Commit represents a commit object.

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

type ForEachBranchOption

type ForEachBranchOption func(*forEachBranchOpts)

ForEachBranchOption are options that can be passed to ForEachBranch.

func ForEachBranchWithRemote

func ForEachBranchWithRemote(remoteName string) ForEachBranchOption

ForEachBranchWithRemote sets the function to only loop over branches present in the passed remote at their respective HEADs.

type ForEachCommitOption

type ForEachCommitOption func(*forEachCommitOpts)

ForEachCommitOption are options that can be passed to ForEachCommit.

func ForEachCommitWithBranchStartPoint

func ForEachCommitWithBranchStartPoint(branchName string, options ...ForEachCommitWithBranchStartPointOption) ForEachCommitOption

ForEachCommitWithBranchStartPoint sets a branch as a starting point to start the loop.

func ForEachCommitWithHashStartPoint

func ForEachCommitWithHashStartPoint(hash string) ForEachCommitOption

ForEachCommitWithHashStartPoint sets a git hash as a starting point to start the loop.

type ForEachCommitWithBranchStartPointOption

type ForEachCommitWithBranchStartPointOption func(*forEachCommitWithBranchStartPointOpts)

func ForEachCommitWithBranchStartPointWithRemote

func ForEachCommitWithBranchStartPointWithRemote(remoteName string) ForEachCommitWithBranchStartPointOption

ForEachCommitWithBranchStartPointWithRemote uses the remote position for the branch, instead of the local position.

type HEADCommitOption

type HEADCommitOption func(*headCommitOpts)

HEADCommitOption are options that can be passed to HEADCommit.

func HEADCommitWithBranch

func HEADCommitWithBranch(branchName string) HEADCommitOption

HEADCommitWithBranch sets the function to return the HEAD commit for a specific branch instead of the default branch.

func HEADCommitWithRemote

func HEADCommitWithRemote(remoteName string) HEADCommitOption

HEADCommitWithRemote sets the function to return the HEAD commit for the branch that is present in the passed remote.

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 = 010_0644
	// ModeExec is a blob that should be written with the executable bit set.
	ModeExe ObjectMode = 010_0755
	// ModeDir is a tree to be unpacked as a subdirectory in the current
	// directory.
	ModeDir ObjectMode = 004_0000
	// ModeSymlink is a blob with its content being the path linked to.
	ModeSymlink ObjectMode = 012_0000
	// ModeSubmodule is a commit that the submodule is checked out at.
	ModeSubmodule ObjectMode = 016_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 OpenRepositoryWithDefaultBranch

func OpenRepositoryWithDefaultBranch(name string) OpenRepositoryOption

OpenRepositoryWithDefaultBranch configures the default branch for this repository.

type Repository

type Repository interface {
	// DefaultBranch is the default branch of the repository. By default this reads the value in
	// `.git/refs/remotes/origin/HEAD` (assuming the default branch has been already pushed to a
	// remote named `origin`). It can be customized via the `OpenRepositoryWithDefaultBranch` option.
	DefaultBranch() string
	// CheckedOutBranch returns the current checked out branch.
	CheckedOutBranch(options ...CheckedOutBranchOption) (string, error)
	// ForEachBranch ranges over branches in the repository in an undefined order.
	ForEachBranch(f func(branch string, headHash Hash) error, options ...ForEachBranchOption) error
	// ForEachCommit ranges over commits in reverse topological order, going backwards in time always
	// choosing the first parent, until no more parents are found (presumably the first commit of the
	// git repository).
	//
	// The range starts by default at the HEAD commit for the default branch. You can customize this
	// starting point by passing options.
	//
	// If an error is seen, the loop is stopped and the error is returned.
	ForEachCommit(f func(commit Commit) error, options ...ForEachCommitOption) error
	// HEADCommit returns by default the HEAD commit at the default branch. You can customize this by
	// passing options.
	HEADCommit(options ...HEADCommitOption) (Commit, error)
	// ForEachTag ranges over tags in the repository in an undefined order.
	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(ctx context.Context, 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 default branch if the repository has been pushed to a remote named `origin`. This may fail if the repository is not pushed, in this case, use the `OpenRepositoryWithDefaultBranch` 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).