semver.1

.Dd February 19, 2019
.Dt SEMVER 1
.Os
.Sh NAME
.Nm semver
.Nd Semantic Versioning utility
.Sh SYNOPSIS
.Nm
.Op Fl hqstw
.Sh DESCRIPTION
The
.Nm
utility is a text filter for Semantic Version strings. It searches text from the standard input, selects any Semantic
Versions that are present, and writes them to the standard output. It can optionally sort or tabulate the selected
versions.
.Pp
A
.Sq version
string will be selected within the text stream if the following criteria are met:
.Bl -bullet -compact
.It
.Sq version
is a valid Semantic Version.
.It
.Sq version
is a whole line. (This can be modified with the
.Fl w
option.)
.El
.Sh OPTIONS
.Pp
The
.Nm
utility understands the following command-line options:
.Bl -tag -width Ds indent
.It Fl h, -help
Display the usage screen.
.It Fl q, -quiet
Quiet mode. Nothing shall be written to the standard output, regardless of matching Semantic Versions. The utility will exit immediately with zero status if a Semantic Version string is selected.
.Pp
Example:
.Pp
.Bd -literal -offset indent
semver -q <<< '1.2.3'    # exit 0
semver -q <<< 'invalid'  # exit >0
.Ed
.It Fl s, -sort
Sort the matched versions in precedence order (low-to-high).
.Pp
Example:
.Pp
.Bd -literal -offset indent
$ semver -s <<EOF
2.2.2
1.1.1
4.4.4
EOF

1.1.1
2.2.2
4.4.4
.Ed
.It Fl t, -tabulate
Tabulate the matched versions (separator: '\\t').
.Pp
Example:
.Pp
.Bd -literal -offset indent
$ semver -t <<EOF
1.0.0
1.0.0-alpha
1.0.0+1
1.0.0-alpha+1
EOF

1   0   0
1   0   0   alpha
1   0   0           1
1   0   0   alpha   1
.Ed
.It Fl w, -word-match
Select words that match the semver pattern. (Equivalent to the
.Xr grep 1
.Fl -word-regexp
option.)
.Pp
Example:
.Pp
.Bd -literal -offset indent
semver -w <<EOF
1.0.0
foo 2.0.0 bar 3.0.0
baz
EOF

1.0.0
2.0.0
3.0.0
.Ed
.El
.Sh EXAMPLES
.Pp
\fBSelect\fR lines that are version strings:
.Pp
.Bd -literal -offset indent -compact
semver < example.txt
.Ed
.Pp
\fBCalculate\fR the next Git tag:
.Pp
.Bd -literal -offset indent -compact
# major++
git tag | semver -st | tail -n 1 | awk -F '\\t' '{ print ++$1 "." 0 "." 0 }'

# minor++
git tag | semver -st | tail -n 1 | awk -F '\\t' '{ print $1 "." ++$2 "." 0 }'

# patch++
git tag | semver -st | tail -n 1 | awk -F '\\t' '{ print $1 "." $2 "." ++$3 }'
.Ed
.Pp
\fBCut\fR out the major, minor, and patch components of versions:
.Pp
.Bd -literal -offset indent -compact
semver -t <<< '1.2.3-alpha+1' | cut -f 1-3
.Ed
.Pp
\fBDownload\fR all artifacts in a version range:
.Pp
.Bd -literal -offset indent -compact
v='0.0.1'
while curl -fs "https://example.com/artifact/$v.tar.gz" > "$v.tar.gz"; do
    v=$(semver -t <<< "$v" | awk -F '\\t' '{ print $1 "." $2 "." ++$3 }')
done
.Ed
.Pp
\fBFind\fR the current Git tag:
.Pp
.Bd -literal -offset indent -compact
git tag | semver -s | tail -n 1
.Ed
.Pp
\fBFormat\fR version strings as CSV:
.Pp
.Bd -literal -offset indent -compact
semver -tw < example.txt | tr '\\t' ','
.Ed
.Pp
\fBValidate\fR a candidate version string:
.Pp
.Bd -literal -offset indent
semver -q <<< $version && echo 'ok'
.Ed
.Sh EXIT STATUS
The
.Nm
utility exits with one of the following values:
.Pp
.Bl -tag -width flag -compact
.It Li 0
One or more Semantic Versions were matched.
.It Li >0
No Semantic Versions were matched, or an error occurred.
.El
.Sh WARNINGS
The Semantic Versioning standard does not define an ordering for two versions that are precedence-equal but stringwise-unequal (for example the BUILD is different). To guarantee predictable ordering between executions, the
.Nm
utility applies an additional natural sort on top of the Semantic Version precedence sort. This additional sort is IMPLEMENTATION-SPECIFIC and SUBJECT TO CHANGE between releases, so its algorithm is deliberately left undocumented. You should not rely on it.
.Sh STANDARDS
The
.Nm
utility is expected to conform to the Semantic Versioning standard, defined at https://semver.org.