git

Documentation

Overview

Package git provides high level API for Git/Gerrit data.

Features:

It enforces read ACLs on Git/Gerrit hosts/projects configured in
  settings.cfg in source_acls blocks.
Transparently caches results respecting ACLs above.
  That's why no caching of returned data should be done by callers.

Limitations:

currently, only works with *.googlesource.com hosted Git/Gerrit
repositories, but could be extended to work with other providers.

Index

• func ProjectFromContext(ctx context.Context) (string, error)
• func Use(c context.Context, s Client) context.Context
• func UseACLs(c context.Context, acls *gitacls.ACLs) context.Context
• func WithProject(ctx context.Context, project string) context.Context
• type Client
  • func Get(c context.Context) Client
• type LogOptions

Functions

func ProjectFromContext

func ProjectFromContext(ctx context.Context) (string, error)

ProjectFromContext is the opposite of WithProject, is extracts the LUCI project which the current call stack is handling a request for.

func Use

func Use(c context.Context, s Client) context.Context

Use returns context with provided Client implementation.

Useful in tests, see also gittest.MockClient

func UseACLs

func UseACLs(c context.Context, acls *gitacls.ACLs) context.Context

UseACLs returns context with production implementation installed.

func WithProject

func WithProject(ctx context.Context, project string) context.Context

WithProject annotates the context object with the LUCI project that a request is handled for.

Types

type Client

type Client interface {

	// Log returns ancestors commits of the given repository host
	// (e.g. "chromium.googlesource.com"), project (e.g. "chromium/src")
	// and descendant committish (e.g. "refs/heads/master" or commit hash).
	//
	// Limit specifies the maximum number of commits to return.
	// If limit<=0, 50 is used.
	// Setting a lower value increases cache hit probability.
	//
	// May return gRPC errors returned by the underlying Gitiles service.
	Log(c context.Context, host, project, commitish string, inputOptions *LogOptions) ([]*gitpb.Commit, error)

	// CombinedLogs returns latest commits reachable from several refs.
	//
	// Returns a slice of up to a limit (defaults to 50 when <= 0) commits that:
	//  * for each source ref, subsequence of returned slice formed by
	//    its corresponding commits will be in the same order,
	//  * across refs, commits will be ordered by timestamp, and
	//  * identical commits from multiple commits will be deduped.
	//
	// For example, for two refs with commits (C_5 means C was committed at time
	// 5) and limit 5, the function will first resolve each ref to sequence of
	// commits:
	//
	//    ref1: A_1 -> B_5 -> C_9
	//    ref2: X_2 -> Y_7 -> Z_4    (note timestamp inversion)
	//
	// and then return combined list of [C_9, B_5, Z_4, Y_7, X_2].
	//
	// refs must be a list of ref specs as described in the proto config (see
	// doc for refs field in the Console message in api/config/project.proto)
	//
	// excludeRef can be set to non-empty value to exclude commits from a specific
	// ref, e.g. this is useful when requesting commits from branches that branch
	// off a single main branch, commits from which should not be returned even
	// though they are present in the history of each requested branch
	CombinedLogs(c context.Context, host, project, excludeRef string,
		refs []string, limit int) (commits []*gitpb.Commit, err error)

	// CLEmail fetches the CL owner email.
	//
	// Returns empty string if either:
	//   CL doesn't exist, or
	//   current user has no access to CL's project.
	//
	// May return gRPC errors returned by the underlying Gerrit service.
	CLEmail(c context.Context, host string, changeNumber int64) (string, error)
}

Client provides high level API for Git/Gerrit data.

Methods may return grpc errors returned by the underlying Gitiles service. These errors will be annotated with Milo's error tags whenever reasonable.

func Get

func Get(c context.Context) Client

Get returns Client set in supplied context.

panics if not set.

type LogOptions

type LogOptions struct {
	Limit     int
	WithFiles bool
}

LogOptions are options for Log function.