gitfs

Documentation

Overview

Package gitfs reads a real .git directory into the protobuf messages defined in gitfs.proto. The byte-level reasoning behind every parser here lives in GIT_DEEPDIVE.md.

This package only reads. Writing back into a working .git would also need to compute SHA-1s, zlib-encode object bodies, and resolve pack deltas — all out of scope here.

Index

• Variables
• func LoadAllLooseRefs(gitDir string) ([]*pb.Ref, error)
• func LoadConfig(path string) (*pb.Config, error)
• func LoadConfigDefault(gitDir string) (*pb.Config, error)
• func LoadIndex(gitDir string) (*pb.Index, error)
• func LoadObject(gitDir, hexSHA string) (*pb.Object, error)
• func LoadPack(gitDir, basename string) (*pb.Pack, error)
• func LoadPackedRefs(gitDir string) (*pb.PackedRefs, error)
• func LoadRef(gitDir, name string) (*pb.Ref, error)
• func LoadReflog(gitDir, refPath string) (*pb.Reflog, error)
• func Open(gitDir string) (*pb.Repository, error)

Variables

var ErrUnsupportedIndexVersion = errors.New("gitfs: unsupported index version (v4 path-compression not implemented)")

LoadIndex parses .git/index. Versions 2 and 3 are fully decoded; v4 (path prefix compression) returns ErrUnsupportedIndexVersion — the schema permits it but the parser does not yet.

Functions

func LoadAllLooseRefs

func LoadAllLooseRefs(gitDir string) ([]*pb.Ref, error)

LoadAllLooseRefs walks .git/refs/ and returns every loose ref.

func LoadConfig

func LoadConfig(path string) (*pb.Config, error)

func LoadConfigDefault

func LoadConfigDefault(gitDir string) (*pb.Config, error)

LoadConfig parses .git/config (or any git config file at `path`). LoadConfigDefault reads gitDir/config.

func LoadIndex

func LoadIndex(gitDir string) (*pb.Index, error)

func LoadObject

func LoadObject(gitDir, hexSHA string) (*pb.Object, error)

LoadObject reads .git/objects/XX/<rest> for the given hex SHA-1, verifies the SHA matches, and returns the typed Object. Errors if the object is not present as a loose object — packed objects are returned by LoadPackedObject (not yet implemented).

func LoadPack

func LoadPack(gitDir, basename string) (*pb.Pack, error)

LoadPack parses just the header of a .pack file and the full idx file. The .pack body (variable-length objects, deltas) is not exploded into Object messages here — callers that need that should delegate to a real git library.

func LoadPackedRefs

func LoadPackedRefs(gitDir string) (*pb.PackedRefs, error)

LoadPackedRefs parses .git/packed-refs. Returns (nil, nil) if the file doesn't exist (some repos have only loose refs).

func LoadRef

func LoadRef(gitDir, name string) (*pb.Ref, error)

LoadRef reads a single ref file (loose). name is relative to .git/, e.g. "HEAD" or "refs/heads/main".

func LoadReflog

func LoadReflog(gitDir, refPath string) (*pb.Reflog, error)

LoadReflog parses .git/logs/<refPath>. refPath is something like "HEAD" or "refs/heads/main" (without the leading "logs/").

func Open

func Open(gitDir string) (*pb.Repository, error)

Open reads a .git directory into a *pb.Repository. Loose objects are loaded en masse; packs are loaded as headers+idx only (object explosion is deferred). LocalState fields are best-effort — missing files leave the field zero.