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.

Package git is a generated GoMock package.

Index

• func ProjectFromContext(ctx context.Context) (string, bool)
• 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
  • func NewClient(acls *gitacls.ACLs) Client
• type LogOptions
• type MockClient
  • func NewMockClient(ctrl *gomock.Controller) *MockClient
  • func (m *MockClient) CLEmail(c context.Context, host string, changeNumber int64) (string, error)
  • func (m *MockClient) CombinedLogs(c context.Context, host, project, excludeRef string, refs []string, limit int) ([]*git.Commit, error)
  • func (m *MockClient) EXPECT() *MockClientMockRecorder
  • func (m *MockClient) Log(c context.Context, host, project, commitish string, inputOptions *LogOptions) ([]*git.Commit, error)
• type MockClientMockRecorder
  • func (mr *MockClientMockRecorder) CLEmail(c, host, changeNumber interface{}) *gomock.Call
  • func (mr *MockClientMockRecorder) CombinedLogs(c, host, project, excludeRef, refs, limit interface{}) *gomock.Call
  • func (mr *MockClientMockRecorder) Log(c, host, project, commitish, inputOptions interface{}) *gomock.Call

Functions

func ProjectFromContext

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

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.

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/main" 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.

func NewClient

func NewClient(acls *gitacls.ACLs) Client

NewClient returns a new production Client.

type LogOptions

type LogOptions struct {
	Limit     int
	WithFiles bool
}

LogOptions are options for Log function.

type MockClient

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

MockClient is a mock of Client interface.

func NewMockClient

func NewMockClient(ctrl *gomock.Controller) *MockClient

NewMockClient creates a new mock instance.

func (*MockClient) CLEmail

func (m *MockClient) CLEmail(c context.Context, host string, changeNumber int64) (string, error)

CLEmail mocks base method.

func (*MockClient) CombinedLogs

func (m *MockClient) CombinedLogs(c context.Context, host, project, excludeRef string, refs []string, limit int) ([]*git.Commit, error)

CombinedLogs mocks base method.

func (*MockClient) EXPECT

func (m *MockClient) EXPECT() *MockClientMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockClient) Log

func (m *MockClient) Log(c context.Context, host, project, commitish string, inputOptions *LogOptions) ([]*git.Commit, error)

Log mocks base method.

type MockClientMockRecorder

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

MockClientMockRecorder is the mock recorder for MockClient.

func (*MockClientMockRecorder) CLEmail

func (mr *MockClientMockRecorder) CLEmail(c, host, changeNumber interface{}) *gomock.Call

CLEmail indicates an expected call of CLEmail.

func (*MockClientMockRecorder) CombinedLogs

func (mr *MockClientMockRecorder) CombinedLogs(c, host, project, excludeRef, refs, limit interface{}) *gomock.Call

CombinedLogs indicates an expected call of CombinedLogs.

func (*MockClientMockRecorder) Log

func (mr *MockClientMockRecorder) Log(c, host, project, commitish, inputOptions interface{}) *gomock.Call

Log indicates an expected call of Log.