Documentation
¶
Overview ¶
Package github is a client of the GitHub REST API for the git data of repositories: branches, commits, trees and files, as for storing and syncing the files of an app in a repository. It uses only HTTPS requests with a token, which work on all platforms, including the web, as the API allows requests from browsers, unlike the git protocol.
Index ¶
- Constants
- Variables
- func BlobSHA(content []byte) string
- func StatusOf(err error) int
- type Client
- func (c *Client) Blob(repo, sha string) ([]byte, error)
- func (c *Client) Commit(repo, sha string) (*Commit, error)
- func (c *Client) CommitFiles(repo, branch, parent, message string, files map[string][]byte) (string, error)
- func (c *Client) CreateCommit(repo, message, tree string, parents ...string) (string, error)
- func (c *Client) CreateTree(repo, base string, files map[string][]byte) (string, error)
- func (c *Client) Do(method, path string, body, result any) error
- func (c *Client) Files(repo, tree string) (map[string]TreeEntry, error)
- func (c *Client) Head(repo, branch string) (string, error)
- func (c *Client) PutFile(repo, branch, path, message string, content []byte) error
- func (c *Client) UpdateRef(repo, branch, sha string, force bool) error
- type Commit
- type Error
- type TreeEntry
Constants ¶
const DefaultAPI = "https://api.github.com"
DefaultAPI is the URL of the GitHub REST API.
Variables ¶
var ErrNotFastForward = errors.New("github: the update of the branch is not a fast forward")
ErrNotFastForward is the error of Client.UpdateRef when the branch has commits that the new commit does not have, as when it was updated since it was read.
Functions ¶
Types ¶
type Client ¶
type Client struct {
// Token is the token for the requests, such as a fine-grained personal
// access token with read and write access to the contents of the
// repositories, or none for public ones.
Token string
// API is the URL of the API, which is [DefaultAPI] if empty,
// or that of a test server (see package githubtest).
API string
// HTTP is the client for the requests, which is
// [http.DefaultClient] if nil.
HTTP *http.Client
// contains filtered or unexported fields
}
Client is a client of the GitHub REST API. Its methods take the repository as "owner/name".
func (*Client) Blob ¶
Blob returns the contents of the blob of a file with the given SHA of the given repository.
func (*Client) CommitFiles ¶
func (c *Client) CommitFiles(repo, branch, parent, message string, files map[string][]byte) (string, error)
CommitFiles commits the given files by path to the given branch of the given repository, after the given commit, the last one of the branch, as in Client.CreateTree, returning the SHA of the new commit. It returns ErrNotFastForward if the branch has commits after the given one, which then must be merged.
func (*Client) CreateCommit ¶
CreateCommit creates a commit of the given repository with the given message, tree and parents, returning its SHA. It does not update a branch (see Client.UpdateRef).
func (*Client) CreateTree ¶
CreateTree creates a tree of the given repository, with the files of the tree with the given SHA, changed by the given files by path: a file is added or replaced with its contents, or deleted if they are nil. It returns the SHA of the new tree.
func (*Client) Do ¶
Do sends a request with the given method to the given path of the API, with the given body as JSON if it is not nil, and decodes the JSON of the response into the given result if it is not nil. GET requests are conditional on the ETag of the last response to the same path, which is used again if it is not modified.
func (*Client) Files ¶
Files returns the files of the tree with the given SHA of the given repository, with those in its directories, by path.
func (*Client) Head ¶
Head returns the SHA of the last commit of the given branch of the given repository. A repository without commits, which the API does not support otherwise, has the status 409 (see StatusOf and Client.PutFile), and one without the branch 404.
func (*Client) PutFile ¶
PutFile commits a file with the given path and contents to the given branch of the given repository, with the contents API, which also works for a repository without commits, for its first commit.
func (*Client) UpdateRef ¶
UpdateRef updates the given branch of the given repository to the commit with the given SHA. Unless force, it must be a fast forward, with the last commit of the branch in its history, or the error is ErrNotFastForward.
type Commit ¶
type Commit struct {
// SHA is the SHA of the commit.
SHA string
// Tree is the SHA of the tree of the files of the commit.
Tree string
// Parents are the SHAs of the parents of the commit.
Parents []string
// Message is the message of the commit.
Message string
// Date is when the commit was made.
Date time.Time
}
Commit is a commit of a repository.
type Error ¶
type Error struct {
// Status is the HTTP status code of the response.
Status int
// Message is the message of the response.
Message string
}
Error is an error response of the API.
type TreeEntry ¶
type TreeEntry struct {
// Path is the path of the file in the tree, with slashes.
Path string `json:"path"`
// Type is blob for a file, and tree for a directory.
Type string `json:"type"`
// SHA is the SHA of the blob of a file (see [BlobSHA]),
// or of the tree of a directory.
SHA string `json:"sha"`
}
TreeEntry is a file or directory in a tree of a repository.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package githubtest is a test server of the parts of the GitHub REST API that package github uses, with repositories in memory.
|
Package githubtest is a test server of the parts of the GitHub REST API that package github uses, with repositories in memory. |