github

Documentation

Overview

Package github reads repository contents from the GitHub API, and searches public code.

It covers what a generator needs to track a file published upstream: find the commit that last touched it, list the tree at that commit, and fetch a file or the whole repository at it. Going through the API rather than cloning keeps the fetch to what is wanted, and yields a commit SHA to record alongside whatever was generated so a result can be traced back to what produced it.

SearchCode answers a different question from the rest: not what is in a repository already named, but which repositories mention something. It is the one call here that reaches across all of GitHub rather than into one project, and it is metered far more tightly than the others.

Index

• Constants
• Variables
• type Client
  • func NewClient(options ...github_config.Option) *Client
  • func (c *Client) Blob(ctx context.Context, owner string, repo string, fileSha string, ...) (*blob.Blob, error)
  • func (c *Client) CommitArchive(ctx context.Context, owner string, repo string, reference string, ...) (*zip.Reader, error)
  • func (c *Client) LatestCommit(ctx context.Context, owner string, repo string, path string, ...) (*commit.Commit, error)
  • func (c *Client) SearchCode(ctx context.Context, query string, page int, perPage int, ...) (*code_search.Response, error)
  • func (c *Client) Tree(ctx context.Context, owner string, repo string, treeSha string, ...) (*tree.Tree, error)

Constants

const (
	DefaultHost        = "api.github.com"
	DefaultArchiveHost = "github.com"
)

const SearchCodeMaxPerPage = 100

SearchCodeMaxPerPage is the largest page the search serves. Asking for more is not an error; it simply returns this many.

const SearchCodePath = "/search/code"

SearchCodePath is where code search is served.

const TextMatchMediaType = "application/vnd.github.text-match+json"

TextMatchMediaType asks for the excerpt around each match. Without it a result names the file that matched but not what in it did.

Variables

var ErrUnexpectedCommitCount = errors.New("unexpected number of commits")

ErrUnexpectedCommitCount reports an answer that does not name exactly the one commit that was asked for.

Types

type Client

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

func NewClient

func NewClient(options ...github_config.Option) *Client

func (*Client) Blob

func (c *Client) Blob(
	ctx context.Context,
	owner string,
	repo string,
	fileSha string,
	options ...fetch_config.Option,
) (*blob.Blob, error)

Blob returns a file's contents.

func (*Client) CommitArchive

func (c *Client) CommitArchive(
	ctx context.Context,
	owner string,
	repo string,
	reference string,
	options ...fetch_config.Option,
) (*zip.Reader, error)

CommitArchive returns the repository at a revision, as an archive.

func (*Client) LatestCommit

func (c *Client) LatestCommit(
	ctx context.Context,
	owner string,
	repo string,
	path string,
	options ...fetch_config.Option,
) (*commit.Commit, error)

LatestCommit returns the commit that last touched path.

Asking for the commit behind a single path, rather than the head of the branch, is what makes a generated file's provenance meaningful: the SHA names the revision that last changed the thing it was generated from.

func (*Client) SearchCode

func (c *Client) SearchCode(
	ctx context.Context,
	query string,
	page int,
	perPage int,
	options ...fetch_config.Option,
) (*code_search.Response, error)

SearchCode returns the public files matching the query.

The query is GitHub's own search syntax, so a caller narrows with qualifiers -- "example.com in:file language:yaml" -- rather than through parameters here. GitHub requires at least one term that is not a qualifier, and refuses a query that is all qualifiers with a 422.

Three things separate this from the rest of the client. It needs a token, and answers 401 without one. It is rate limited to ten requests a minute rather than the five thousand an hour the other calls get, so a caller sweeping many domains must pace itself. And the excerpt around each match arrives only under the text-match media type, which is asked for here because a result without it cannot be judged without opening the file.

perPage of zero asks for the server default; page of zero asks for the first.

func (*Client) Tree

func (c *Client) Tree(
	ctx context.Context,
	owner string,
	repo string,
	treeSha string,
	options ...fetch_config.Option,
) (*tree.Tree, error)

Tree returns the repository listing a tree sha names.