gitoid

README

gitoid provides a simple library to compute gitoids (git object ids)

Creating GitOIDs

Default Usage

By default it produces gitoids for git object type blob using sha1:

var reader os.Reader
gitoidHash, err := gitoid.New(reader)
fmt.Println(gitoidHash)
// Output: 261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64
fmt.Println(gitoidHash.URI())
// Output: gitoid:blob:sha1:261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64

GitOid from string or []byte

It's simple to compute the gitoid from a string or []byte by using bytes.NewBuffer:

input := []byte("example")
gitoidHash, _ := gitoid.New(bytes.NewBuffer(input))
fmt.Println(gitoidHash)
// Output: 96236f8158b12701d5e75c14fb876c4a0f31b963
fmt.Println(gitoidHash.URI())
// Output: gitoid:blob:sha1:96236f8158b12701d5e75c14fb876c4a0f31b963

GitOID from URIs

GitOIDs can be represented as a gitoid uri.

gitoidHash, _ := gitoid.FromURI("gitoid:blob:sha1:96236f8158b12701d5e75c14fb876c4a0f31b96")
fmt.Println(gitoidHash)
// Output: 96236f8158b12701d5e75c14fb876c4a0f31b963
fmt.Println(gitoidHash.URI())
// Output: gitoid:blob:sha1:96236f8158b12701d5e75c14fb876c4a0f31b963

Variations on GitOIDs

SHA256 gitoids

Git defaults to computing gitoids with sha1. Git also supports sha256 gitoids. Sha256 gitoids are supported using an Option:

var reader os.Reader
gitoidHash, err := gitoid.New(reader, gitoid.WithSha256())
fmt.Println(gitoidHash)
// Output: ed43975fbdc3084195eb94723b5f6df44eeeed1cdda7db0c7121edf5d84569ab
fmt.Println(gitoidHash.URI())
// Output: gitoid:blob:sha256:ed43975fbdc3084195eb94723b5f6df44eeeed1cdda7db0c7121edf5d84569ab

Other git object types

git has four object types: blob, tree, commit, tag. By default gitoid using object type blob. You may optionally specify another object type using an Option:

var reader os.Reader
gitoidHash, err := gitoid.New(reader, gitoid.WithGitObjectType(gitoid.COMMIT))

Assert ContentLength

git object ids consist of hash over a header followed by the file contents. The header contains the length of the file contents. By default, gitoid simply copies the reader into a buffer to establish its contentLength to compute the header.

If you wish to assert the contentLength yourself, you may do so with an Option:

var reader os.Reader
var contentLength int64
gitoidHash, _ := gitoid.New(reader, gitoid.WithContentLength(contentLength))
fmt.Println(gitoidHash)
// Output: 261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64

gitoid will read the first contentLength bytes from the provided reader. If the reader is unable to provide contentLength bytes a wrapper error around io.ErrUnexpectedEOF will be returned from gitoid.New

Using GitOIDs

Match contents to a GitOID

var reader io.Reader
var gitoidHash *gitoid.GitOID
if gitoidHash.Match(reader) {
	fmt.Println("matched")
}

Find files that match GitOID

var path1 fs.FS = os.DirFS("./relative/path")
var path2 fs.FS = os.DirFS("/absolute/path")
var gitoidHash *gitoid.GitOID

// Find a file in path1 and path2 that matches gitoidHash
file,_ := gitoidHash.Find(path1, path2)

// Find all files in path1 and path2 that matches gitoidHash
files, := gitoidHash.FindAll(path1, path2)

Documentation

Overview

Example (Gitoid_bytes_sha1)

package main

import (
	"bytes"
	"fmt"

	"github.com/edwarnicke/gitoid"
)

func main() {
	input := []byte("example")
	gitoidHash, _ := gitoid.New(bytes.NewBuffer(input))
	fmt.Println(gitoidHash)
}

Output:

96236f8158b12701d5e75c14fb876c4a0f31b963

Example (Gitoid_sha1)

package main

import (
	"fmt"
	"os"

	"github.com/edwarnicke/gitoid"
)

const filename = "LICENSE"

func main() {
	file, _ := os.Open(filename)
	defer file.Close()

	gitoidHash, _ := gitoid.New(file)
	fmt.Println(gitoidHash)
}

Output:

261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64

Example (Gitoid_sha1_content_length)

package main

import (
	"fmt"
	"os"

	"github.com/edwarnicke/gitoid"
)

const filename = "LICENSE"

func main() {
	file, _ := os.Open(filename)
	defer file.Close()
	fi, _ := file.Stat()

	gitoidHash, _ := gitoid.New(file, gitoid.WithContentLength(fi.Size()))
	fmt.Println(gitoidHash)
}

Output:

261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64

Example (Gitoid_sha256)

package main

import (
	"fmt"
	"os"

	"github.com/edwarnicke/gitoid"
)

const filename = "LICENSE"

func main() {
	file, _ := os.Open(filename)
	defer file.Close()

	gitoidHash, _ := gitoid.New(file, gitoid.WithSha256())
	fmt.Println(gitoidHash)
}

Output:

ed43975fbdc3084195eb94723b5f6df44eeeed1cdda7db0c7121edf5d84569ab

Example (Gitoid_uri_sha1)

package main

import (
	"fmt"
	"os"

	"github.com/edwarnicke/gitoid"
)

const filename = "LICENSE"

func main() {
	file, _ := os.Open(filename)
	defer file.Close()

	gitoidHash, _ := gitoid.New(file)
	fmt.Println(gitoidHash.URI())
}

Output:

gitoid:blob:sha1:261eeb9e9f8b2b4b0d119366dda99c6fd7d35c64

Example (Gitoid_uri_sha256)

package main

import (
	"fmt"
	"os"

	"github.com/edwarnicke/gitoid"
)

const filename = "LICENSE"

func main() {
	file, _ := os.Open(filename)
	defer file.Close()

	gitoidHash, _ := gitoid.New(file, gitoid.WithSha256())
	fmt.Println(gitoidHash.URI())
}

Output:

gitoid:blob:sha256:ed43975fbdc3084195eb94723b5f6df44eeeed1cdda7db0c7121edf5d84569ab

Index

• Variables
• func Header(gitObjectType GitObjectType, contentLength int64) []byte
• type GitOID
  • func FromURI(uri string) (*GitOID, error)
  • func New(reader io.Reader, opts ...Option) (*GitOID, error)
  • func (g *GitOID) Bytes() []byte
  • func (g *GitOID) Equal(x *GitOID) bool
  • func (g *GitOID) Find(paths ...fs.FS) fs.File
  • func (g *GitOID) FindAll(paths ...fs.FS) []fs.File
  • func (g *GitOID) Match(reader io.Reader) bool
  • func (g *GitOID) String() string
  • func (g *GitOID) URI() string
• type GitObjectType
• type Option
  • func WithContentLength(contentLength int64) Option
  • func WithGitObjectType(gitObjectType GitObjectType) Option
  • func WithSha256() Option

Examples

• Package (Gitoid_bytes_sha1)
• Package (Gitoid_sha1)
• Package (Gitoid_sha1_content_length)
• Package (Gitoid_sha256)
• Package (Gitoid_uri_sha1)
• Package (Gitoid_uri_sha256)

Variables

var ErrInvalidGitOIDURI = errors.New("invalid uri in gitoid.FromURI")

var ErrMayNotBeNil = errors.New("may not be nil")

Functions

func Header

func Header(gitObjectType GitObjectType, contentLength int64) []byte

Header - returns the git object header from the gitObjectType and contentLength.

Types

type GitOID

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

func FromURI

func FromURI(uri string) (*GitOID, error)

FromURI - returns a *GitOID from a gitoid uri string - see https://www.iana.org/assignments/uri-schemes/prov/gitoid

func New

func New(reader io.Reader, opts ...Option) (*GitOID, error)

New - create a new GitOID

by default git object type is "blob" and hash is sha1

func (*GitOID) Bytes

func (g *GitOID) Bytes() []byte

func (*GitOID) Equal

func (g *GitOID) Equal(x *GitOID) bool

Equal - returns true of g == x.

func (*GitOID) Find

func (g *GitOID) Find(paths ...fs.FS) fs.File

Find - return the first fs.File in paths that Matches the *GitOID g.

func (*GitOID) FindAll

func (g *GitOID) FindAll(paths ...fs.FS) []fs.File

FindAll - return all fs.Files in paths that Matches the *GitOID g.

func (*GitOID) Match

func (g *GitOID) Match(reader io.Reader) bool

Match - returns true if contents of reader generates a GitOID equal to g.

func (*GitOID) String

func (g *GitOID) String() string

String - returns the gitoid in lowercase hex.

func (*GitOID) URI

func (g *GitOID) URI() string

URI - returns the gitoid as a URI (https://www.iana.org/assignments/uri-schemes/prov/gitoid)

type GitObjectType

type GitObjectType string

GitObjectType type of git object - current values are "blob", "commit", "tag", "tree".

const (
	BLOB   GitObjectType = "blob"
	COMMIT GitObjectType = "commit"
	TAG    GitObjectType = "tag"
	TREE   GitObjectType = "tree"
)

type Option

type Option func(o *option)

Option - option for GitOID creation.

func WithContentLength

func WithContentLength(contentLength int64) Option

WithContentLength - allows the assertion of a contentLength to be read from the provided reader

only the first contentLength of data will be read from the reader
if contentLength bytes are unavailable from the reader, an error will be returned.

func WithGitObjectType

func WithGitObjectType(gitObjectType GitObjectType) Option

WithGitObjectType - set the GitOobjectType to a value different than the default gitoid.BLOB type.

func WithSha256

func WithSha256() Option

WithSha256 - use sha256 for computing gitoids instead of the default sha1.