Documentation
¶
Overview ¶
Package tree re-cuts the release branch.
The release branch is machine-owned output. It is not kept up to date with its target — it is CUT FROM it on every run, which is spec 0001 D7 and the reason a release merge request can never be behind. Nothing survives between runs, so there is no state that can drift.
The clone is in-memory: no working copy to be dirty, no checkout on the wrong branch, and nothing left behind by a previous failure.
Index ¶
- Variables
- type Author
- type CheckoutSpec
- type ContainsRequest
- type File
- type FileRequest
- type Option
- type Recut
- type Recutter
- func (r *Recutter) Checkout(ctx context.Context, spec CheckoutSpec) (string, error)
- func (r *Recutter) Contains(ctx context.Context, req ContainsRequest) (bool, error)
- func (r *Recutter) Do(ctx context.Context, spec Recut) (Result, error)
- func (r *Recutter) FileAt(ctx context.Context, req FileRequest) ([]byte, error)
- func (r *Recutter) ResolveTag(ctx context.Context, req TagLookup) (string, error)
- func (r *Recutter) Tag(ctx context.Context, spec TagSpec) (TagResult, error)
- type Result
- type TagLookup
- type TagResult
- type TagSpec
Constants ¶
This section is empty.
Variables ¶
var ( // ErrMissingField reports a required input absent from a [Recut]. // // Exported so a caller — and a test — can distinguish colophon refusing // the request from git refusing it. Several of these guards duplicate a // refusal go-git would also make: an empty commit, for instance. The // duplication is deliberate, because go-git's message describes a git // operation rather than the missing release input that caused it. ErrMissingField = errors.New("release branch: missing required field") // ErrInvalid reports an input that is present but cannot be used. ErrInvalid = errors.New("release branch: invalid input") // ErrPushNotLanded reports a push go-git called up to date while the // remote's branch is not at the release commit. ErrPushNotLanded = errors.New("release branch: the push sent nothing and the remote is elsewhere") )
var ( // ErrTagMoved reports a tag that already exists on a DIFFERENT commit. // // Not the same thing as re-running a release. Re-tagging the same commit is // idempotent and fine; a tag pointing somewhere else means two artefacts // would answer to one version, and that must stop the release rather than // be papered over. ErrTagMoved = errors.New("release tag: already exists on a different commit") // ErrFileNotFound reports a path absent at the requested commit. ErrFileNotFound = errors.New("release tree: file not found at commit") )
var ErrTagNotFound = errors.New("release tag: not found on the remote")
ErrTagNotFound reports a tag the remote does not carry.
Functions ¶
This section is empty.
Types ¶
type Author ¶
Author signs the release commit. Both fields are required: go-git otherwise falls back to ambient git configuration, which would make the commit depend on whichever machine happened to run it.
type CheckoutSpec ¶ added in v0.3.0
type CheckoutSpec struct {
Remote string
Target string
Tag string
// Dir is where the clone is written. The caller owns it, and its
// lifetime: nothing here removes it.
Dir string
}
CheckoutSpec asks for a working clone of Target, detached at Tag, in Dir.
type ContainsRequest ¶ added in v0.3.0
ContainsRequest asks whether the target branch carries a commit.
type File ¶
File is one path written into the release commit. Path is slash-separated and relative to the repository root; parent directories are created.
type FileRequest ¶
FileRequest names one file at one commit.
type Option ¶
type Option func(*Recutter)
Option configures a Recutter.
func WithSettings ¶
WithSettings supplies the go/repo settings used to authenticate the clone and the push. The zero value authenticates nothing, which is what local fixtures need and what a public repository accepts.
type Recut ¶
type Recut struct {
// Remote is the clone location — a URL, or a local path in tests.
Remote string
// Target is the branch the release branch is cut FROM, e.g. "main".
Target string
// Branch is the release branch, replaced wholesale on every run.
Branch string
// Files are written into the release commit, replacing what the target
// carried at those paths.
Files []File
Message string
Author Author
// Now, when set, fixes the commit timestamp. Left zero, the current time is
// used. Tests set it so a commit hash is reproducible.
Now func() object.Signature
}
Recut describes one re-cut of the release branch.
type Recutter ¶
type Recutter struct {
// contains filtered or unexported fields
}
Recutter re-cuts the release branch from its target.
func (*Recutter) Checkout ¶ added in v0.3.0
Checkout clones the target branch with its tags into spec.Dir and detaches at the tag, returning the tagged commit.
On disk rather than in memory because what reads it next walks a path: go/changelog opens a repository by location and walks from its HEAD, which is why HEAD is put at the tag rather than at the branch tip. Spec 0005 D4.
func (*Recutter) Contains ¶ added in v0.3.0
Contains reports whether Commit is reachable from the head of Target.
Spec 0005 D2. A commit the clone does not hold is not contained, and one it holds is checked by ancestry rather than by presence, so the answer does not rest on what a single-branch fetch happened to bring.
func (*Recutter) Do ¶
Do re-cuts the release branch and force-pushes it.
The force-push is correct rather than a smell: the branch is regenerated from the target and the release inputs, and nothing a human wrote lives on it that is not also a commit on the target.
func (*Recutter) FileAt ¶
FileAt reads a file as it was at a commit.
At the COMMIT, not at the branch head: after a release lands, more commits arrive on the target, and reading the head would describe a different release from the one being published.
func (*Recutter) ResolveTag ¶ added in v0.3.0
ResolveTag returns the full SHA of the commit a tag points at, whether the tag is annotated or lightweight.
type Result ¶
type Result struct {
// Commit is the release commit that was pushed.
Commit string
// Base is the target head it was cut from — the release commit's only
// parent, and what `propose` reports so a reader can see which target
// state the proposal describes.
Base string
}
Result reports what a re-cut wrote.
type TagLookup ¶ added in v0.3.0
TagLookup names a tag on a remote, and the branch to clone to find it.
type TagResult ¶
type TagResult struct {
// Created is false when the tag was already there on the same commit,
// which is a successful no-op rather than a failure.
Created bool
// Tag is the tag object's own hash when this run created it.
Tag string
}
TagResult reports what tagging did.
type TagSpec ¶
type TagSpec struct {
// Remote is the clone location.
Remote string
// Target is the branch carrying Commit. The clone fetches it, so the
// commit is reachable.
Target string
// Name is the tag, e.g. "v1.2.3".
Name string
// Commit is the full SHA the tag points at — the commit that actually
// landed, resolved against the target branch.
Commit string
Message string
Author Author
}
TagSpec describes the release tag.