gitutil

Documentation

Overview

Package git contains enhanced Git reference resolution and diff utilities built on top of go-git. It adds higher level ergonomics required by the deputy CLI including:

• Flexible reference parsing (branches, tags, SHAs, remote refs, pseudo WORKING ref)
• Time-qualified revision selection (HEAD@{1.week.ago} style) via ResolveRevisionEnhanced
• Detection of dependency file changes for optimization (CheckFilesChanged)
• Heuristics for default branch discovery in varied repository topologies
• Similarity scoring and suggestion generation for mistyped references

The functions are side‑effect free (except repository reads) and suitable for reuse in other analysis workflows.

Index

• Constants
• Variables
• func CheckFilesChanged(repoPath string, baseRef string, prRef string) ([]string, error)
• func CloneContext(ctx context.Context, dir string, opts *gitlib.CloneOptions) (*gitlib.Repository, func(), error)
• func GetDefaultBranch(repo *git.Repository) (string, error)
• func GetReferenceSuggestions(repo *git.Repository, invalidRef string) []string
• func InstallSafeGitTransport()
• func InstallSafeGitTransportWithOptions(opts ...network.Option)
• func NewSafeGitTransport() transport.Transport
• func NewSafeGitTransportWithOptions(opts ...network.Option) transport.Transport
• func NormalizeGitRefForGoGit(ref string) string
• func ParseReferences(repoPath string, args []string, matcher PathMatcher) (baseRef, targetRef string, err error)
• func ParseTimeShorthandToISO(expr string) string
• func ReadFileAtCommit(repo *git.Repository, hash plumbing.Hash, path string) ([]byte, error)
• func ResolveReferenceName(ctx context.Context, remoteURL string, auth transport.AuthMethod, ...) (plumbing.ReferenceName, error)
• func ResolveRevisionEnhanced(repo *git.Repository, ref string) (*plumbing.Hash, error)
• func ToHTTPSGitURL(ref string) string
• type PathMatcher

Constants

const (
	// RefHEAD is the symbolic reference to the current commit.
	RefHEAD = "HEAD"
	// RefWORKING represents the working tree (uncommitted changes).
	RefWORKING = "WORKING"
)

Common Git reference constants.

Variables

var DefaultBranchPatterns = []string{"main", "master", "trunk", "default"}

DefaultBranchPatterns lists common default branch names used by various Git hosting providers. Order matters: more common names come first for prioritized matching.

Functions

func CheckFilesChanged

func CheckFilesChanged(repoPath string, baseRef string, prRef string) ([]string, error)

CheckFilesChanged returns the list of changed file paths between two refs by generating a patch diff. It is used to short‑circuit expensive dependency analysis when go.mod and go.sum are unchanged.

func CloneContext

func CloneContext(ctx context.Context, dir string, opts *gitlib.CloneOptions) (*gitlib.Repository, func(), error)

CloneContext clones a repository into dir using a filesystem storage that keeps file descriptors open for faster object access. The caller must invoke the returned cleanup function to release resources when done.

func GetDefaultBranch

func GetDefaultBranch(repo *git.Repository) (string, error)

GetDefaultBranch attempts to find the repository's default branch using multiple strategies.

func GetReferenceSuggestions

func GetReferenceSuggestions(repo *git.Repository, invalidRef string) []string

GetReferenceSuggestions provides helpful suggestions for similar reference names.

func InstallSafeGitTransport

func InstallSafeGitTransport()

InstallSafeGitTransport registers SSRF-protected HTTP transports as the default for all go-git operations.

This affects the global go-git transport registry. After calling this, all go-git HTTP(S) operations will use SafeDialer to validate resolved IP addresses, preventing DNS rebinding attacks.

This function is called automatically via init(), but can be called explicitly if needed (e.g., after tests that modify the transport registry).

func InstallSafeGitTransportWithOptions

func InstallSafeGitTransportWithOptions(opts ...network.Option)

InstallSafeGitTransportWithOptions registers SSRF-protected transports with custom options.

func NewSafeGitTransport

func NewSafeGitTransport() transport.Transport

NewSafeGitTransport returns a go-git transport.Transport that uses SafeDialer for SSRF protection. This prevents DNS rebinding attacks by validating resolved IP addresses at connection time.

Use this transport with go-git operations that handle user-controlled URLs, especially in server mode where targets come from untrusted sources.

Note: The safe transport is installed globally via init(), so this function is primarily useful for explicit transport configuration in tests or when creating custom git clients.

func NewSafeGitTransportWithOptions

func NewSafeGitTransportWithOptions(opts ...network.Option) transport.Transport

NewSafeGitTransportWithOptions returns a go-git transport.Transport with custom SafeDialer options.

func NormalizeGitRefForGoGit

func NormalizeGitRefForGoGit(ref string) string

NormalizeGitRefForGoGit converts common time shorthands within Git revision expressions into ISO-8601 timestamps accepted by go-git. If no recognizable shorthand is present, the input is returned unchanged.

func ParseReferences

func ParseReferences(repoPath string, args []string, matcher PathMatcher) (baseRef, targetRef string, err error)

ParseReferences intelligently parses command line arguments to determine base and target references. It supports all Git reference types: branches, tags, commits, remote refs, and Git revision expressions. Dependency-related decisions (e.g., whether to compare with WORKING) are aided by the provided matcher.

func ParseTimeShorthandToISO

func ParseTimeShorthandToISO(expr string) string

ParseTimeShorthandToISO parses simple time shorthands and returns an RFC3339 UTC timestamp. Supported forms:

• "now"
• "yesterday"
• "<n>.<unit>.ago" where unit in {second(s), minute(s), hour(s), day(s), week(s), month(s), year(s)}

func ReadFileAtCommit

func ReadFileAtCommit(repo *git.Repository, hash plumbing.Hash, path string) ([]byte, error)

ReadFileAtCommit retrieves the contents of a file at a specific commit. It returns an empty byte slice if the file does not exist or an error occurs.

func ResolveReferenceName

func ResolveReferenceName(ctx context.Context, remoteURL string, auth transport.AuthMethod, refStr string) (plumbing.ReferenceName, error)

ResolveReferenceName resolves a user-provided ref to a full ref name. It consults the remote to determine a default branch when refStr is empty.

func ResolveRevisionEnhanced

func ResolveRevisionEnhanced(repo *git.Repository, ref string) (*plumbing.Hash, error)

ResolveRevisionEnhanced resolves Git revisions with support for time-based selectors of the form "<ref>@{<timestamp>}" where <timestamp> is either RFC3339 or one of the supported shorthands handled by ParseTimeShorthandToISO. If a time selector is present, the function walks the commit history from <ref> backwards to find the newest commit whose commit time is <= the timestamp, and returns its hash. If no time selector is present, this defers to go-git's ResolveRevision. For CI environments (GitHub Actions, etc.), if a simple branch name fails to resolve, it will also try origin/<branch> as a fallback.

func ToHTTPSGitURL

func ToHTTPSGitURL(ref string) string

ToHTTPSGitURL converts a repository reference into an HTTPS URL with a .git suffix.

Types

type PathMatcher

type PathMatcher interface {
	Matches(path string) bool
}

PathMatcher reports whether a path should be treated as a dependency manifest.