clover

command module
v0.3.12 Latest Latest
Warning

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

 Go to latest Published: Jul 13, 2026 License: MIT Imports: 2 Imported by: 0

README

🍀 Clover

Clover keeps version references in a codebase synchronized with their upstream sources of truth. Annotate a line with a clover: comment describing where its version comes from, and Clover resolves the latest matching version and rewrites the line in place. It works across Dockerfiles, YAML, HCL, shell, Markdown, and any other text format.

Installation

macOS / Linux

brew install gechr/tap/clover

Windows

scoop bucket add gechr https://github.com/gechr/scoop-bucket
scoop install gechr/clover

Go

go install github.com/gechr/clover@latest

Quick Start

Place a clover: annotation in a comment next to the line you want kept up to date:

# clover: provider=github repository=redis/redis constraint=minor
FROM redis:7.2.0

Then resolve and update every annotation in place:

clover init        # create a starter .clover.yaml interactively
clover run         # resolve references and update them in place
clover run -n      # dry-run: resolve and preview, write nothing
clover lint        # check every directive resolves, offline, no writes
clover format      # canonicalize directive comments
clover annotate    # preview @clover directives for recognized lines
clover annotate -w # write those annotations

By default, lines without a clover: comment are never touched.

Providers

Clover resolves versions from a range of upstream sources:

  • crates - Rust crate versions from crates.io
  • docker - image tags and digests from any OCI registry
  • gitea - Gitea and Forgejo forges, defaulting to Codeberg
  • github - releases and tags, with checksum and commit-SHA pinning
  • gitlab - project tags and releases
  • go - Go toolchain versions from go.dev
  • hashicorp - Terraform, Vault, Consul, Nomad, and other HashiCorp tools from releases.hashicorp.com
  • helm - chart versions from HTTP or OCI repositories
  • http - any endpoint, read with jq or a regular expression
  • manual - a hand-maintained value for other directives to follow
  • node - Node.js runtime versions from nodejs.org
  • npm - package versions from registry.npmjs.org
  • pypi - Python package versions from pypi.org
  • python - Python runtime versions from python.org
  • rust - Rust toolchain versions, stable or beta channel
  • swift - Swift toolchain versions from swift.org
  • terraform / opentofu - provider plugins from a registry
  • zig - Zig toolchain versions from ziglang.org

A bare # @clover comment (shorthand for provider=auto) infers the right provider from the line itself, so common cases such as GitHub Actions, FROM images, go.mod, and Terraform blocks need no provider at all.

Documentation

Full documentation is available at gechr.github.io/clover.

Documentation

Overview

Command clover keeps version references in a codebase synchronized with their upstream sources of truth.

Source Files

View all Source files

Directories

Path Synopsis
internal
attest
Package attest verifies Sigstore bundles for pinned artifact digests.
 Package attest verifies Sigstore bundles for pinned artifact digests.
auth
Package auth reports credential status for the providers a run uses.
 Package auth reports credential status for the providers a run uses.
checksum
Package checksum sources a sha256 for a value=sha256 follower.
 Package checksum sources a sha256 for a value=sha256 follower.
command
Package command implements the clover CLI: argument parsing and dispatch to the run, lint, and format modes.
 Package command implements the clover CLI: argument parsing and dispatch to the run, lint, and format modes.
comment
Package comment recognizes host-language comment syntaxes (#, //, <!-- -->) so directives are found in any text file.
 Package comment recognizes host-language comment syntaxes (#, //, <!-- -->) so directives are found in any text file.
config
Package config loads and validates Clover's optional YAML configuration.
 Package config loads and validates Clover's optional YAML configuration.
console
Package console renders engine progress at the CLI edge.
 Package console renders engine progress at the CLI edge.
constant
Package constant holds clover's shared string vocabulary - the literal spellings of directive grammar that appear across more than one package (constraint keywords now; provider names, source selectors, and value kinds as they land).
 Package constant holds clover's shared string vocabulary - the literal spellings of directive grammar that appear across more than one package (constraint keywords now; provider names, source selectors, and value kinds as they land).
dates
directive
Package directive scans for the clover: keyword and parses the key=value grammar (quote-on-demand) into an ordered Directive.
 Package directive scans for the clover: keyword and parses the key=value grammar (quote-on-demand) into an ordered Directive.
display
Package display formats resolved values for human-facing output.
 Package display formats resolved values for human-facing output.
exec
Package exec schedules markers over the follow-edge dependency DAG: topological order, stable-sorted ready set, cycle detection, capped parallelism.
 Package exec schedules markers over the follow-edge dependency DAG: topological order, stable-sorted ready set, cycle detection, capped parallelism.
forge
Package forge holds provider-agnostic helpers shared by forge providers - Gitea/Forgejo today, GitHub Enterprise and self-managed GitLab in future: host parsing, same-origin checks, and OAuth PKCE/Link primitives.
 Package forge holds provider-agnostic helpers shared by forge providers - Gitea/Forgejo today, GitHub Enterprise and self-managed GitLab in future: host parsing, same-origin checks, and OAuth PKCE/Link primitives.
httpcache
Package httpcache provides a caching http.RoundTripper that sits beneath the providers: they use an ordinary *http.Client and never manage caching themselves.
 Package httpcache provides a caching http.RoundTripper that sits beneath the providers: they use an ordinary *http.Client and never manage caching themselves.
ignore
Package ignore matches paths against the ignore files that apply to them, for use as scan's ignore predicate.
 Package ignore matches paths against the ignore files that apply to them, for use as scan's ignore predicate.
infer
Package infer bridges auto-detection and the provider registry: it decides whether a line Clover recognizes would actually resolve, offline.
 Package infer bridges auto-detection and the provider registry: it decides whether a line Clover recognizes would actually resolve, offline.
jq
Package jq compiles jq programs, so the gojq parse-then-compile pair lives in one place for every caller that queries JSON - the http provider's extractor and the sidecar locator alike.
 Package jq compiles jq programs, so the gojq parse-then-compile pair lives in one place for every caller that queries JSON - the http provider's extractor and the sidecar locator alike.
log/field
Package field defines the structured-log field names clover logs with, so a key is spelled identically everywhere and a misspelling is a compile error.
 Package field defines the structured-log field names clover logs with, so a key is spelled identically everywhere and a misspelling is a compile error.
logger
Package logger centralizes configuration of the process-wide clog logger for the CLI, layered on top of conductor's defaults.
 Package logger centralizes configuration of the process-wide clog logger for the CLI, layered on top of conductor's defaults.
match
Package match holds the Rewriter seam (Locate + Render -> edit-set) and its dispatch table: the smart rewriter plus the action-pin rewriter for SHA-pinned uses: lines.
 Package match holds the Rewriter seam (Locate + Render -> edit-set) and its dispatch table: the smart rewriter plus the action-pin rewriter for SHA-pinned uses: lines.
mode
Package mode implements run, lint, and format over the shared pipeline, differing only in network use and what (if anything) is written.
 Package mode implements run, lint, and format over the shared pipeline, differing only in network use and what (if anything) is written.
model
Package model defines the shared domain types: Directive, Target, Marker (lifecycle), Candidate (rich: Commit/sha256), and Result.
 Package model defines the shared domain types: Directive, Target, Marker (lifecycle), Candidate (rich: Commit/sha256), and Result.
oci
Package oci is a small client for the OCI distribution (registry v2) protocol: listing a repository's tags, resolving a tag's manifest digest, and answering the bearer-token challenge a registry returns on the first unauthenticated request.
 Package oci is a small client for the OCI distribution (registry v2) protocol: listing a repository's tags, resolving a tag's manifest digest, and answering the bearer-token challenge a registry returns on the first unauthenticated request.
output
Package output defines the detail level of a clover report.
 Package output defines the detail level of a clover report.
pattern
Package pattern is clover's one matching grammar, shared by every directive that accepts a pattern (include/exclude, verify-branch, checksum, find): a value bracketed by / is a strict RE2 regex; any other value is a glob with *, ?, and <placeholders>.
 Package pattern is clover's one matching grammar, shared by every directive that accepts a pattern (include/exclude, verify-branch, checksum, find): a value bracketed by / is a strict RE2 regex; any other value is a glob with *, ?, and <placeholders>.
pipeline
Package pipeline orchestrates the phases (discover -> parse -> validate -> prepare -> execute -> report) and defines the Executor, Mode, and Reporter seams.
 Package pipeline orchestrates the phases (discover -> parse -> validate -> prepare -> execute -> report) and defines the Executor, Mode, and Reporter seams.
progress
Package progress is the engine-facing seam for reporting the live state of a batch of concurrent work - one task per unit (a marker resolving).
 Package progress is the engine-facing seam for reporting the live state of a batch of concurrent work - one task per unit (a marker resolving).
provider
Package provider defines the Provider interface, the compiled-in registry (init self-registration), and optional capabilities (Anchorer, Digester, Linker, Committer, BranchChecker, Authenticator).
 Package provider defines the Provider interface, the compiled-in registry (init self-registration), and optional capabilities (Anchorer, Digester, Linker, Committer, BranchChecker, Authenticator).
provider/all
Package all is the composition helper that constructs every built-in provider.
 Package all is the composition helper that constructs every built-in provider.
provider/crates
Package crates resolves Rust crate versions from the crates.io registry API.
 Package crates resolves Rust crate versions from the crates.io registry API.
provider/docker
Package docker resolves container image versions from a registry's tags, using Docker Hub's API for hub.docker.com and the OCI registry v2 bearer-token challenge elsewhere, piggybacking on the user's existing docker login for credentials.
 Package docker resolves container image versions from a registry's tags, using Docker Hub's API for hub.docker.com and the OCI registry v2 bearer-token challenge elsewhere, piggybacking on the user's existing docker login for credentials.
provider/follow
Package follow implements the follow provider: reuses another marker's resolved Candidate (via from=) from the registry and renders a value (version/commit/sha256).
 Package follow implements the follow provider: reuses another marker's resolved Candidate (via from=) from the registry and renders a value (version/commit/sha256).
provider/gitea
Package gitea resolves versions from a Gitea or Forgejo forge's tags and releases.
 Package gitea resolves versions from a Gitea or Forgejo forge's tags and releases.
provider/github
Package github resolves versions from GitHub releases/tags, enriches candidates with commit SHAs, and sources checksums via an ordered chain.
 Package github resolves versions from GitHub releases/tags, enriches candidates with commit SHAs, and sources checksums via an ordered chain.
provider/gitlab
Package gitlab resolves versions from a GitLab project's tags or releases, enriching candidates with the commit SHA the REST API returns for free.
 Package gitlab resolves versions from a GitLab project's tags or releases, enriching candidates with the commit SHA the REST API returns for free.
provider/golang
Package golang resolves Go toolchain versions from the official go.dev download index.
 Package golang resolves Go toolchain versions from the official go.dev download index.
provider/hashicorp
Package hashicorp resolves HashiCorp tool versions (Terraform, Vault, Consul, Nomad, Packer, Boundary, Sentinel, ...) from HashiCorp's public, unauthenticated releases API.
 Package hashicorp resolves HashiCorp tool versions (Terraform, Vault, Consul, Nomad, Packer, Boundary, Sentinel, ...) from HashiCorp's public, unauthenticated releases API.
provider/helm
Package helm resolves Helm chart versions from both classic HTTP chart repositories (an index.yaml served under the repo URL) and OCI registries (oci://, where a chart's versions are the repository's tags).
 Package helm resolves Helm chart versions from both classic HTTP chart repositories (an index.yaml served under the repo URL) and OCI registries (oci://, where a chart's versions are the repository's tags).
provider/http
Package http resolves versions from an arbitrary HTTP endpoint, the escape hatch for any source clover has no bespoke provider for.
 Package http resolves versions from an arbitrary HTTP endpoint, the escape hatch for any source clover has no bespoke provider for.
provider/manual
Package manual implements a human-owned root provider.
 Package manual implements a human-owned root provider.
provider/node
Package node resolves Node.js runtime versions from nodejs.org's public, unauthenticated release index.
 Package node resolves Node.js runtime versions from nodejs.org's public, unauthenticated release index.
provider/npm
Package npm resolves npm package versions from an npm registry.
 Package npm resolves npm package versions from an npm registry.
provider/pypi
Package pypi resolves Python package versions from the official PyPI JSON API.
 Package pypi resolves Python package versions from the official PyPI JSON API.
provider/python
Package python resolves CPython releases from the official python.org downloads API.
 Package python resolves CPython releases from the official python.org downloads API.
provider/rust
Package rust resolves Rust toolchain versions from the official static.rust-lang.org manifest index.
 Package rust resolves Rust toolchain versions from the official static.rust-lang.org manifest index.
provider/swift
Package swift resolves Swift toolchain versions from the official swift.org release index.
 Package swift resolves Swift toolchain versions from the official swift.org release index.
provider/terraform
Package terraform resolves Terraform provider versions from a registry implementing the provider registry protocol.
 Package terraform resolves Terraform provider versions from a registry implementing the provider registry protocol.
provider/zig
Package zig resolves Zig toolchain versions from the official ziglang.org download index.
 Package zig resolves Zig toolchain versions from the official ziglang.org download index.
ratelimit
Package ratelimit provides an http.RoundTripper that respects an API's rate limit headers.
 Package ratelimit provides an http.RoundTripper that respects an API's rate limit headers.
regexlit
Package regexlit defines clover's /regex/ literal syntax: a value bracketed by slashes is a regular expression, anything else is not.
 Package regexlit defines clover's /regex/ literal syntax: a value bracketed by slashes is a regular expression, anything else is not.
registry
Package registry is the run-scoped store mapping id -> resolved Candidate, enabling follow markers to reuse producers' results.
 Package registry is the run-scoped store mapping id -> resolved Candidate, enabling follow markers to reuse producers' results.
report
Package report renders mode summaries to the user through clog: per-marker lines with smart file:line hyperlinks, plus a closing summary.
 Package report renders mode summaries to the user through clog: per-marker lines with smart file:line hyperlinks, plus a closing summary.
report/github
Package github builds GitHub Actions workflow-command annotations - the ::error/::warning/::notice lines a workflow parses from a step's output to surface a message inline on a pull request.
 Package github builds GitHub Actions workflow-command annotations - the ::error/::warning/::notice lines a workflow parses from a step's output to surface a message inline on a pull request.
rule
Package rule compiles a directive's selection-policy keys (constraint, include/exclude, prerelease, cooldown, behind, downgrade) into the options the version selection chain consumes.
 Package rule compiles a directive's selection-policy keys (constraint, include/exclude, prerelease, cooldown, behind, downgrade) into the options the version selection chain consumes.
scan
Package scan walks the requested paths and discovers the files that contain a clover: directive.
 Package scan walks the requested paths and discovers the files that contain a clover: directive.
sidecar
Package sidecar carries the format-agnostic logic for YAML sidecar files: the <target>.clover.yaml (or .yml) that holds update rules for a target that cannot host an inline clover: comment, strict JSON being the canonical case.
 Package sidecar carries the format-agnostic logic for YAML sidecar files: the <target>.clover.yaml (or .yml) that holds update rules for a target that cannot host an inline clover: comment, strict JSON being the canonical case.
tag
Package tag parses and evaluates the --tag marker filter.
 Package tag parses and evaluates the --tag marker filter.
token
Package token persists the access tokens clover mints (e.g.
 Package token persists the access tokens clover mints (e.g.
tools/genmise command
Command genmise generates the maps the match package's auto-detection uses to resolve a mise tool name to the upstream whose versions it tracks.
 Command genmise generates the maps the match package's auto-detection uses to resolve a mise tool name to the upstream whose versions it tracks.
tui
Package tui holds the charmbracelet-based interactive surfaces (the clover init wizard).
 Package tui holds the charmbracelet-based interactive surfaces (the clover init wizard).
vcs
Package vcs resolves the version-controlled repository a file belongs to, so clover can namespace id= per repository: the same id in two different repositories is not a clash.
 Package vcs resolves the version-controlled repository a file belongs to, so clover can namespace id= per repository: the same id in two different repositories is not a clash.
version
Package version parses/compares semver, evaluates constraints (keyword bumps + Terraform ranges), and runs the candidate-selection filter chain.
 Package version parses/compares semver, evaluates constraints (keyword bumps + Terraform ranges), and runs the candidate-selection filter chain.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.