.\" Shadows openssl man page 1ssl version
.\"
.TH version "February 2014" "BSD/Linux" "User Manuals"
.SH NAME
version \- copy version numbers across source code files
.SH SYNOPSIS
.B version
[
.BI action " file.name"
] [
.B action
] [
.IB "file.name " action
]
.SH DESCRIPTION
version is a commandline tool to extract version numbers from source
code files, optionally modify it, write it back to source code, or
synchronize package build scripts.
It's regex based, and looks for the common x.y.z version style, including
build/patch suffixes. For reading and writing from and to source code
it considers file extensions to infer the type and constrained context /
syntax to modify.
.SH OPTIONS
Action names may be prepended with a single - or double -- dash.
.PP
.B File actions
Every valid filename will be treated as such. The order of action
and filename is insignificant for those actions that consume it.
.TP
.BI get " file.name"
Reads and prints version number from source file.
.TP
.BI read " file.name"
Just reads a version number from source code. Does not print it.
.TP
.BI write " file.name"
Updates a file. Depending on file type inserts the currently
proccessed version number into appropriate code context / syntax.
.TP
.IB ... " last"
Reuses the last consumed filename with a new action. For instance
.BI read " file1.c " "write last"
will update to where the read action did previously load from.
.PP
.B Version data
After reading from a file, the version number is kept as current
value for further actions.
.TP
.RB - show
Outputs the version number.
.TP
.RB - incr / ++
Increments the decimal after the last version dot (commonly understood as
the patch version). For instance 0.0.x or 0.0.0.y
.TP
.RB - bump
Adds or increments the build suffix, as in x.x.x-1
.br
Additional alphanumeric suffixes or subversioning schemes may occur
thereafter, like 1.2.3-1dev_2 or 3.5-0beta_2.7, and are ignored by
the -bump action. Also allows a
.BI bump :: 2
count argument.
.TP
.IR 1 . 2 . 3 - 0alpha
Any commandline argument that matches the common numeric version
number format will be understood as current version, for later
modification or writing elsewhere.
.PP
.B Miscellaneous options
File actions may be preceded by a -format option, which takes
two optional arguments separated by
.BR : colons.
And in addition to filenames, version numbers itself can be input sources.
.TP
.RB - format : name
Specifies a file type or regex name. The type may be any known
file extension, a list of file extensions, or an internal format
name specifying just one constrained regex context / code syntax.
.TP
.RB - format :: count
The second option rules on how many regex replacements in a target file
may occur. Which constrains the default mode to just replacing the first
allowed format and version number. It's useful to allow updating two
occurences in different
.BR --format : "docblock,var" : 2
variations and locations.
Actually the --format action is a virtual action. And the optional
arguments may as well be merged into
.BR write : fmt : cnt
or
.BR read : fmt
actions.
.TP
.RB - dry / nowrite
This is a debugging option, which wakes writing operations non-destructive;
but just outputs the modified target file.
.SH EXAMPLES
.TP
.IB version " get" " file.c"
Reads from filename and outputs found version number.
.TP
.IB version " read" " file.c" " write" " dist/header.c"
Looks for the first version number, and writes it to another file
where appropriate syntax was found.
.TP
.IB version " read" " file.php" " ++ write" " file.php"
Increments patch version number, and updates file.
.TP
.IB version " -read" " file.php" " -incr -bump -write" : "_raw_" : 2 " readme.txt"
Reads from source, updates patch version and release suffix, then writes
to a text file using the _raw_ format (any version number without context
checks will be updated) two times.
.TP
.IB "version src/file.php" " read and then " src/out.c " write
The order of read/write actions and filenames may be reversed, "and" and
"then" are just filler no-op commands.
.LP
.LP
.IB VERSION=$( "version get file.name" )
.br
.BI version " $VERSION " "write file.name"
.in +.8i
The version tool is meant to be utilized from build preparation scripts.
While both actions can be done in one call, it's sometimes useful to keep
the current $VERSION number in shell context (e.g. for adapting output
filenames).
.TP
.IB version " get:php" " /usr/bin/version"
Just shows the version of the version tool.
.SH FORMATS
.TP
.RI "Common file extensions " php ", " py ", " cpp ", " c ", " json ", " sh ", " xml ", " spec " are understood and mapped already to " some " of the internal context / syntax formats (as implemented per regex):"
.PP
.TS
allbox;
lb cb cb
li l l.
Format Name Description Common Pattern
debian DEB package control Version: 1.0.0
rpmspec RPM package spec %version 1.0.0
plugin Generic meta block T{
/**
* version: 1.0.0
T}
docblock Documentation * @version 1.0.0
const Constant declarations const VERSION = '1.0.0';
var Scripting language syntax $Xyz_version = "1.0.0";
define PHP constant defines define("XYZ_VERSION", '1.0.0');
ini Configuration files version = "1.0.0"
python Module numbers __version__ = "1.0.0"
composer JSON { "version": "1.0.0",
wordpress Wordpress plugin meta Version: 1.0.0
xmltag Single XML tag <version>1.0.0</version>
_raw_ \fBmatch anything\fR T{
This matches virtually anywhere, as it just applies the common
version number syntax regex, but does not take any syntax context into account.
T}
.TE
.PP
.RI "The moniker " any " includes all known regex formats but " _raw_ ", of course."
.SH "SEE ALSO"
.BR "http://semver.org/#" (2.0.0)