git_versions.h Header

#include <git_versions.h>

Types

struct SemVer A plain X.Y.Z version. Parse rejects everything else (v-prefixes, pre-release suffixes, partial versions): the tag list treats those as not-a-version and skips them.
struct TagInfo One usable tag from the repo: its name, parsed number, and creation date pretty-printed to the config style ("September 3, 2026" — creatordate covers annotated and lightweight tags alike).
struct BuildProvenance
struct BuiltVersion One versions/<label>/ dir beside the config, as its provenance describes it. A dir with neither a tag nor a preview has no readable provenance.
struct VersionSources Everything the derivation merges. Assembled by the caller so the function itself stays pure (fixture-testable without git or a filesystem).
struct VersionRow One table row: a major.minor site version, collapsed from that minor's tags (the highest patch wins — superseded patches never appear anywhere).
struct LatestVersion Which version fronts the project.

Type Aliases

using GitRunner Runs git with the given argv (argv[0] is "git"), collecting combined stdout+stderr as lines. Returns the exit code; -1 means git could not be run at all. Injected everywhere so tests substitute fixtures.

Enums

enum class VersionStatus
enum class SupportStatus How a published version stands. Only the latest is supported unless the project lists more in versions_supported[]. An archived version still publishes, and its doc pages say that it is archived.

Functions

bool parse_semver(const std::string & text, SemVer & out)
int parse_tag_list(const int & lines, std::size_t * ignored = nullptr)
std::string pretty_date(const std::string & iso_date)
GitRunner make_system_git_runner()
int git_tag_list_argv(const std::string & repo_dir)
int git_worktree_add_argv(const std::string & repo_dir, const std::string & worktree_dir, const std::string & tag)
int git_worktree_remove_argv(const std::string & repo_dir, const std::string & worktree_dir)
int git_worktree_prune_argv(const std::string & repo_dir)
int git_rev_parse_argv(const std::string & repo_dir, const std::string & tag)
bool list_repo_tags(const GitRunner & run, const std::string & repo_dir, int & out, std::size_t * ignored = nullptr, std::string * error = nullptr)
bool write_build_provenance(const std::filesystem::path & version_dir, const BuildProvenance & provenance, std::string * error = nullptr)
bool read_build_provenance(const std::filesystem::path & version_dir, BuildProvenance & out, std::string * error = nullptr)
int read_built_versions(const std::filesystem::path & config_dir)
int excluded_version_labels(const int & project_config)
int supported_version_labels(const int & project_config)
int derive_version_rows(const VersionSources & sources)
bool version_label_newer(const std::string & a, const std::string & b)
bool is_version_label(const std::string & label)
int published_versions(const int & built, const int & excluded)
LatestVersion derive_latest_version(const int & published)
int version_support(const int & published, const int & supported)

Type Alias Documentation

using GitRunner = std::function<int (const int &, int &)>

Runs git with the given argv (argv[0] is "git"), collecting combined stdout+stderr as lines. Returns the exit code; -1 means git could not be run at all. Injected everywhere so tests substitute fixtures.

Enum Documentation

enum class VersionStatus

Constant Description
Excluded listed in versions_excluded[] (unchecked, dimmed)
Pending included but not current: unbuilt, provenance unknown, or patched since build (stale says which of those it is)
Complete included and built from this minor's latest tag
Preview included working-tree build of a minor with no tag

enum class SupportStatus

How a published version stands. Only the latest is supported unless the project lists more in versions_supported[]. An archived version still publishes, and its doc pages say that it is archived.

Constant Description
Latest the newest published version (derive_latest_version)
Supported listed in versions_supported[]
Archived every other published version

Function Documentation

bool parse_semver(const std::string & text, SemVer & out)

No description available.

int parse_tag_list(const int & lines, std::size_t * ignored = nullptr)

Parse git for-each-ref output lines ("\t", the tag_list_argv format below). Lines that aren't plain-semver tags are skipped; *ignored (when non-null) counts them so callers can advanced-log what the table won't show.

std::string pretty_date(const std::string & iso_date)

Pretty-print an ISO "YYYY-MM-DD" date to the config style ("March 26, 2026"; English month names so it can't drift with the system locale). Anything unparseable passes through verbatim rather than failing.

GitRunner make_system_git_runner()

The real thing: shell out via popen (_popen on Windows), stderr merged. Only the CLI should ever invoke this — see the header comment.

int git_tag_list_argv(const std::string & repo_dir)

argv builders — one place spells each git command so the CLI, the tests, and the docs can't drift on the exact invocation.

int git_worktree_add_argv(const std::string & repo_dir, const std::string & worktree_dir, const std::string & tag)

No description available.

int git_worktree_remove_argv(const std::string & repo_dir, const std::string & worktree_dir)

No description available.

int git_worktree_prune_argv(const std::string & repo_dir)

No description available.

int git_rev_parse_argv(const std::string & repo_dir, const std::string & tag)

No description available.

bool list_repo_tags(const GitRunner & run, const std::string & repo_dir, int & out, std::size_t * ignored = nullptr, std::string * error = nullptr)

List a repo's usable tags: run tag_list_argv through the runner and parse. Returns false with *error filled (when non-null) if git couldn't run or the command failed (e.g. not a git repository — git's own message is passed through so the caller can surface the real reason).

bool write_build_provenance(const std::filesystem::path & version_dir, const BuildProvenance & provenance, std::string * error = nullptr)

Write versions_dir/

bool read_build_provenance(const std::filesystem::path & version_dir, BuildProvenance & out, std::string * error = nullptr)

Read a version dir's provenance. False when missing, unparseable, a too-new format, or naming neither a tag nor a preview. Output without readable provenance doesn't publish, and its row reads Pending when the minor has a tag.

int read_built_versions(const std::filesystem::path & config_dir)

Scan config_dir/versions into BuiltVersion entries (read_build_provenance per dir), sorted by label.

int excluded_version_labels(const int & project_config)

A project config's versions_excluded[] labels (non-strings skipped).

int supported_version_labels(const int & project_config)

A project config's versions_supported[] labels (non-strings skipped).

int derive_version_rows(const VersionSources & sources)

Merge tags × exclusions × built output into display rows, newest first. A tagged minor is included unless versions_excluded[] lists it, and reads Pending until its built provenance matches the minor's latest tag. Built output whose minor has no tag gets a row too: Preview for a working-tree build, Complete (flagged tag_missing) for a tag build whose tag is gone. Untagged dirs without readable provenance get no row.

bool version_label_newer(const std::string & a, const std::string & b)

True when major.minor label a is newer than b. A label that isn't major.minor is older than any that is, and never newer than another one.

bool is_version_label(const std::string & label)

True for a major.minor site label ("2.1"), the name every versions/

int published_versions(const int & built, const int & excluded)

What the site publishes: the built versions with readable provenance (tag builds and previews) that excluded doesn't list, newest first (unorderable labels sink below any orderable one).

LatestVersion derive_latest_version(const int & published)

The newest of published (published_versions order). Building a new version thus fronts it automatically; rebuilding an old one never does.

int version_support(const int & published, const int & supported)

The status of each version in published (published_versions order), returned in that same order. The first is Latest even when supported lists it, and labels in supported that aren't published are ignored. For example, published 3.0, 2.1, 2.0 with supported {"2.1", "1.0"} gives {Latest, Supported, Archived}.
Appearance
Theme
—