Documentation
¶
Overview ¶
Package git contains shared git helpers used by both the skills importer (pkg/skills) and the MCP server source builder (pkg/builder).
The helpers are thin wrappers over go-git that factor out duplicated clone/fetch/checkout logic. They do not know anything about gridctl's cache layout or authentication strategy: callers compute destination paths and pass in a transport.AuthMethod (or nil).
Index ¶
- Variables
- func Checkout(repo *gogit.Repository, ref string) error
- func ClassifyError(err error) error
- func Clone(destPath string, opts CloneOptions, logger *slog.Logger) (*gogit.Repository, error)
- func Fetch(repoPath string, opts FetchOptions, logger *slog.Logger) error
- func HeadCommit(repoPath string) (string, error)
- func ListTags(repoPath string) ([]string, error)
- func Open(repoPath string) (*gogit.Repository, error)
- func RedactError(err error) error
- func RedactString(s string) string
- func RedactURL(raw string) string
- func ResolveRef(repo *gogit.Repository, ref string) (string, error)
- type Auther
- type CloneOptions
- type FetchOptions
- type HTTPSTokenAuth
- type NoAuth
- type Protocol
- type SSHAgentAuth
- type SSHKeyFileAuth
Constants ¶
This section is empty.
Variables ¶
var ( // ErrAuthRequired: the remote rejected the request because no // credentials were presented. ErrAuthRequired = errors.New("authentication required") // ErrAuthFailed: credentials were presented but rejected. ErrAuthFailed = errors.New("authentication failed") // ErrNotFound: the remote returned a "not found" response. On hosts // like GitHub this may also mean a private repository accessed without // sufficient credentials. ErrNotFound = errors.New("repository not found") // ErrHostKeyMismatch: the SSH host key did not match the local // known_hosts — a potential man-in-the-middle indicator. ErrHostKeyMismatch = errors.New("ssh host key mismatch") // ErrSSHAgentMissing: ssh-agent was unavailable (socket missing or // SSH_AUTH_SOCK unset) when SSH-agent auth was requested. ErrSSHAgentMissing = errors.New("ssh agent not available") // ErrEmptyToken: a token-based Auther was constructed with an empty // token. Reported eagerly rather than falling through to an // unauthenticated clone that then fails with a cryptic error. ErrEmptyToken = errors.New("token is empty") // ErrProtocolMismatch: an Auther was asked to produce credentials for // a URL whose protocol does not match the auth mechanism (e.g., an // HTTPS token against an SSH URL). ErrProtocolMismatch = errors.New("protocol mismatch") )
Sentinel errors classify git-operation failures so callers can render actionable UI messages without string-matching raw go-git output.
Functions ¶
func Checkout ¶
func Checkout(repo *gogit.Repository, ref string) error
Checkout lands the worktree on ref, trying in order: tag, local branch, remote branch (origin), commit hash. Force is used so uncommitted changes in the worktree (unlikely in a cache) are discarded.
func ClassifyError ¶
ClassifyError maps raw go-git (or network) errors to sentinels in this package, wrapping the original so errors.Is / errors.As still find it. Unknown errors are returned unchanged — the caller is free to wrap them with its own context.
func Clone ¶
func Clone(destPath string, opts CloneOptions, logger *slog.Logger) (*gogit.Repository, error)
Clone performs a plain git clone into destPath. When Ref is set it first attempts a single-branch clone of that ref (as a branch); if that fails it removes destPath and retries with a full clone. Callers are responsible for a subsequent Checkout when they need to land on a non-branch ref (tag, commit, remote branch) after the full-clone fallback.
func Fetch ¶
func Fetch(repoPath string, opts FetchOptions, logger *slog.Logger) error
Fetch updates the cached repository at repoPath from its remote. Returns nil if the remote had no new refs.
func HeadCommit ¶
HeadCommit returns the HEAD commit hash for the repository at repoPath.
func Open ¶
func Open(repoPath string) (*gogit.Repository, error)
Open is a thin wrapper around gogit.PlainOpen. It lets callers avoid importing go-git directly for routine repository access.
func RedactError ¶
RedactError returns an error whose message has been scrubbed of credential-shaped content. The original error is preserved via Unwrap so errors.Is / errors.As continue to work as expected. Returns nil when err is nil, and returns err unchanged when the message does not contain any redactable content.
func RedactString ¶
RedactString scrubs known token patterns and URL userinfo from arbitrary text. Use it on strings whose construction you do not fully control, e.g. error messages returned from go-git.
func RedactURL ¶
RedactURL returns a version of raw with any userinfo stripped.
https://TOKEN@host/path → https://host/path git@host:path → git@host:path (SCP-style, unchanged) non-URL text → unchanged
func ResolveRef ¶
func ResolveRef(repo *gogit.Repository, ref string) (string, error)
ResolveRef returns the commit hash for ref by consulting, in order: tag, remote branch (origin), local branch.
Types ¶
type Auther ¶
type Auther interface {
AuthFor(url string) (transport.AuthMethod, error)
}
Auther returns a transport.AuthMethod appropriate for the given URL. A nil AuthMethod with a nil error means "no credentials required"; a non-nil error surfaces misconfiguration (wrong protocol, missing agent, empty token) so callers don't silently fall through to an unauthenticated clone that then fails with a cryptic "repository not found".
type CloneOptions ¶
type CloneOptions struct {
URL string
Ref string // if set and branch-style, attempted as single-branch clone first
Depth int // 0 = full history
AllTags bool // fetch all tags
Auth transport.AuthMethod // nil = unauthenticated
}
CloneOptions configures a Clone call.
type FetchOptions ¶
type FetchOptions struct {
AllTags bool
Auth transport.AuthMethod
}
FetchOptions configures a Fetch call.
type HTTPSTokenAuth ¶
type HTTPSTokenAuth struct {
Token string
}
HTTPSTokenAuth sends a Personal Access Token as HTTP basic-auth username with an empty password — the shape GitHub, GitLab, Bitbucket, and most self-hosted servers accept for PAT-based authentication.
func (HTTPSTokenAuth) AuthFor ¶
func (a HTTPSTokenAuth) AuthFor(url string) (transport.AuthMethod, error)
AuthFor returns an *http.BasicAuth carrying the PAT, or an error if the token is empty or the URL is not HTTPS.
type NoAuth ¶
type NoAuth struct{}
NoAuth produces no credentials for any URL. Use it for public repositories or when ambient go-git mechanisms handle auth transparently.
type Protocol ¶
type Protocol string
Protocol describes how a git URL is accessed.
func DetectProtocol ¶
DetectProtocol classifies a git remote URL by its scheme.
type SSHAgentAuth ¶
type SSHAgentAuth struct {
User string
}
SSHAgentAuth delegates authentication to the user's running ssh-agent. The User field defaults to "git" when empty.
func (SSHAgentAuth) AuthFor ¶
func (a SSHAgentAuth) AuthFor(url string) (transport.AuthMethod, error)
AuthFor returns a PublicKeysCallback backed by the ambient ssh-agent, or ErrSSHAgentMissing if no agent socket is available.
type SSHKeyFileAuth ¶
type SSHKeyFileAuth struct {
User string
KeyPath string
Passphrase string
KnownHostsPath string // reserved for a follow-up change
}
SSHKeyFileAuth authenticates using an on-disk private key file. The User field defaults to "git" when empty.
Host-key verification uses go-git's default behavior for this PR; a stricter TOFU / accept-new host-key policy and explicit KnownHostsPath handling will be wired through in a follow-up change. KnownHostsPath is reserved for that future work.
func (SSHKeyFileAuth) AuthFor ¶
func (a SSHKeyFileAuth) AuthFor(url string) (transport.AuthMethod, error)
AuthFor loads the private key file and returns an SSH PublicKeys auth.
Source Files