git

Documentation

Index

• Constants
• Variables
• func ExtractNamedPointerFromRevision(rev string) string
• func IsAnnotatedTag(t Tag) bool
• func IsConcreteCommit(c Commit) bool
• func IsSignedTag(t Tag) bool
• func SecurePath(path string) (string, error)
• func TransformRevision(rev string) string
• type AuthOptions
  • func NewAuthOptions(u url.URL, data map[string][]byte) (*AuthOptions, error)
  • func (o AuthOptions) Validate() error
• type Commit
  • func (c *Commit) AbsoluteReference() string
  • func (c *Commit) ShortMessage() string
  • func (c *Commit) String() string
  • func (c *Commit) Verify(keyRings ...string) (string, error)
• type Credentials
  • func GetCredentials(ctx context.Context, providerOpts *ProviderOptions) (*Credentials, time.Time, error)
• type ErrRepositoryNotFound
  • func (e ErrRepositoryNotFound) Error() string
• type Hash
  • func ExtractHashFromRevision(rev string) Hash
  • func SplitRevision(rev string) (string, Hash)
  • func (h Hash) Algorithm() string
  • func (h Hash) Digest() string
  • func (h Hash) String() string
• type ProviderOptions
• type Signature
• type Tag
  • func (t *Tag) String() string
  • func (t *Tag) Verify(keyRings ...string) (string, error)
• type TransportType

Constants

const (
	ProviderAzure  = "azure"
	ProviderGitHub = "github"

	GitHubAccessTokenUsername = "x-access-token"
)

const (
	// HashTypeSHA1 is the SHA1 hash algorithm.
	HashTypeSHA1 = "sha1"
	// HashTypeUnknown is an unknown hash algorithm.
	HashTypeUnknown = "<unknown>"
)

const (
	DefaultRemote            = "origin"
	DefaultBranch            = "master"
	DefaultPublicKeyAuthUser = "git"
)

Variables

var (
	ErrNoGitRepository = errors.New("no git repository")
	ErrNoStagedFiles   = errors.New("no staged files")
)

var HostKeyAlgos []string

HostKeyAlgos holds the HostKey algorithms that the SSH client will advertise to the server. If empty, Go's default is used instead.

var KexAlgos []string

KexAlgos hosts the key exchange algorithms to be used for SSH connections. If empty, Go's default is used instead.

Functions

func ExtractNamedPointerFromRevision

func ExtractNamedPointerFromRevision(rev string) string

ExtractNamedPointerFromRevision extracts the named pointer from a revision string. It accepts the following formats:

• main@sha1:5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• feature/branch@sha1:5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• main/5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• feature/branch/5394cb7f48332b2de7c17dd8b8384bbc84b7e738

If the revision string does not contain a named pointer, the returned string is empty.

func IsAnnotatedTag

func IsAnnotatedTag(t Tag) bool

IsAnnotatedTag returns true if the provided tag is annotated.

func IsConcreteCommit

func IsConcreteCommit(c Commit) bool

IsConcreteCommit returns if a given commit is a concrete commit. Concrete commits have most of the commit metadata and content. In contrast, a partial commit may only have some metadata and no commit content.

func IsSignedTag

func IsSignedTag(t Tag) bool

IsSignedTag returns true if the provided tag has a signature.

func SecurePath

func SecurePath(path string) (string, error)

SecurePath accepts an absolute or relative path and returns a path that is safe for use. If the path is absolute, it's `filepath.Clean`ed and returned. If the path is relative, it's securely joined against the working directory to ensure that the resultant path is a child of the working directory.

func TransformRevision

func TransformRevision(rev string) string

TransformRevision transforms a "legacy" revision string into a "new" revision string. It accepts the following formats:

• main/5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• feature/branch/5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• HEAD/5394cb7f48332b2de7c17dd8b8384bbc84b7e738

Which are transformed into the following formats respectively:

- main@sha1:5394cb7f48332b2de7c17dd8b8384bbc84b7e738 - feature/branch@sha1:5394cb7f48332b2de7c17dd8b8384bbc84b7e738 - sha1:5394cb7f48332b2de7c17dd8b8384bbc84b7e738

NOTE: This function is only intended to be used for backwards compatibility with the old revision format. It may be removed in a future release.

Types

type AuthOptions

type AuthOptions struct {
	Transport    TransportType
	Host         string
	Username     string
	Password     string
	BearerToken  string
	Identity     []byte
	KnownHosts   []byte
	CAFile       []byte
	ProviderOpts *ProviderOptions
}

AuthOptions are the authentication options for the Transport of communication with a remote origin.

func NewAuthOptions

func NewAuthOptions(u url.URL, data map[string][]byte) (*AuthOptions, error)

NewAuthOptions constructs an AuthOptions object from the given map and URL. If the map is empty, it returns a minimal AuthOptions object after validating the result.

func (AuthOptions) Validate

func (o AuthOptions) Validate() error

Validate the AuthOptions against the defined Transport.

type Commit

type Commit struct {
	// Hash is the hash of the commit.
	Hash Hash
	// Reference is the original reference of the commit, for example:
	// 'refs/tags/foo'.
	Reference string
	// Author is the original author of the commit.
	Author Signature
	// Committer is the one performing the commit, might be different from
	// Author.
	Committer Signature
	// Signature is the PGP signature of the commit.
	Signature string
	// Encoded is the encoded commit, without any signature.
	Encoded []byte
	// Message is the commit message, containing arbitrary text.
	Message string
	// ReferencingTag is the tag that points to this commit.
	ReferencingTag *Tag
}

Commit contains all possible information about a Git commit.

func (*Commit) AbsoluteReference

func (c *Commit) AbsoluteReference() string

AbsoluteReference returns a string representation of the Commit, composed out of the Reference element (if not empty) and Hash. For example: 'refs/tags/tag-1@sha1:a0c14dc8580a23f79bc654faa79c4f62b46c2c22' for a "refs/tags/tag-1" Reference.

func (*Commit) ShortMessage

func (c *Commit) ShortMessage() string

ShortMessage returns the first 50 characters of a commit subject.

func (*Commit) String

func (c *Commit) String() string

String returns a string representation of the Commit, composed out of the last part of the Reference element (if not empty) and Hash. For example: 'tag-1@sha1:a0c14dc8580a23f79bc654faa79c4f62b46c2c22', for a "refs/tags/tag-1" Reference.

func (*Commit) Verify

func (c *Commit) Verify(keyRings ...string) (string, error)

Verify the Signature of the commit with the given key rings. It returns the fingerprint of the key the signature was verified with, or an error. It does not verify the signature of the referencing tag (if present). Users are expected to explicitly verify the referencing tag's signature using `c.ReferencingTag.Verify()`

type Credentials

type Credentials struct {
	BearerToken string
	Username    string
	Password    string
}

Credentials contains authentication data needed in order to access a Git repository.

func GetCredentials

func GetCredentials(ctx context.Context, providerOpts *ProviderOptions) (*Credentials, time.Time, error)

GetCredentials returns authentication credentials for accessing the provided Git repository.

type ErrRepositoryNotFound

type ErrRepositoryNotFound struct {
	Message string
	URL     string
}

ErrRepositoryNotFound indicates that the repository (or the ref in question) does not exist at the given URL.

func (ErrRepositoryNotFound) Error

func (e ErrRepositoryNotFound) Error() string

type Hash

type Hash []byte

Hash is the (non-truncated) SHA-1 or SHA-256 hash of a Git commit.

func ExtractHashFromRevision

func ExtractHashFromRevision(rev string) Hash

ExtractHashFromRevision extracts the hash from a revision string. It accepts the following formats:

• main@sha1:5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• feature/branch@sha1:5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• sha1:5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• main/5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• feature/branch/5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• HEAD/5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• 5394cb7f48332b2de7c17dd8b8384bbc84b7e738

func SplitRevision

func SplitRevision(rev string) (string, Hash)

SplitRevision splits a revision string into it's named pointer and hash components. It accepts the following formats:

• main@sha1:5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• feature/branch@sha1:5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• sha1:5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• main/5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• feature/branch/5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• HEAD/5394cb7f48332b2de7c17dd8b8384bbc84b7e738
• 5394cb7f48332b2de7c17dd8b8384bbc84b7e738

If the revision string does not contain a named pointer, the returned string will be empty.

func (Hash) Algorithm

func (h Hash) Algorithm() string

Algorithm returns the algorithm of the hash based on its length. This is heuristic, and may not be accurate for truncated user constructed hashes. The library itself does not produce truncated hashes.

func (Hash) Digest

func (h Hash) Digest() string

Digest returns a digest of the commit, in the format of "<algorithm>:<hash>".

func (Hash) String

func (h Hash) String() string

String returns the Hash as a string.

type ProviderOptions

type ProviderOptions struct {
	Name       string
	AzureOpts  []azure.OptFunc
	GitHubOpts []github.OptFunc
}

ProviderOptions contains options to configure various authentication providers.

type Signature

type Signature struct {
	Name  string
	Email string
	When  time.Time
}

Signature represents an entity which associates a person and a time with a commit.

type Tag

type Tag struct {
	// Hash is the hash of the tag.
	Hash Hash
	// Name is the name of the tag.
	Name string
	// Author is the original author of the tag.
	Author Signature
	// Signature is the PGP signature of the tag.
	Signature string
	// Encoded is the encoded tag, without any signature.
	Encoded []byte
	// Message is the tag message, containing arbitrary text.
	Message string
}

Tag represents a Git tag.

func (*Tag) String

func (t *Tag) String() string

String returns a short string representation of the tag in the format of <name@hash>, for eg: "1.0.0@a0c14dc8580a23f79bc654faa79c4f62b46c2c22" If the tag is lightweight, it won't have a hash, so it'll simply return the tag name, i.e. "1.0.0".

func (*Tag) Verify

func (t *Tag) Verify(keyRings ...string) (string, error)

Verify the Signature of the tag with the given key rings. It returns the fingerprint of the key the signature was verified with, or an error.

type TransportType

type TransportType string

const (
	SSH   TransportType = "ssh"
	HTTPS TransportType = "https"
	HTTP  TransportType = "http"
)