tree

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Aug 30, 2026 License: MIT Imports: 13 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")
)
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")
)

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 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) 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) 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 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