gitstore

README

Git Store

Git abstraction layer written in Go, mainly for use in Kubernetes Controllers.

Git Store is based on Go Git and provides convenience methods for cloning, fetching and checking out repository references and accessing file contents within a repository.

Usage

To get a slice of all yaml and json file from a repository at a given reference:

func getFilesFromRepo(url string, privateKey []byte, gitReference string) ([]*gitstore.File, error) {
	store := gitstore.NewRepoStore()

	repo, err := store.Get(&gistore.RepoRef{
		URL: 		url,
		PrivateKey:	privateKey,
	})

	err = repo.Checkout(gitReference)

	globbedSubPath := strings.TrimPrefix(gt.Spec.SubPath, "/") + "{**/*,*}.{yaml,yml,json}"
	files, err := repo.GetAllFiles(globbedSubPath, true)
	return files, err
}

Then, to work with these files:

files, err := getFilesFromRepo("git@github.com:/...", someKey, "master")

for file := range files {
	doStuffWith(file.Contents())
}

Communication

• Found a bug? Please open an issue.
• Have a feature request. Please open an issue.
• If you want to contribute, please submit a pull request

Contributing

Please see our Contributing guidelines.

License

This project is licensed under Apache 2.0 and a copy of the license is available here.

Documentation

Overview

Package gitstore provides an abstraction on top of Go Git for use with (primarily) Kubernetes Controllers. It has basic caching capabilities and can handle multiple repositories at the same time.

The primary purpose of GitStore is to give easy access to the files in the repository at a certain git reference. To that end it checks out the code into a temporary in-memory filesystem.

Index

• type AsyncRepoCloner
  • func (rc *AsyncRepoCloner) Clone(auth transport.AuthMethod) <-chan struct{}
• type File
  • func (f *File) Contents() string
  • func (f *File) FileLog() (GitLog, error)
• type GitLog
• type Repo
  • func (r *Repo) Checkout(ref string) error
  • func (r *Repo) CheckoutContext(ctx context.Context, ref string) error
  • func (r *Repo) Fetch() error
  • func (r *Repo) FetchContext(ctx context.Context) error
  • func (r *Repo) GetAllFiles(subPath string, ignoreSymlinks bool) (map[string]*File, error)
  • func (r *Repo) GetFile(path string) (*File, error)
  • func (r *Repo) IsDirectory(path string) (bool, error)
  • func (r *Repo) IsFile(path string) (bool, error)
  • func (r *Repo) LastUpdated() (time.Time, error)
• type RepoRef
  • func (r *RepoRef) Validate() error
• type RepoStore
  • func NewRepoStore(repoDir string) *RepoStore
  • func (rs *RepoStore) Get(ref *RepoRef) (*Repo, error)
  • func (rs *RepoStore) GetAsync(ref *RepoRef) (*AsyncRepoCloner, <-chan struct{}, error)

Types

type AsyncRepoCloner

type AsyncRepoCloner struct {
	Ready   bool     // Ready indicates whether the clone operation has completed.
	RepoRef *RepoRef // RepoRef is a pointer to the RepoRef handled by this cloner.
	Repo    *Repo    // Repo contains the actual repository once clone has completed.
	Error   error    // Error is the last error encountered during the clone operation or nil.
	// contains filtered or unexported fields
}

AsyncRepoCloner provides an asynchronous repository cloner that can perform long-running checkout operations without blocking.

func (*AsyncRepoCloner) Clone

func (rc *AsyncRepoCloner) Clone(auth transport.AuthMethod) <-chan struct{}

Clone starts an asynchronous clone of the requested repository and sets Ready to true when the repository is cloned successfully. If any errors are encountered, Ready will be false and Error will contain the error information.

type File

type File struct {
	// contains filtered or unexported fields
}

File represents a file within a git repository.

func (*File) Contents

func (f *File) Contents() string

Contents returns the content of the File as a string.

Note: Contents() does not verify file type and will return binary files as a (probably useless) string representation. It reads the contents in memory, so may suffer from problems if the file size is too large.

func (*File) FileLog

func (f *File) FileLog() (GitLog, error)

FileLog returns the file log for the current file.

type GitLog

type GitLog struct {
	Date   time.Time     // Date is the datetime of the commit this log corresponds to.
	Hash   plumbing.Hash // Hash contains the hash of the commit.
	Author string        // Author is the author as stored in the commit.
	Text   string        // Text is the commit message.
}

GitLog contains information about a commit from the git repository log.

type Repo

type Repo struct {
	// contains filtered or unexported fields
}

Repo represents a git repository.

func (*Repo) Checkout

func (r *Repo) Checkout(ref string) error

Checkout performs a Git checkout of the repository at the provided reference.

Note: It is assumed that the repository has already been cloned prior to Checkout() being called.

func (*Repo) CheckoutContext

func (r *Repo) CheckoutContext(ctx context.Context, ref string) error

CheckoutContext performs a Git checkout of the repository at the provided reference.

Note: It is assumed that the repository has already been cloned prior to Checkout() being called.

func (*Repo) Fetch

func (r *Repo) Fetch() error

Fetch performs a Git fetch of the repository.

Note: While Fetch itself is thread-safe in that it ensures a previous Fetch() is completed before starting a new one, the Repo is not. If Fetch is called from two go routines, subsequent reads may be non-deterministic.

func (*Repo) FetchContext

func (r *Repo) FetchContext(ctx context.Context) error

FetchContext performs a Git fetch of the repository.

Note: While Fetch itself is thread-safe in that it ensures a previous Fetch() is completed before starting a new one, the Repo is not. If Fetch is called from two go routines, subsequent reads may be non-deterministic.

func (*Repo) GetAllFiles

func (r *Repo) GetAllFiles(subPath string, ignoreSymlinks bool) (map[string]*File, error)

GetAllFiles returns a map of Files. Each file is keyed in the map by it's path within the repository

func (*Repo) GetFile

func (r *Repo) GetFile(path string) (*File, error)

GetFile returns a pointer to a File from the repository that can be used to read its contents.

func (*Repo) IsDirectory

func (r *Repo) IsDirectory(path string) (bool, error)

IsDirectory checks if the reference at a path if a directory

func (*Repo) IsFile

func (r *Repo) IsFile(path string) (bool, error)

IsFile checks if the reference at a path if a regular file

func (*Repo) LastUpdated

func (r *Repo) LastUpdated() (time.Time, error)

LastUpdated returns the timestamp that the currently checked out reference was last updated at.

type RepoRef

type RepoRef struct {
	URL        string // URL where the repository is located
	User       string // User is the username used for user/pass authentication
	Pass       string // Pass is the password used for user/pass authentication
	PrivateKey []byte // PrivateKey is the ssh key material used for SSH key-based authentication
	// contains filtered or unexported fields
}

RepoRef contains all information required to connect to a git repository

func (*RepoRef) Validate

func (r *RepoRef) Validate() error

Validate validates the repository url format. If the url contains auth credentials and none are provided explicitly, the relevant fields of the RepoRef are filled.

type RepoStore

type RepoStore struct {
	// contains filtered or unexported fields
}

RepoStore manages a collection of git repositories.

func NewRepoStore

func NewRepoStore(repoDir string) *RepoStore

NewRepoStore initializes a new RepoStore.

func (*RepoStore) Get

func (rs *RepoStore) Get(ref *RepoRef) (*Repo, error)

Get retrieves a Repo from the RepoStore

func (*RepoStore) GetAsync

func (rs *RepoStore) GetAsync(ref *RepoRef) (*AsyncRepoCloner, <-chan struct{}, error)

GetAsync returns an AsyncRepoCloner that will retrieve a Repo in the background according to the RepoRef provided.