Documentation
¶
Overview ¶
Package gitexec wraps the system git binary. gitdr shells out to real git for faithful clone/bundle semantics (and later git-lfs). Auth is injected via GIT_CONFIG_* env, scoped to the clone host, so tokens never reach argv.
Index ¶
- func LFSAvailable() bool
- type BundleRef
- type Git
- func (g *Git) BundleAll(ctx context.Context, repoDir, bundlePath string) error
- func (g *Git) BundleHeads(ctx context.Context, bundlePath string) ([]BundleRef, error)
- func (g *Git) BundleVerify(ctx context.Context, bundlePath string) error
- func (g *Git) CloneFromBundle(ctx context.Context, bundlePath, dir string) error
- func (g *Git) CloneMirror(ctx context.Context, repoURL, dir string, opts Options) error
- func (g *Git) HasRefs(ctx context.Context, repoDir string) (bool, error)
- func (g *Git) HeadOID(ctx context.Context, repoDir string) (string, error)
- func (g *Git) LFSCheckout(ctx context.Context, repoDir string) error
- func (g *Git) LFSFetchAll(ctx context.Context, repoDir, repoURL string, opts Options) error
- func (g *Git) LFSInstallLocal(ctx context.Context, repoDir string) error
- func (g *Git) LFSPointersRemaining(ctx context.Context, repoDir string) ([]string, error)
- func (g *Git) ListRefs(ctx context.Context, repoDir string) (map[string]string, error)
- func (g *Git) LsRemote(ctx context.Context, repoURL string, opts Options) (map[string]string, error)
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LFSAvailable ¶
func LFSAvailable() bool
LFSAvailable reports whether the git-lfs binary is installed.
Types ¶
type BundleRef ¶ added in v0.1.13
type BundleRef struct {
// Name is a full ref name such as "refs/heads/main" or "refs/tags/v1", or the literal
// "HEAD". A bundle written with `bundle create --all HEAD` carries a HEAD entry, which
// is not a ref any repository stores under refs/; callers normalise it.
Name string
// OID is the object the bundle declares for Name, exactly as recorded. For an annotated
// tag this is the tag object, not the commit it peels to.
OID string
}
BundleRef is one entry from a bundle's header: a name the bundle declares and the object it points at.
type Git ¶
type Git struct {
// contains filtered or unexported fields
}
Git runs git subcommands.
func (*Git) BundleAll ¶
BundleAll bundles every ref plus HEAD inside repoDir so `git clone <bundle>` checks out the default branch on restore.
func (*Git) BundleHeads ¶ added in v0.1.13
BundleHeads returns the ref-to-object map the bundle itself declares.
This is the other half of the restore proof. The signed manifest fixes the bundle's bytes; this says which refs those bytes claim to carry. Because git is content-addressed, a commit id transitively covers its tree, its blobs and its whole ancestry, so comparing these against the refs a restored repository actually has is not a sample of the history, it is exact equality of it.
func (*Git) BundleVerify ¶
BundleVerify runs `git bundle verify bundlePath` from a scratch repository.
It reads the bundle's header — format, prerequisites, refs — and stops, so it is a structural check and not an integrity one. Integrity is the SHA-256 the restore path compares against the sidecar and the signed manifest before git is asked anything.
func (*Git) CloneFromBundle ¶
CloneFromBundle restores a repo by cloning from a bundle file.
--origin is pinned rather than left to default. `clone.defaultRemoteName` in an operator's ~/.gitconfig renames the remote, and with it the whole refs/remotes/<name>/* namespace that a clone files every branch under. That would make the shape of a restore depend on the machine it ran on, and the ref comparison — which looks for a declared branch under refs/heads/X or refs/remotes/origin/X — report a perfectly good restore as missing every branch but one. Same reasoning as the local LFS filters: in a disaster the machine is new, and a restore must not depend on how it happens to be configured.
func (*Git) CloneMirror ¶
CloneMirror runs `git clone --mirror url dir`.
func (*Git) HasRefs ¶ added in v0.1.7
HasRefs reports whether repoDir contains at least one ref.
A repository created and never pushed to has none, and `git bundle create` refuses to write an empty bundle: "fatal: Refusing to create empty bundle." Without this check that refusal reads as a failed repository, and one unused project in an organisation is enough to make every backup of it fail for ever.
Asked of the local mirror rather than the provider's API, because it is the state that actually matters: a clone that produced no refs is what bundling has to cope with, whatever the API said. `git clone --mirror` fails loudly on a partial fetch, so zero refs after a successful clone means the remote genuinely has none.
func (*Git) HeadOID ¶ added in v0.1.13
HeadOID resolves repoDir's HEAD to the object it points at. It fails on an unborn HEAD, which for a repository cloned from a non-empty bundle cannot happen.
func (*Git) LFSCheckout ¶
LFSCheckout materializes LFS files in the working tree from local objects (no network).
func (*Git) LFSFetchAll ¶
LFSFetchAll downloads all LFS objects referenced by any ref into repoDir, reusing the clone's host-scoped auth.
func (*Git) LFSInstallLocal ¶ added in v0.1.5
LFSInstallLocal writes the lfs clean/smudge filters into repoDir's own config.
A repository cloned from a bundle has no filter.lfs.* configuration, and without it "git lfs checkout" exits 0 and does nothing — the working tree keeps 130-byte pointer files. That makes a successful restore depend on whether the operator had already run "git lfs install" on the machine, which in a disaster is exactly the machine that is new.
--skip-repo, because a restored copy needs the filters, not the pre-push hook.
func (*Git) LFSPointersRemaining ¶ added in v0.1.5
LFSPointersRemaining lists tracked paths that are still pointer files.
Checked rather than assumed: "git lfs checkout" reports success whether or not it replaced anything, so its exit code says a command ran, not that the bytes are there. This reads the working tree back and is what lets restore fail instead of handing over pointers.
func (*Git) ListRefs ¶ added in v0.1.13
ListRefs returns every ref in repoDir mapped to the object it points at.
%(objectname) is the ref's own target and not the peeled one. A bundle header records an annotated tag as its tag object, so the two compare directly; peeling here (%(*objectname)) would compare a tag against the commit under it and accept a repository whose tag object had been replaced with a different one over the same commit.
func (*Git) LsRemote ¶ added in v0.1.13
func (g *Git) LsRemote(ctx context.Context, repoURL string, opts Options) (map[string]string, error)
LsRemote asks the remote what refs it has, without cloning anything.
This is the cheap half of not rewriting a repository that has not changed. One network round trip, no objects transferred, no working tree, and the answer is the same shape ListRefs returns for a local repository.
`--symref` is deliberately absent: the symbolic target of HEAD is a property of the remote's configuration and not of its history, so a repository whose default branch was renamed with no commits since has not changed in any sense that matters to a backup, and including it would force a full rewrite of every repository in an organisation the day somebody renames master to main.
The peeled `^{}` lines are dropped for the reason ListRefs does not peel: an annotated tag compares as its tag object, so a tag object swapped over the same commit is a change.
Source Files