git

Documentation

Index

• func NewCensoringExecutor(dir string, censor Censor, logger *logrus.Entry) (executor, error)
• type Censor
• type ClientFactory
  • func NewClientFactory(opts ...ClientFactoryOpt) (ClientFactory, error)
  • func NewLocalClientFactory(baseDir string, gitUser GitUserGetter, censor Censor) (ClientFactory, error)
• type ClientFactoryOpt
• type ClientFactoryOpts
  • func (cfo *ClientFactoryOpts) Apply(target *ClientFactoryOpts)
• type ForkRemoteResolver
• type GitUserGetter
• type Interactor
• type LoginGetter
• type MergeOpt
• type Publisher
• type RemoteResolver
• type RemoteResolverFactory
• type RepoClient
• type RepoOpts
• type TokenGetter

Functions

func NewCensoringExecutor

func NewCensoringExecutor(dir string, censor Censor, logger *logrus.Entry) (executor, error)

Types

type Censor

type Censor func(content []byte) []byte

Censor censors content to remove secrets

type ClientFactory

type ClientFactory interface {
	// ClientFromDir creates a client that operates on a repo that has already
	// been cloned to the given directory.
	ClientFromDir(org, repo, dir string) (RepoClient, error)
	// ClientFor creates a client that operates on a new clone of the repo.
	ClientFor(org, repo string) (RepoClient, error)
	// ClientForWithRepoOpts is like ClientFor, but allows you to customize the
	// setup of the cloned repo (such as sparse checkouts instead of using the
	// default full clone).
	ClientForWithRepoOpts(org, repo string, repoOpts RepoOpts) (RepoClient, error)

	// Clean removes the caches used to generate clients
	Clean() error
}

ClientFactory knows how to create clientFactory for repos

func NewClientFactory

func NewClientFactory(opts ...ClientFactoryOpt) (ClientFactory, error)

NewClientFactory allows for the creation of repository clients. It uses github.com without authentication by default, if UseSSH then returns sshRemoteResolverFactory, and if CookieFilePath is provided then returns gerritResolverFactory(Assuming that git http.cookiefile is used only by Gerrit, this function needs to be updated if it turned out that this assumtpion is not correct.)

func NewLocalClientFactory

func NewLocalClientFactory(baseDir string, gitUser GitUserGetter, censor Censor) (ClientFactory, error)

NewLocalClientFactory allows for the creation of repository clients based on a local filepath remote for testing

type ClientFactoryOpt

type ClientFactoryOpt func(*ClientFactoryOpts)

ClientFactoryOpts allows to manipulate the options for a ClientFactory

type ClientFactoryOpts

type ClientFactoryOpts struct {
	// Host, defaults to "github.com" if unset
	Host string
	// Whether to use HTTP. By default, HTTPS is used (overrides UseSSH).
	//
	// TODO (listx): Combine HTTPS, HTTP, and SSH schemes into a single enum.
	UseInsecureHTTP *bool
	// UseSSH, defaults to false
	UseSSH *bool
	// The directory in which the cache should be
	// created. Defaults to the "/var/tmp" on
	// Linux and os.TempDir otherwise
	CacheDirBase *string
	// If unset, publishing action will error
	Username LoginGetter
	// If unset, publishing action will error
	Token TokenGetter
	// The git user to use.
	GitUser GitUserGetter
	// The censor to use. Not needed for anonymous
	// actions.
	Censor Censor
	// Path to the httpCookieFile that will be used to authenticate client
	CookieFilePath string
	// If set, cacheDir persist. Otherwise temp dir will be used for CacheDir
	Persist *bool
}

func (*ClientFactoryOpts) Apply

func (cfo *ClientFactoryOpts) Apply(target *ClientFactoryOpts)

Apply allows to use a ClientFactoryOpts as Opt

type ForkRemoteResolver

type ForkRemoteResolver func(forkName string) (string, error)

ForkRemoteResolver knows how to construct a remote URL for git calls It accepts a fork name since this may be different than the parent repo name. If the forkName is "", the parent repo name is assumed.

type GitUserGetter

type GitUserGetter func() (name, email string, err error)

GitUserGetter fetches a name and email for us in git commits on-demand

type Interactor

type Interactor interface {
	// Directory exposes the directory in which the repository has been cloned
	Directory() string
	// Clean removes the repository. It is up to the user to call this once they are done
	Clean() error
	// ResetHard runs `git reset --hard`
	ResetHard(commitlike string) error
	// IsDirty checks whether the repo is dirty or not
	IsDirty() (bool, error)
	// Checkout runs `git checkout`
	Checkout(commitlike string) error
	// RevParse runs `git rev-parse`
	RevParse(commitlike string) (string, error)
	// RevParseN runs `git rev-parse`, but takes a slice of git revisions, and
	// returns a map of the git revisions as keys and the SHAs as values.
	RevParseN(rev []string) (map[string]string, error)
	// BranchExists determines if a branch with the name exists
	BranchExists(branch string) bool
	// ObjectExists determines if the Git object exists locally
	ObjectExists(sha string) (bool, error)
	// CheckoutNewBranch creates a new branch from HEAD and checks it out
	CheckoutNewBranch(branch string) error
	// Merge merges the commitlike into the current HEAD
	Merge(commitlike string) (bool, error)
	// MergeWithStrategy merges the commitlike into the current HEAD with the strategy
	MergeWithStrategy(commitlike, mergeStrategy string, opts ...MergeOpt) (bool, error)
	// MergeAndCheckout merges all commitlikes into the current HEAD with the appropriate strategy
	MergeAndCheckout(baseSHA string, mergeStrategy string, headSHAs ...string) error
	// Am calls `git am`
	Am(path string) error
	// Fetch calls `git fetch arg...`
	Fetch(arg ...string) error
	// FetchRef fetches the refspec
	FetchRef(refspec string) error
	// FetchFromRemote fetches the branch of the given remote
	FetchFromRemote(remote RemoteResolver, branch string) error
	// CheckoutPullRequest fetches and checks out the synthetic refspec from GitHub for a pull request HEAD
	CheckoutPullRequest(number int) error
	// Config runs `git config`
	Config(args ...string) error
	// Diff runs `git diff`
	Diff(head, sha string) (changes []string, err error)
	// MergeCommitsExistBetween determines if merge commits exist between target and HEAD
	MergeCommitsExistBetween(target, head string) (bool, error)
	// ShowRef returns the commit for a commitlike. Unlike rev-parse it does not require a checkout.
	ShowRef(commitlike string) (string, error)
}

Interactor knows how to operate on a git repository cloned from GitHub using a local cache.

type LoginGetter

type LoginGetter func() (login string, err error)

LoginGetter fetches a GitHub login on-demand

type MergeOpt

type MergeOpt struct {
	CommitMessage string
}

MergeOpt holds options for git merge operations. Currently only commit message option is supported.

type Publisher

type Publisher interface {
	// Commit stages all changes and commits them with the message
	Commit(title, body string) error
	// PushToFork pushes the local state to the fork remote
	PushToFork(branch string, force bool) error
	// PushToNamedFork is used for when the fork has a different name than the original repp
	PushToNamedFork(forkName, branch string, force bool) error
	// PushToCentral pushes the local state to the central remote
	PushToCentral(branch string, force bool) error
}

Publisher knows how to publish local work to a remote

type RemoteResolver

type RemoteResolver func() (string, error)

RemoteResolver knows how to construct a remote URL for git calls

type RemoteResolverFactory

type RemoteResolverFactory interface {
	// CentralRemote returns a resolver for a remote server with an
	// authoritative version of the repository. This type of remote
	// is useful for fetching refs and cloning.
	CentralRemote(org, repo string) RemoteResolver
	// PublishRemote returns a resolver for a remote server with a
	// personal fork of the central repository. This type of remote is most
	// useful for publishing local changes.
	PublishRemote(org, centralRepo string) ForkRemoteResolver
}

RemoteResolverFactory knows how to construct remote resolvers for authoritative central remotes (to pull from) and publish remotes (to push to) for a repository. These resolvers are called at run-time to determine remotes for git commands.

type RepoClient

type RepoClient interface {
	Publisher
	Interactor
}

RepoClient exposes interactions with a git repo

type RepoOpts

type RepoOpts struct {
	// sparseCheckoutDirs is the list of directories that the working tree
	// should have. If non-nil and empty, then the working tree only has files
	// reachable from the root. If non-nil and non-empty, then those additional
	// directories from the root are also checked out (populated) in the working
	// tree, recursively.
	SparseCheckoutDirs []string
	// This is the `--share` flag to `git clone`. For cloning from a local
	// source, it allows bypassing the copying of all objects. If this is true,
	// you must also set NeededCommits to a non-empty value; otherwise, when the
	// primary is updated with RemoteUpdate() the `--prune` flag may end up
	// deleting objects in the primary (which could adversely affect the
	// secondary).
	ShareObjectsWithPrimaryClone bool
	// NeededCommits list only those commit SHAs which are needed. If the commit
	// already exists, it is not fetched to save network costs. If NeededCommits
	// is set, we do not call RemoteUpdate() for the primary clone (git cache).
	NeededCommits sets.Set[string]
	// BranchesToRetarget contains a map of branch names mapped to SHAs. These
	// branch name and SHA pairs will be fed into RetargetBranch in the git v2
	// client, to update the current HEAD of each branch.
	BranchesToRetarget map[string]string
}

These options are scoped to the repo, not the ClientFactory level. The reason for the separation is to allow a single process to have for example repos that are both sparsely checked out and non-sparsely checked out.

type TokenGetter

type TokenGetter func(org string) (string, error)

TokenGetter fetches a GitHub OAuth token on-demand