gitiles

Documentation

Overview

Package gitiles allows querying git repositories hosted on *.googlesource.com.

Index

• func NormalizeRepoURL(repoURL string) (string, error)
• func ValidateRepoURL(repoURL string) error
• type Client
  • func (c *Client) Log(ctx context.Context, repoURL, treeish string, limit int) ([]Commit, error)
  • func (c *Client) Refs(ctx context.Context, repoURL, refsPath string) (map[string]string, error)
• type Commit
• type User
  • func (u *User) GetTime() (time.Time, error)

Functions

func NormalizeRepoURL

func NormalizeRepoURL(repoURL string) (string, error)

NormalizeRepoURL returns canonical for gitiles URL of the repo including "a/" path prefix. error is returned if validation fails.

func ValidateRepoURL

func ValidateRepoURL(repoURL string) error

ValidateRepoURL validates gitiles repository URL for use in this package.

Types

type Client

type Client struct {
	Client *http.Client
	// contains filtered or unexported fields
}

Client is Gitiles client.

func (*Client) Log

func (c *Client) Log(ctx context.Context, repoURL, treeish string, limit int) ([]Commit, error)

Log returns a list of commits based on a repo and treeish. This should be equivalent of a "git log <treeish>" call in that repository.

treeish can be either:

(1) a git revision as 40-char string or its prefix so long as its unique in repo.
(2) a ref such as "refs/heads/branch" or just "branch"
(3) a ref defined as n-th parent of R in the form "R~n".
    For example, "master~2" or "deadbeef~1".
(4) a range between two revisions in the form "CHILD..PREDECESSOR", where
    CHILD and PREDECESSOR are each specified in either (1), (2) or (3)
    formats listed above.
    For example, "foo..ba1", "master..refs/branch-heads/1.2.3",
      or even "master~5..master~9".

If the returned log has a commit with 2+ parents, the order of commits after that is whatever Gitiles returns, which currently means ordered by topological sort first, and then by commit timestamps.

This means that if Log(C) contains commit A, Log(A) will not necessarily return a subsequence of Log(C) (though definitely a subset). For example,

   common... -> base ------> A ----> C
                     \            /
                      --> B ------

   ----commit timestamp increases--->

Log(A) = [A, base, common...]
Log(B) = [B, base, common...]
Log(C) = [C, A, B, base, common...]

func (*Client) Refs

func (c *Client) Refs(ctx context.Context, repoURL, refsPath string) (map[string]string, error)

Refs returns a map resolving each ref in a repo to git revision.

refsPath limits which refs to resolve to only those matching {refsPath}/*. refsPath should start with "refs" and should not include glob '*'. Typically, "refs/heads" should be used.

To fetch **all** refs in a repo, specify just "refs" but beware of two caveats:

• refs returned include a ref for each patchset for each Gerrit change associated with the repo
• returned map will contain special "HEAD" ref whose value in resulting map will be name of the actual ref to which "HEAD" points, which is typically "refs/heads/master".

Thus, if you are looking for all tags and all branches of repo, it's recommended to issue two Refs calls limited to "refs/tags" and "refs/heads" instead of one call for "refs".

Since Gerrit allows per-ref ACLs, it is possible that some refs matching refPrefix would not be present in results because current user isn't granted read permission on them.

type Commit

type Commit struct {
	Commit    string   `json:"commit"`
	Tree      string   `json:"tree"`
	Parents   []string `json:"parents"`
	Author    User     `json:"author"`
	Committer User     `json:"committer"`
	Message   string   `json:"message"`
}

Commit is the information of a commit returned from gitiles.

type User

type User struct {
	Name  string `json:"name"`
	Email string `json:"email"`
	Time  string `json:"time"`
}

User is the author or the committer returned from gitiles.

func (*User) GetTime

func (u *User) GetTime() (time.Time, error)

GetTime returns the Time field as real data!