tree

package
v0.21.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 14 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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")
)
View Source
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")
)
View Source
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

type Author struct {
	Name  string
	Email string
}

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

type ContainsRequest struct {
	Remote string
	Target string
	Commit string
}

ContainsRequest asks whether the target branch carries a commit.

type File

type File struct {
	Path    string
	Content []byte
}

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

type FileRequest struct {
	Remote string
	Branch string
	Commit string
	Path   string
}

FileRequest names one file at one commit.

type Option

type Option func(*Recutter)

Option configures a Recutter.

func WithSettings

func WithSettings(s repo.Settings) Option

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 New

func New(opts ...Option) *Recutter

New returns a Recutter.

func (*Recutter) Checkout added in v0.3.0

func (r *Recutter) Checkout(ctx context.Context, spec CheckoutSpec) (string, error)

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

func (r *Recutter) Contains(ctx context.Context, req ContainsRequest) (bool, error)

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

func (r *Recutter) Do(ctx context.Context, spec Recut) (Result, error)

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

func (r *Recutter) FileAt(ctx context.Context, req FileRequest) ([]byte, error)

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

func (r *Recutter) ResolveTag(ctx context.Context, req TagLookup) (string, error)

ResolveTag returns the full SHA of the commit a tag points at, whether the tag is annotated or lightweight.

func (*Recutter) Tag

func (r *Recutter) Tag(ctx context.Context, spec TagSpec) (TagResult, error)

Tag creates the release tag at spec.Commit and pushes it.

Idempotent for the same commit: `publish` runs on every merge to the target branch and a pipeline retried by hand is ordinary, so a second run reports that it did nothing rather than failing.

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

type TagLookup struct {
	Remote string
	Target string
	Name   string
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL