Version
in package
What is running, and where its source lives.
Read from files, since the runtime image ships no git binary: a release archive's own stamp (written by git on
export, see .gitattributes), else the commit in .git. The parsers take contents, not paths, so they are tested
without a repository.
Table of Contents
Constants
- HASH : mixed = '/^[0-9a-f]{40}$/'
- A full SHA-1 commit hash.
Methods
- fromGit() : string
- The commit a checkout is on, read from its `.git`.
- gitdir() : string
- The git directory that the `.git` file of a worktree or a submodule points to.
- head() : string
- Where `HEAD` points: the commit itself when detached, else the ref it names.
- packedRef() : string
- The commit a ref points to in `packed-refs`, which lists one `<hash> <ref>` per line.
- running() : string
- The running version, read from the tree.
- sourcePath() : string
- The repository path holding the running source.
- stampField() : string
- One field of a `VERSION` stamp.
- path() : string
- A path as written in git's own files: absolute, or relative to the directory holding that file.
- read() : string
- A file's contents, or '' when it is not a readable file.
Constants
HASH
A full SHA-1 commit hash.
private
mixed
HASH
= '/^[0-9a-f]{40}$/'
Methods
fromGit()
The commit a checkout is on, read from its `.git`.
public
static fromGit(string $root) : string
Tags are not resolved: the hash already names the exact source, and matching tags would mean peeling annotated ones.
Parameters
- $root : string
-
The checkout root.
Return values
string —An abbreviated commit hash, or 'unknown'.
gitdir()
The git directory that the `.git` file of a worktree or a submodule points to.
public
static gitdir(string $link, string $root) : string
Parameters
- $link : string
-
The contents of that
.gitfile, agitdir: <path>line. - $root : string
-
The checkout root, which a relative path is resolved against.
Return values
string —The git directory, or '' when the file names none.
head()
Where `HEAD` points: the commit itself when detached, else the ref it names.
public
static head(string $head) : string
Parameters
- $head : string
-
The contents of
HEAD.
Return values
string —A full commit hash, a ref such as 'refs/heads/main', or '' when it is neither.
packedRef()
The commit a ref points to in `packed-refs`, which lists one `<hash> <ref>` per line.
public
static packedRef(string $packed, string $ref) : string
Parameters
- $packed : string
-
The contents of
packed-refs. - $ref : string
-
A full ref name, for example 'refs/heads/main'.
Return values
string —The full commit hash, or '' when the ref is not listed.
running()
The running version, read from the tree.
public
static running([string|null $root = null ]) : string
Parameters
- $root : string|null = null
-
The installation root; the one holding this file by default.
Return values
string —A version as git describe writes it, an abbreviated commit hash, or 'unknown'.
sourcePath()
The repository path holding the running source.
public
static sourcePath(string $version) : string
The AGPL asks for the source of the running version: a tag links to its release, but a version past a tag
(v0.1-7-gabcdef0) or without one links to its commit.
Parameters
- $version : string
-
A version string as
VERSIONcarries it, or 'unknown'.
Return values
string —A path under the repository: 'releases/tag/v0.1', 'commit/abcdef0', or '' (the repository root) when the version is unknown.
stampField()
One field of a `VERSION` stamp.
public
static stampField(string $stamp, string $field) : string
Parameters
- $stamp : string
-
The contents of
VERSION. - $field : string
-
The field name, 'describe' or 'commit'.
Return values
string —The stamped value, or '' when the field is missing or still holds git's $Format:...$
placeholder.
path()
A path as written in git's own files: absolute, or relative to the directory holding that file.
private
static path(string $path, string $base) : string
Parameters
- $path : string
-
The path as written.
- $base : string
-
The directory a relative path starts from.
Return values
string —The absolute path as is, a relative one joined to $base.
read()
A file's contents, or '' when it is not a readable file.
private
static read(string $file) : string
Parameters
- $file : string
-
Path to the file.
Return values
string —Its contents, or ''.