gitproto

Documentation

Overview

Package gitproto reads the git smart HTTP advertisement.

This is the one surface on github.com that answers "what refs does this repository have" completely, in a single request, with no login, no page limit, and no truncation. The branches page caps its list and says so, the refs fragment gives names and nothing else, and the tags feed gives ten. The advertisement gives every branch, every tag, every pull request head, and the object each one points at.

The format is pkt-line, which is four hex digits of length followed by that many bytes including the four. 0000 is a flush packet. The first line after the service header carries the capability list after a NUL byte, and one of those capabilities is symref=HEAD:refs/heads/main, which is where the default branch comes from for free.

Index

• Variables
• type Advertisement
  • func Parse(body []byte) (*Advertisement, error)
  • func (a *Advertisement) Branches() []Ref
  • func (a *Advertisement) PullHeads() []Ref
  • func (a *Advertisement) Tags() []Ref
• type Ref

Variables

var ErrNotGit = errors.New("not a git upload-pack advertisement")

ErrNotGit is returned when the body is not an advertisement. It usually means github.com answered with an HTML page, which is what a private or missing repository does.

Types

type Advertisement

type Advertisement struct {
	Refs []Ref
	// Head is the SHA the HEAD line advertised.
	Head string
	// DefaultBranch is the target of symref=HEAD:..., short form, so "main"
	// rather than "refs/heads/main". Empty when the server did not advertise it.
	DefaultBranch string
	Capabilities  []string
}

Advertisement is a parsed info/refs response.

func Parse

func Parse(body []byte) (*Advertisement, error)

Parse reads an info/refs?service=git-upload-pack body.

Peeled entries are folded into the ref they belong to rather than kept as separate refs, because "refs/tags/v1.0.0^{}" is not a ref anybody can check out and a caller that has to know about the fold is a caller doing the parser's job.

func (*Advertisement) Branches

func (a *Advertisement) Branches() []Ref

Branches returns the refs under refs/heads, with the prefix stripped.

func (*Advertisement) PullHeads

func (a *Advertisement) PullHeads() []Ref

PullHeads returns the refs under refs/pull, which github.com advertises for every pull request ever opened against the repository. The name keeps its shape, "1234/head" or "1234/merge", because those two are different objects and flattening them would lose that.

func (*Advertisement) Tags

func (a *Advertisement) Tags() []Ref

Tags returns the refs under refs/tags, with the prefix stripped. An annotated tag keeps both SHAs: SHA is the tag object and Peeled is the commit.

type Ref

type Ref struct {
	Name string
	SHA  string
	// Peeled is set on the ^{} entry of an annotated tag: the tag object's own
	// SHA is in SHA and the commit it points at is here. A lightweight tag has
	// no peeled entry, which is how you tell the two apart.
	Peeled string
}

Ref is one advertised ref.