v2

package
v5.0.0-...-c65899a Latest Latest
Warning

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

 Go to latest Published: Jan 25, 2024 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package v2 implements encoding and decoding of commit-graph files.

This package was created to work around the issues of the incorrect types in the commitgraph package.

Git commit graph format =======================

The Git commit graph stores a list of commit OIDs and some associated metadata, including:

  • The generation number of the commit. Commits with no parents have generation number 1; commits with parents have generation number one more than the maximum generation number of its parents. We reserve zero as special, and can be used to mark a generation number invalid or as "not computed".

- The root tree OID.

- The commit date.

  • The parents of the commit, stored using positional references within the graph file.

These positional references are stored as unsigned 32-bit integers corresponding to the array position within the list of commit OIDs. Due to some special constants we use to track parents, we can store at most (1 << 30) + (1 << 29) + (1 << 28) - 1 (around 1.8 billion) commits.

== Commit graph files have the following format:

In order to allow extensions that add extra data to the graph, we organize the body into "chunks" and provide a binary lookup table at the beginning of the body. The header includes certain values, such as number of chunks and hash type.

All 4-byte numbers are in network order.

HEADER: 

4-byte signature:
    The signature is: {'C', 'G', 'P', 'H'}

1-byte version number:
    Currently, the only valid version is 1.

1-byte Hash Version (1 = SHA-1)
    We infer the hash length (H) from this value.

1-byte number (C) of "chunks"

1-byte (reserved for later use)
   Current clients should ignore this value.

CHUNK LOOKUP: 

(C + 1) * 12 bytes listing the table of contents for the chunks:
    First 4 bytes describe the chunk id. Value 0 is a terminating label.
    Other 8 bytes provide the byte-offset in current file for chunk to
    start. (Chunks are ordered contiguously in the file, so you can infer
    the length using the next chunk position if necessary.) Each chunk
    ID appears at most once.

The remaining data in the body is described one chunk at a time, and
these chunks may be given in any order. Chunks are required unless
otherwise specified.

CHUNK DATA: 

OID Fanout (ID: {'O', 'I', 'D', 'F'}) (256 * 4 bytes)
    The ith entry, F[i], stores the number of OIDs with first
    byte at most i. Thus F[255] stores the total
    number of commits (N).

OID Lookup (ID: {'O', 'I', 'D', 'L'}) (N * H bytes)
    The OIDs for all commits in the graph, sorted in ascending order.

Commit Data (ID: {'C', 'D', 'A', 'T' }) (N * (H + 16) bytes)
  * The first H bytes are for the OID of the root tree.
  * The next 8 bytes are for the positions of the first two parents
    of the ith commit. Stores value 0x7000000 if no parent in that
    position. If there are more than two parents, the second value
    has its most-significant bit on and the other bits store an array
    position into the Extra Edge List chunk.
  * The next 8 bytes store the generation number of the commit and
    the commit time in seconds since EPOCH. The generation number
    uses the higher 30 bits of the first 4 bytes, while the commit
    time uses the 32 bits of the second 4 bytes, along with the lowest
    2 bits of the lowest byte, storing the 33rd and 34th bit of the
    commit time.

Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
    This list of 4-byte values store the second through nth parents for
    all octopus merges. The second parent value in the commit data stores
    an array position within this list along with the most-significant bit
    on. Starting at that array position, iterate through this list of commit
    positions for the parents until reaching a value with the most-significant
    bit on. The other bits correspond to the position of the last parent.

TRAILER: 

H-byte HASH-checksum of all of the above.

Source: https://raw.githubusercontent.com/git/git/master/Documentation/technical/commit-graph-format.txt

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrUnsupportedVersion is returned by OpenFileIndex when the commit graph
	// file version is not supported.
	ErrUnsupportedVersion = errors.New("unsupported version")
	// ErrUnsupportedHash is returned by OpenFileIndex when the commit graph
	// hash function is not supported. Currently only SHA-1 is defined and
	// supported.
	ErrUnsupportedHash = errors.New("unsupported hash algorithm")
	// ErrMalformedCommitGraphFile is returned by OpenFileIndex when the commit
	// graph file is corrupted.
	ErrMalformedCommitGraphFile = errors.New("malformed commit graph file")
)

Functions

func OpenChainFile 

func OpenChainFile(r io.Reader) ([]string, error)

OpenChainFile reads a commit chain file and returns a slice of the hashes within it

Commit-Graph chains are described at https://git-scm.com/docs/commit-graph and are new line separated list of graph file hashes, oldest to newest.

This function simply reads the file and returns the hashes as a slice.

Types

type ChunkType 

type ChunkType int

ChunkType represents the type of a chunk in the commit graph file. 

const (
	OIDFanoutChunk              ChunkType = iota // "OIDF"
	OIDLookupChunk                               // "OIDL"
	CommitDataChunk                              // "CDAT"
	GenerationDataChunk                          // "GDA2"
	GenerationDataOverflowChunk                  // "GDO2"
	ExtraEdgeListChunk                           // "EDGE"
	BloomFilterIndexChunk                        // "BIDX"
	BloomFilterDataChunk                         // "BDAT"
	BaseGraphsListChunk                          // "BASE"
	ZeroChunk                                    // "\000\000\000\000"
)

func ChunkTypeFromBytes 

func ChunkTypeFromBytes(b []byte) (ChunkType, bool)

ChunkTypeFromBytes returns the chunk type for the given byte signature.

func (ChunkType) Signature 

func (ct ChunkType) Signature() []byte

Signature returns the byte signature for the chunk type.

type CommitData 

type CommitData struct {
	// TreeHash is the hash of the root tree of the commit.
	TreeHash plumbing.Hash
	// ParentIndexes are the indexes of the parent commits of the commit.
	ParentIndexes []uint32
	// ParentHashes are the hashes of the parent commits of the commit.
	ParentHashes []plumbing.Hash
	// Generation number is the pre-computed generation in the commit graph
	// or zero if not available.
	Generation uint64
	// GenerationV2 stores the corrected commit date for the commits
	// It combines the contents of the GDA2 and GDO2 sections of the commit-graph
	// with the commit time portion of the CDAT section.
	GenerationV2 uint64
	// When is the timestamp of the commit.
	When time.Time
}

CommitData is a reduced representation of Commit as presented in the commit graph file. It is merely useful as an optimization for walking the commit graphs.

func (*CommitData) GenerationV2Data 

func (c *CommitData) GenerationV2Data() uint64

GenerationV2Data returns the corrected commit date for the commits

type Encoder 

type Encoder struct {
	io.Writer
	// contains filtered or unexported fields
}

Encoder writes MemoryIndex structs to an output stream.

func NewEncoder 

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new stream encoder that writes to w.

func (*Encoder) Encode 

func (e *Encoder) Encode(idx Index) error

Encode writes an index into the commit-graph file

type Index 

type Index interface {
	// GetIndexByHash gets the index in the commit graph from commit hash, if available
	GetIndexByHash(h plumbing.Hash) (uint32, error)
	// GetHashByIndex gets the hash given an index in the commit graph
	GetHashByIndex(i uint32) (plumbing.Hash, error)
	// GetNodeByIndex gets the commit node from the commit graph using index
	// obtained from child node, if available
	GetCommitDataByIndex(i uint32) (*CommitData, error)
	// Hashes returns all the hashes that are available in the index
	Hashes() []plumbing.Hash
	// HasGenerationV2 returns true if the commit graph has the corrected commit date data
	HasGenerationV2() bool
	// MaximumNumberOfHashes returns the maximum number of hashes within the index
	MaximumNumberOfHashes() uint32

	io.Closer
}

Index represents a representation of commit graph that allows indexed access to the nodes using commit object hash

func OpenChainIndex 

func OpenChainIndex(fs billy.Filesystem) (Index, error)

OpenChainIndex expects a billy.Filesystem representing a .git directory. It will read a commit-graph chain file and return a coalesced index. If the chain file or a graph in that chain is not present, an error is returned.

See: https://git-scm.com/docs/commit-graph

func OpenChainOrFileIndex 

func OpenChainOrFileIndex(fs billy.Filesystem) (Index, error)

OpenChainOrFileIndex expects a billy.Filesystem representing a .git directory. It will first attempt to read a commit-graph index file, before trying to read a commit-graph chain file and its index files. If neither are present, an error is returned. Otherwise an Index will be returned.

See: https://git-scm.com/docs/commit-graph

func OpenFileIndex 

func OpenFileIndex(reader ReaderAtCloser) (Index, error)

OpenFileIndex opens a serialized commit graph file in the format described at https://github.com/git/git/blob/master/Documentation/technical/commit-graph-format.txt

func OpenFileIndexWithParent 

func OpenFileIndexWithParent(reader ReaderAtCloser, parent Index) (Index, error)

OpenFileIndexWithParent opens a serialized commit graph file in the format described at https://github.com/git/git/blob/master/Documentation/technical/commit-graph-format.txt

type MemoryIndex 

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

MemoryIndex provides a way to build the commit-graph in memory for later encoding to file.

func NewMemoryIndex 

func NewMemoryIndex() *MemoryIndex

NewMemoryIndex creates in-memory commit graph representation

func (*MemoryIndex) Add 

func (mi *MemoryIndex) Add(hash plumbing.Hash, data *CommitData)

Add adds new node to the memory index

func (*MemoryIndex) Close 

func (mi *MemoryIndex) Close() error

Close closes the index

func (*MemoryIndex) GetCommitDataByIndex 

func (mi *MemoryIndex) GetCommitDataByIndex(i uint32) (*CommitData, error)

GetCommitDataByIndex gets the commit node from the commit graph using index obtained from child node, if available

func (*MemoryIndex) GetHashByIndex 

func (mi *MemoryIndex) GetHashByIndex(i uint32) (plumbing.Hash, error)

GetHashByIndex gets the hash given an index in the commit graph

func (*MemoryIndex) GetIndexByHash 

func (mi *MemoryIndex) GetIndexByHash(h plumbing.Hash) (uint32, error)

GetIndexByHash gets the index in the commit graph from commit hash, if available

func (*MemoryIndex) HasGenerationV2 

func (mi *MemoryIndex) HasGenerationV2() bool

func (*MemoryIndex) Hashes 

func (mi *MemoryIndex) Hashes() []plumbing.Hash

Hashes returns all the hashes that are available in the index

func (*MemoryIndex) MaximumNumberOfHashes 

func (mi *MemoryIndex) MaximumNumberOfHashes() uint32

type ReaderAtCloser 

type ReaderAtCloser interface {
	io.ReaderAt
	io.Closer
}

ReaderAtCloser is an interface that combines io.ReaderAt and io.Closer.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.