github

package
v0.5.30 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: BSD-3-Clause Imports: 12 Imported by: 0

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

View Source
const DefaultAPI = "https://api.github.com"

DefaultAPI is the URL of the GitHub REST API.

Variables

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

func BlobSHA

func BlobSHA(content []byte) string

BlobSHA returns the SHA of a blob of a file with the given contents, as git computes it, for comparing files with those of a tree without getting them.

func StatusOf

func StatusOf(err error) int

StatusOf returns the HTTP status code of the given error, if it is an Error, and otherwise 0.

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

func (c *Client) Blob(repo, sha string) ([]byte, error)

Blob returns the contents of the blob of a file with the given SHA of the given repository.

func (*Client) Commit

func (c *Client) Commit(repo, sha string) (*Commit, error)

Commit returns the commit 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

func (c *Client) CreateCommit(repo, message, tree string, parents ...string) (string, error)

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

func (c *Client) CreateTree(repo, base string, files map[string][]byte) (string, error)

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

func (c *Client) Do(method, path string, body, result any) error

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

func (c *Client) Files(repo, tree string) (map[string]TreeEntry, error)

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

func (c *Client) Head(repo, branch string) (string, error)

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

func (c *Client) PutFile(repo, branch, path, message string, content []byte) error

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

func (c *Client) UpdateRef(repo, branch, sha string, force bool) error

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.

func (*Error) Error

func (e *Error) Error() string

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL