gitiles

Documentation

Overview

Package gitiles implements GitilesClient in "go.chromium.org/common/proto/gitiles" package on top of Gitiles's REST API.

Additionally provides some useful functionality on top of that API. It allows querying Git repositories hosted on *.googlesource.com.

Index

• Constants
• func FormatRepoURL(host, project string, auth bool) url.URL
• func NewRESTClient(httpClient *http.Client, host string, auth bool) (gitiles.GitilesClient, error)
• func NormalizeRepoURL(repoURL string, auth bool) (*url.URL, error)
• func PagingLog(ctx context.Context, client gitiles.GitilesClient, req gitiles.LogRequest, ...) ([]*git.Commit, error)
• func ParseRepoURL(repoURL string) (host, project string, err error)
• func ValidateRefSet(c *validation.Context, refs []string)
• func ValidateRepoURL(repoURL string) error
• type RefSet
  • func NewRefSet(refs []string) RefSet
  • func (w RefSet) Has(ref string) bool
  • func (w RefSet) Resolve(c context.Context, client gitiles.GitilesClient, project string) (refTips map[string]string, missingRefs []string, err error)

Constants

const DefaultLimit = 1000

DefaultLimit is the default maximum number of commits to load. It is used in PagingLog.

const OAuthScope = "https://www.googleapis.com/auth/gerritcodereview"

OAuthScope is the OAuth 2.0 scope that must be included when acquiring an access token for Gitiles RPCs.

Functions

func FormatRepoURL

func FormatRepoURL(host, project string, auth bool) url.URL

FormatRepoURL returns a canonical gitiles URL of the repo. If auth is true, the returned URL has "/a/" path prefix. See also ParseRepoURL.

func NewRESTClient

func NewRESTClient(httpClient *http.Client, host string, auth bool) (gitiles.GitilesClient, error)

NewRESTClient creates a new Gitiles client based on Gitiles's REST API.

The host must be a full Gitiles host, e.g. "chromium.googlesource.com".

If auth is true, indicates that the given HTTP client sends authenticated requests. If so, the requests to Gitiles will include "/a/" URL path prefix.

RPC methods of the returned client return an error if a grpc.CallOption is passed.

func NormalizeRepoURL

func NormalizeRepoURL(repoURL string, auth bool) (*url.URL, error)

NormalizeRepoURL is a shortcut for ParseRepoURL and FormatRepoURL.

func PagingLog

func PagingLog(ctx context.Context, client gitiles.GitilesClient, req gitiles.LogRequest, limit int, opts ...grpc.CallOption) ([]*git.Commit, error)

PagingLog is a wrapper around Gitiles.Log RPC that pages though commits. If req.PageToken is not empty, paging will continue from there.

req.PageSize specifies maximum number of commits to load in each page.

Limit specifies the maximum number of commits to load. 0 means use DefaultLimit.

func ParseRepoURL

func ParseRepoURL(repoURL string) (host, project string, err error)

ParseRepoURL parses a Gitiles repository URL.

func ValidateRefSet

func ValidateRefSet(c *validation.Context, refs []string)

ValidateRefSet validates strings representing a set of refs.

It ensures that passed strings match the requirements as described in the documentation for the NewRefSet function. It is designed to work with config validation logic, hence one needs to pass in the validation.Context as well.

func ValidateRepoURL

func ValidateRepoURL(repoURL string) error

ValidateRepoURL validates gitiles repository URL.

Types

type RefSet

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

RefSet efficiently resolves many refs, supporting regexps.

RefSet groups refs by prefix and issues 1 refs RPC per prefix. This is more efficient that a single refs RPC for "refs/" prefix, because it would return all refs of the repo, incl. potentially huge number of refs in refs/changes/.

func NewRefSet

func NewRefSet(refs []string) RefSet

NewRefSet creates an instance of the RefSet.

Each entry in the refs parameter can be either

• a fully-qualified ref with at least 2 slashes, e.g. `refs/heads/master`, `refs/tags/v1.2.3`, or
• a regular expression with "regexp:" prefix to match multiple refs, e.g. `regexp:refs/heads/.*` or `regexp:refs/branch-heads/\d+\.\d+`.

The regular expression must have:

• a literal prefix with at least 2 slashes, e.g. `refs/release-\d+/foo` is not allowed, because the literal prefix `refs/release-` contains only one slash, and
• must not start with ^ or end with $ as they will be added automatically.

See also ValidateRefSet function.

func (RefSet) Has

func (w RefSet) Has(ref string) bool

Has checks if a specific ref is in this set.

func (RefSet) Resolve

func (w RefSet) Resolve(c context.Context, client gitiles.GitilesClient, project string) (refTips map[string]string, missingRefs []string, err error)

Resolve queries gitiles to resolve watched refs to git SHA1 hash of their current tips.

Returns map from individual ref to its SHA1 hash and a list of original refs, incl. regular expressions, which either don't exist or are not visible to the requester.