advrefs

Documentation

Overview

Package advrefs implements encoding and decoding advertised-refs messages from a git-upload-pack command.

Index

• Variables
• type AdvRefs
  • func New() *AdvRefs
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v *AdvRefs) error
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (e *Encoder) Encode(v *AdvRefs) error

Examples

• Decoder.Decode
• Encoder.Encode

Variables

var ErrEmpty = errors.New("empty advertised-ref message")

ErrEmpty is returned by Decode when there was no advertised-message at all

Types

type AdvRefs

type AdvRefs struct {
	Prefix       [][]byte // payloads of the prefix
	Head         *plumbing.Hash
	Capabilities *packp.Capabilities
	References   map[string]plumbing.Hash
	Peeled       map[string]plumbing.Hash
	Shallows     []plumbing.Hash
}

AdvRefs values represent the information transmitted on an advertised-refs message. Values from this type are not zero-value safe, use the New function instead.

When using this messages over (smart) HTTP, you have to add a pktline before the whole thing with the following payload:

'# service=$servicename" LF

Moreover, some (all) git HTTP smart servers will send a flush-pkt just after the first pkt-line.

To accomodate both situations, the Prefix field allow you to store any data you want to send before the actual pktlines. It will also be filled up with whatever is found on the line.

func New

func New() *AdvRefs

New returns a pointer to a new AdvRefs value, ready to be used.

type Decoder

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

A Decoder reads and decodes AdvRef values from an input stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r.

Will not read more data from r than necessary.

func (*Decoder) Decode

func (d *Decoder) Decode(v *AdvRefs) error

Decode reads the next advertised-refs message form its input and stores it in the value pointed to by v.

Example

// Here is a raw advertised-ref message.
raw := "" +
	"0065a6930aaee06755d1bdcfd943fbf614e4d92bb0c7 HEAD\x00multi_ack ofs-delta symref=HEAD:/refs/heads/master\n" +
	"003fa6930aaee06755d1bdcfd943fbf614e4d92bb0c7 refs/heads/master\n" +
	"00441111111111111111111111111111111111111111 refs/tags/v2.6.11-tree\n" +
	"00475555555555555555555555555555555555555555 refs/tags/v2.6.11-tree^{}\n" +
	"0035shallow 5dc01c595e6c6ec9ccda4f6f69c131c0dd945f8c\n" +
	"0000"

// Use the raw message as our input.
input := strings.NewReader(raw)

// Create a advref.Decoder reading from our input.
d := advrefs.NewDecoder(input)

// Decode the input into a newly allocated AdvRefs value.
ar := advrefs.New()
_ = d.Decode(ar) // error check ignored for brevity

// Do something interesting with the AdvRefs, e.g. print its contents.
fmt.Println("head =", ar.Head)
fmt.Println("capabilities =", ar.Capabilities.String())
fmt.Println("...")
fmt.Println("shallows =", ar.Shallows)

Output:

head = a6930aaee06755d1bdcfd943fbf614e4d92bb0c7
capabilities = multi_ack ofs-delta symref=HEAD:/refs/heads/master
...
shallows = [5dc01c595e6c6ec9ccda4f6f69c131c0dd945f8c]

type Encoder

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

An Encoder writes AdvRefs values to an output stream.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w.

func (*Encoder) Encode

func (e *Encoder) Encode(v *AdvRefs) error

Encode writes the AdvRefs encoding of v to the stream.

All the payloads will end with a newline character. Capabilities, references and shallows are writen in alphabetical order, except for peeled references that always follow their corresponding references.

Example

// Create an AdvRefs with the contents you want...
ar := advrefs.New()

// ...add a hash for the HEAD...
head := plumbing.NewHash("1111111111111111111111111111111111111111")
ar.Head = &head

// ...add some server capabilities...
ar.Capabilities.Add("symref", "HEAD:/refs/heads/master")
ar.Capabilities.Add("ofs-delta")
ar.Capabilities.Add("multi_ack")

// ...add a couple of references...
ar.References["refs/heads/master"] = plumbing.NewHash("2222222222222222222222222222222222222222")
ar.References["refs/tags/v1"] = plumbing.NewHash("3333333333333333333333333333333333333333")

// ...including a peeled ref...
ar.Peeled["refs/tags/v1"] = plumbing.NewHash("4444444444444444444444444444444444444444")

// ...and finally add a shallow
ar.Shallows = append(ar.Shallows, plumbing.NewHash("5555555555555555555555555555555555555555"))

// Encode the advrefs.Contents to a bytes.Buffer.
// You can encode into stdout too, but you will not be able
// see the '\x00' after "HEAD".
var buf bytes.Buffer
e := advrefs.NewEncoder(&buf)
_ = e.Encode(ar) // error checks ignored for brevity

// Print the contents of the buffer as a quoted string.
// Printing is as a non-quoted string will be prettier but you
// will miss the '\x00' after "HEAD".
fmt.Printf("%q", buf.String())

Output:

"00651111111111111111111111111111111111111111 HEAD\x00multi_ack ofs-delta symref=HEAD:/refs/heads/master\n003f2222222222222222222222222222222222222222 refs/heads/master\n003a3333333333333333333333333333333333333333 refs/tags/v1\n003d4444444444444444444444444444444444444444 refs/tags/v1^{}\n0035shallow 5555555555555555555555555555555555555555\n0000"