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

    View Source
    const DefaultLimit = 1000

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

      View Source
      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.

        Variables

        This section is empty.

        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.