Documentation
¶
Overview ¶
Package gitrepo keeps a local, bare copy of a git remote and answers questions about its commits.
It is transport plumbing, not domain logic: it fetches, resolves commits, and computes merge bases, but never decides what those facts mean. A reader that derives change metadata — files, line counts, author — drives a copy through this package and interprets the raw git output itself.
The copy is bare because nothing here checks anything out, so there is no working tree to leave dirty and no index to corrupt. Git commands against one copy cannot safely interleave, so a Repo carries a lock (it embeds sync.Mutex) that every reader sharing the copy holds across a sequence of commands. Command environment and git-binary resolution come from platform/git/exec, the one source of truth every git caller shares.
Index ¶
- func SetConfig(ctx context.Context, path, key, value string) error
- type Auth
- type Repo
- func (r *Repo) EnsureCommit(ctx context.Context, sha, ref string) error
- func (r *Repo) FetchTarget(ctx context.Context) error
- func (r *Repo) HasCommit(ctx context.Context, sha string) bool
- func (r *Repo) MergeBase(ctx context.Context, a, b string) (string, error)
- func (r *Repo) Provision(ctx context.Context) error
- func (r *Repo) Remote() string
- func (r *Repo) RunRaw(ctx context.Context, args ...string) (string, error)
- func (r *Repo) Target() string
- type RepoConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Auth ¶
type Auth interface {
// Apply configures repoPath so that git commands run against remoteURL from
// inside it can authenticate.
Apply(ctx context.Context, repoPath, remoteURL string) error
}
Auth prepares a local repository to authenticate to its remote.
This package never decides what a credential is, where it comes from, or how long it lives. An integrator wires an implementation in — reading an environment variable, calling a secrets manager, minting a short-lived token — and only that implementation changes when the answer does.
Apply runs immediately before every fetch rather than once at provisioning, so an implementation backed by an expiring credential can refresh it. It must therefore be cheap and idempotent.
A nil Auth means the remote needs none, which covers a local path and an SSH remote served by the host's own SSH configuration and agent.
type Repo ¶
Repo is one local, bare copy of a remote, shared by every reader built over it. The embedded mutex serializes git commands against the copy; a reader holds it across any sequence that must see a consistent object set.
func NewRepo ¶
func NewRepo(cfg RepoConfig) (*Repo, error)
NewRepo returns a Repo for cfg, resolving the git binary. It touches no disk; Provision does that.
func (*Repo) EnsureCommit ¶
EnsureCommit guarantees sha is present locally, fetching if it is not.
By SHA first, which needs the server to allow a want for an object it does not advertise (github.com does); the change's own ref is the fallback for a server that does not. Neither is shallow — a merge base needs ancestry.
func (*Repo) FetchTarget ¶
FetchTarget updates the target branch, which is the baseline a change's first commit is measured from and moves as other changes land.
func (*Repo) MergeBase ¶
MergeBase returns the commit two revisions diverged from. Absence of one is reported as an error rather than an empty diff: a change sharing no history with what it claims to land on is a fact worth surfacing, not a change that touches nothing.
func (*Repo) Provision ¶
Provision creates the copy if it is not already there and points it at the remote, leaving an existing copy's objects alone.
Callers run this at wiring time rather than on first use: a reader is often resolved once per message on a retry-driven path, so a copy created there would put a clone inside a retry loop and hide a bad remote behind queue processing rather than failing the service that owns it.
type RepoConfig ¶
type RepoConfig struct {
// Git is the path to the git binary. Empty resolves through GIT_EXECUTABLE
// and then PATH.
Git string
// Path is where this copy lives on disk. It belongs to one owner: another
// reader of the same remote keeps its own.
Path string
// RemoteURL is where the copy fetches from — a URL or a local path.
RemoteURL string
// Remote is the name the copy records RemoteURL under.
Remote string
// Target is the branch a change's diff is measured against.
Target string
// Auth prepares the copy to reach RemoteURL. Nil when it needs nothing.
Auth Auth
}
RepoConfig describes one local copy of a remote.
Source Files