history

package
v0.16.2 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package history reads a repository and produces exactly what a version decision needs: where the project is now, and what has landed since.

This is the seam where I/O enters. Everything above it — package policy — is pure, which is what makes the decision testable as a table and reviewable without running anything. Keeping the git in one narrow place is what buys that.

Index

Constants

View Source
const FirstVersion = "0.0.0"

FirstVersion is where a project with no releases starts.

A repository with no semver tag has no current version, so one has to be chosen rather than discovered. 0.0.0 is the choice, which means the first release is decided by its commits exactly as every later one is: a feat makes it 0.1.0, a fix makes it 0.0.1.

The alternative — defaulting the first release to 0.1.0 whatever landed — was rejected because it makes the first release the one release whose number nobody can explain from the log.

Variables

View Source
var (
	// ErrTagNotFound reports a release tag the repository does not carry.
	ErrTagNotFound = errors.New("release tag not found")

	// ErrNotAVersion reports a tag that does not name a semantic version.
	ErrNotAVersion = errors.New("tag is not a version")

	// ErrNotAtTag reports a checkout whose HEAD is not the tagged commit. The
	// commits are walked from HEAD, so anywhere else would describe a
	// different release from the one named.
	ErrNotAtTag = errors.New("HEAD is not at the release tag")
)
View Source
var ErrAmbiguousLatest = errors.New("ambiguous latest release")

ErrAmbiguousLatest reports two reachable tags that compare equal under semver precedence but exclude different commits — "v1.0.0+a" and "v1.0.0+b". There is no highest, and choosing one silently changes what the release contains.

View Source
var ErrNoComponent = errors.New("no component")

ErrNoComponent reports a ReadComponent call with nothing to read.

View Source
var ErrNoSuchCommit = errors.New("commit not found")

ErrNoSuchCommit reports a span endpoint the repository does not carry.

View Source
var ErrNotARepository = errors.New("not a git repository")

ErrNotARepository reports a path that is not a git repository.

View Source
var ErrShallowClone = errors.New("this checkout is shallow (depth-limited clone)")

ErrShallowClone reports a depth-limited checkout. Whether such a clone holds enough history to answer correctly changes with every commit that lands, so it is refused before the walk rather than after the walk happens to fail.

View Source
var ErrUnresolvableHEAD = errors.New("HEAD cannot be resolved")

ErrUnresolvableHEAD reports a repository that has history its HEAD cannot reach. Reporting it as empty would compute a release from thin air.

Functions

func Root added in v0.5.0

func Root(path string) (string, error)

Root resolves the working-tree root of the repository at path, which is where the manifest is read from. A caller with components reads the manifest before it can say what Read should exclude, so the root is resolved on its own first.

func TagAge added in v0.11.0

func TagAge(path, tag string, now time.Time) (time.Duration, error)

TagAge reports how long ago a tag was made.

An annotated tag carries its own timestamp; a lightweight one is a pointer, so its age is its commit's. Both are close enough for the question this answers: has this tag had long enough for its release to have appeared.

Types

type Component added in v0.5.0

type Component struct {
	Dir       string
	TagPrefix string
}

Component is what history needs to read a directory with a version of its own (spec 0010 D2). TagPrefix is the component's tag template rendered with an empty version: "lint/v" for the default shape, "capabilitygen-v" for a `{name}-v{version}` template. Every tag it writes ends in the version, so the prefix is the whole rule.

type Landed added in v0.6.0

type Landed struct {
	SHA string

	// Body is everything below the subject line, which is where git looks for
	// a trailer block. The subject is deliberately not included: a one-line
	// commit would otherwise offer `feat: something` as its last paragraph.
	Body string
}

Landed is one commit a push added, reduced to what a merge-time reader needs: which commit it was, and the body its trailers are in.

func Between added in v0.6.0

func Between(path, before, to string) ([]Landed, error)

Between reads the commits a push added: those reachable from to and not from before, newest first.

This is the merge-time span, and it is not the release span. `plan` and `propose` ask what has landed since the last release; a run acting on what a person wrote in a commit must see exactly what this push carried, or a weekly-releasing repository would act on the whole week again on every merge (spec 0012 D6).

An empty or all-zero before is the first push to a branch, where a forge has no previous commit to name: the span is `to` alone, rather than the repository's entire history.

type Option added in v0.5.0

type Option func(*scope)

Option narrows what Read considers.

func Excluding added in v0.5.0

func Excluding(dirs ...string) Option

Excluding leaves out the commits that touch only the given directories: the root of a repository with components owns everything outside them (spec 0010 D2, on spec 0008 D1). A commit touching a component and a shared file stays in the root's range.

func Under added in v0.9.0

func Under(s policy.Scheme) Option

Under names the version scheme the repository's tags are written in. Absent — or nil, which a caller that never heard of schemes passes — tags are read as semver, which is every repository in the estate but one (spec 0016).

The caller supplies it because the scheme comes from the manifest, and this package does not read the manifest.

type Range

type Range struct {
	// Dir is the component's directory, empty for the root (spec 0010 D2).
	Dir string

	// Root is the repository's working-tree root, resolved by walking up from
	// the supplied path.
	//
	// Anything else read per-repository — the manifest above all — must use
	// this rather than the path the caller happened to pass, or `plan -C
	// ./subdir` reads the same history with the manifest silently missing.
	Root string

	// Current is the latest released version, or the scheme's first when
	// there are none.
	Current policy.Version

	// FromTag is the tag Current came from. Empty when the project has never
	// released, which is what distinguishes "no releases" from "released 0.0.0".
	FromTag string

	// Commits are those not yet in any release, newest first.
	Commits []policy.Commit
}

Range is a repository reduced to what a decision needs.

func Read

func Read(path string, opts ...Option) (Range, error)

Read opens the repository at path and reduces it to a Range.

func ReadComponent added in v0.5.0

func ReadComponent(path string, c Component) (Range, error)

ReadComponent reduces one component to a Range: its current version is the highest reachable tag carrying its prefix, and its commits are those since that tag whose diff touches its directory.

The same walk as the root's, with the tag rule and the path filter swapped: the root refuses any tag with a slash and reads everything outside the components; a component reads only tags with its prefix and only the commits under it. Neither can read the other's tags, because the manifest refuses a template the root could read and refuses two that render alike.

func (Range) HasReleased

func (r Range) HasReleased() bool

HasReleased reports whether the project has ever cut a release.

type Released added in v0.3.0

type Released struct {
	Range

	Tag     string
	Version policy.Version
	Commit  string
}

Released is one named release and the range of history it covers.

Current and FromTag describe the release BEFORE this one, and Commits are what this release added on top of it: the same shape Read gives for a release that has not happened yet, for a release that has.

func ReadComponentRelease added in v0.5.0

func ReadComponentRelease(path, tagName string, c Component) (Released, error)

ReadComponentRelease is ReadRelease for a component's tag: the previous release is the highest reachable tag with the component's prefix strictly below this one, and the commits are those between that touch its directory (spec 0011 D4, on spec 0010 D2).

func ReadRelease added in v0.3.0

func ReadRelease(path, tagName string, opts ...Option) (Released, error)

ReadRelease reduces the repository at path to the range a named release covers: from the highest reachable semver tag strictly below it, to the tagged commit. HEAD must be that commit.

Spec 0005 D4. Strictly below, because on a checkout of the tag the highest reachable tag is the tag itself and the range would be empty. The ambiguity refusal is inherited from Read for the reason it exists there.

Jump to

Keyboard shortcuts

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